Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#1,528 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
48/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
javascript, playwright
Área
documentation

Línea de trabajo

Comienza con la hoja de referencia de Vue Testing Library y compara su tabla Search Type con la guía enlazada Queries — Priority. Revisa los ejemplos de ByLabelText y los enlaces a recursos, y después lee la sección Firing Events junto con las referencias enlazadas de user-event y Vitest browser-mode. Se considera terminado cuando las actualizaciones acordadas de la hoja de referencia se hayan aplicado de forma coherente, sin ampliar la revisión al alcance más general, salvo que se solicite.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
JavaScript
Estrellas
479
Forks
738
Sin PR fusionados en 30 d

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de testing-library/testing-library-docs

Todos los issues de testing-library/testing-library-docs

Issues similares

Más issues de JavaScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.