[Vue Cheatsheet] Suggested updates — with notes on broader docs freshness

Vue Testing Library の cheatsheet から始め、その Search Type テーブルをリンク先の Queries — Priority ガイドと比較します。ByLabelText の例とリソースリンクを確認し、その後、Firing Events セクションを、リンク先の user-event および Vitest browser-mode のリファレンスと併せて読みます。合意した cheatsheet の更新が一貫して適用され、依頼がない限り、より広範なレビューに拡張しなければ完了です。

The Vue Testing Library cheatsheet was last updated on Jul 21, 2021. As this is typically one of the first pages Vue developers visit when getting started with Testing Library, a handful of targeted updates would significantly improve its usefulness. The suggestions below are ordered by perceived priority.

---

1. Search Type table: reorder rows to reflect the documented query priority

The DOM Testing Library docs (Queries — Priority) define a clear recommended hierarchy for query types. The current cheat sheet lists ByRole in seventh position — second-to-last — effectively inverting the hierarchy for readers who encounter this page before the DOM docs.

Suggested order (matching the priority guide):

#	Query type
1	ByRole
2	ByLabelText
3	ByPlaceholderText
4	ByText
5	ByDisplayValue
6	ByAltText
7	ByTitle
8	ByTestId

Reordering the rows to match this hierarchy would make the table self-explanatory without requiring developers to cross-reference a second page.

---

2. ByLabelText: expand DOM examples to cover aria-label and aria-labelledby

The current "DOM example" column shows only:

<label for="element" />

This implies <label for> is the only way to associate a label with an input. In practice, aria-label and aria-labelledby are common — and often the only available — alternatives, especially when working with UI component libraries that render their own label elements internally:

<!-- aria-label — most concise for single elements -->
<input aria-label="Surname" />

<!-- aria-labelledby — when the label text lives elsewhere in the DOM -->
<span id="surname-label">Surname</span>
<input aria-labelledby="surname-label" />

Adding these examples would address one of the most common questions new users have: "Why doesn't getByLabelText find my input?"

---

3. Add links to further resources where relevant

A small number of targeted reference links would connect developers to deeper material without inflating the cheat sheet itself:

Row	Suggested addition
ByRole	Link to MDN: ARIA roles
ByLabelText	Link to MDN: aria-label
Search Variants	Cross-reference to Queries — about for the full API surface

These additions would make the cheat sheet a useful starting point that leads developers to the right deeper reference, rather than a standalone summary that leaves important questions unanswered.

It may also be worth considering whether the "DOM example" cells could be made expandable (e.g. via a disclosure widget) for rows like ByLabelText and ByRole that have multiple valid implementations — keeping the table scannable at a glance while still offering depth on demand. Whether that is feasible given the current site tooling is of course for you to judge.

---

4. Firing Events: recommend @testing-library/user-event and note Vitest browser mode

The "Firing Events" section currently covers only fireEvent. However, @testing-library/user-event (currently v14) has been the recommended approach for user interactions for a long time — it simulates realistic user behaviour by dispatching the full sequence of events a real browser would fire, and performs visibility/interactability checks that fireEvent skips. The cheat sheet would benefit from at least a brief callout, for example:

For most interactions, prefer @testing-library/user-event over fireEvent — it dispatches the full sequence of events a real browser would fire and prevents actions on hidden or disabled elements.

Additionally, for Vitest browser mode users:

Vitest ships its own userEvent API for tests running in browser mode (via @vitest/browser with Playwright or WebdriverIO). Rather than dispatching simulated JS events, it routes interactions through the browser's Chrome DevTools Protocol — making event handling genuinely accurate without requiring @testing-library/user-event:

// Vitest browser mode — real browser events via Playwright CDP
import { userEvent } from "vitest/browser";  // named import

await userEvent.click(button);
await userEvent.tab();

One notable behavioural difference worth documenting: unlike @testing-library/user-event (where userEvent.setup() returns a fresh instance per test), Vitest's userEvent is a singleton — keyboard state (e.g. held modifier keys) persists across calls within the same test.

As Vitest adoption has grown substantially since 2021, a note or See also covering this use case would prevent confusion for the growing number of developers who reach this cheat sheet from a Vitest browser mode context.

---

Broader context: other sections worth reviewing

The four suggestions above are focused on the Vue cheat sheet, but they reflect a wider pattern. A quick pass over the Vue Testing Library docs reveals several other areas where the guidance appears to be meaningfully out of date or incomplete. Noting them here in case it's useful as a starting point for a broader review — they are not blocking requests, just observations, and the maintainers will of course know better than anyone what is already in progress:

Page / Section	Approx. last updated	Key gap
vue-testing-library/setup	—	Almost no content; no working vitest.config.ts example, no jest-dom wiring, no distinction between Jest and Vitest setup flows
ecosystem-jest-dom	Aug 2022	No Vitest setup path at all; predates mainstream Vitest adoption; developers setting up a fresh Vitest project find no usable guidance here
vue-testing-library/examples	May 2025	Uses fireEvent exclusively throughout — contradicting the project's own recommendation to prefer user-event
vue-testing-library/faq	Sep 2025	Covers Vuex but not Pinia (the de facto standard since Vue 3); no guidance on composables or <script setup>
dom-testing-library/intro	Nov 2020	Predates Vitest entirely; implies Jest is the only relevant test runner

Across the Vue docs as a whole, a few topics seem to be absent entirely: TypeScript examples, Vue 3 <script setup> syntax, Pinia integration, and any mention of Vitest browser mode (@vitest/browser). Given that vue-testing-library/intro and vue-testing-library/api were both updated in December 2025, it seems like there is active maintenance — so hopefully some of the above are already on the radar.

---

I'd be happy to contribute a PR for any or all of these. Let me know which direction you'd prefer.