Mejores prácticas de testing

Un resumen condensado de las 25 mejores prácticas más importantes extraídas de todas las páginas de esta sección.

Prefiere getByRole sobre test IDs: Recorre la prioridad de consultas de Testing Library (getByRole → getByLabelText → getByText → getByTestId) para que las aserciones coincidan con el árbol de accesibilidad; usar getByTestId primero acopla los tests a la implementación y pasa por alto regresiones de a11y.
queryBy para ausencia, getBy para presencia: getBy* lanza una excepción cuando no hay coincidencias y findBy* reintenta, así que solo queryBy* es seguro para aserciones de «no debería existir» — usar getBy* para ausencia produce un error confuso de «no encontrado» en lugar de una aserción fallida clara.
Delimita las consultas con within: Cuando los tests renderizan elementos de lista que comparten etiquetas o botones, envuelve las consultas en within(listItem) (o un aria-label con nombre único) para apuntar exactamente a la fila que quieres en lugar de la primera coincidencia de la página.
Espera (await) cada llamada a userEvent: Cada método de userEvent (v14+) devuelve una Promise, así que olvidar await hace que la siguiente aserción se ejecute antes de que el evento se procese y convierte tests fallidos en falsos positivos silenciosos — siempre await userEvent.click(button).
Prefiere userEvent sobre fireEvent: userEvent.type despacha la secuencia completa focus → keydown → keypress → input → keyup, que es lo que escuchan los componentes y validadores reales; fireEvent.change solo establece el valor y omite los eventos de pulsación de tecla de los que dependen bibliotecas como React Hook Form.
Envuelve Jest con createJestConfig: Exporta tu configuración de Jest a través de createJestConfig de next/jest para obtener gratis las transformaciones SWC, los mocks de módulos CSS y la resolución de env/alias consciente de next.config.js; pon los matchers de jest-dom en setupFilesAfterSetup (no en setupFiles) o las extensiones de expect no estarán en el ámbito.
Configura Vitest explícitamente: Vitest necesita @vitejs/plugin-react para JSX, environment: "jsdom", globals: true, una importación de @testing-library/jest-dom/vitest en el archivo de setup y "vitest/globals" en tsconfig.compilerOptions.types — si falta cualquiera, JSX o los tipos de matchers fallan en silencio.
Usa vi.hoisted para referencias de factory de mocks: vi.mock() se eleva (hoist) por encima de los imports, así que las variables declaradas en el cuerpo del módulo son undefined dentro de la factory; usa vi.hoisted(() => ({ mockPush: vi.fn() })) y referencia esa ref compartida tanto desde la factory como desde tus tests.
Limpia los mocks entre tests: Los valores de retorno y el historial de llamadas de los mocks se filtran entre tests del mismo archivo, así que llama a vi.clearAllMocks() (o jest.clearAllMocks()) en beforeEach; lo mismo aplica a vi.restoreAllMocks() para spies y server.resetHandlers() para MSW.
findBy para aparición, waitFor para estado: Usa findByRole / findByText cuando esperas que aparezca un elemento, y waitFor solo cuando la aserción no es sobre un elemento (p. ej., un contador de llamadas de efecto secundario) — findBy encapsula el reintento y ofrece mejores mensajes de error.
Sin efectos secundarios en waitFor: waitFor sondea su callback cada ~50 ms, así que poner userEvent.click() o un spy de fetch dentro dispara el evento repetidamente y corrompe el state; haz la interacción fuera de waitFor y deja solo las aserciones dentro.
Reinicia MSW entre tests: Llama a server.resetHandlers() en afterEach para que las sobrescrituras por test no se filtren al siguiente, y mantén onUnhandledRequest: "error" para que cualquier endpoint olvidado salga a la superficie de inmediato en lugar de enmascararse como un cuelgue misterioso.
Reinicia el state de Zustand por test: Los stores de Zustand son singletons de módulo, así que el state persiste entre tests del mismo archivo a menos que lo reinicies con useCartStore.setState({ items: [] }) (o getState().reset()) en beforeEach — de lo contrario, las mutaciones de un test presembran invisiblemente el siguiente.
QueryClient nuevo por test: Crea un QueryClient nuevo con retry: false dentro de un helper renderWithProviders para cada test; un cliente compartido cachea respuestas entre tests y cuelga las suites en reintentos fallidos.
Consulta role=alert para errores de RHF: Renderiza los errores de validación con role="alert" para que se anuncien al lector de pantalla y sean consultables como await screen.findAllByRole("alert"); recuerda que React Hook Form valida al enviar por defecto, así que aserciones de errores antes del envío no encuentran nada a menos que configures mode: "onChange".
Mockea useActionState en jsdom: useActionState no puede ejecutar realmente una Server Action bajo jsdom, así que mockea el hook para devolver una tupla controlada [state, formAction, isPending] al probar la UI de error/pendiente del formulario — probar la acción real pertenece a un test de integración en Node/Vitest.
Envuelve las actualizaciones de state del hook en act: En renderHook, cualquier llamada síncrona que provoque una actualización de state necesita act(() => result.current.increment()) o obtienes una advertencia más un result.current obsoleto; con temporizadores falsos, avanza también dentro de act o pasa { shouldAdvanceTime: true }.
No desestructures result.current: result.current es una referencia viva que cambia después de cada renderizado, así que const { count } = result.current captura una instantánea que queda obsoleta — lee siempre result.current.count directamente en cada aserción.
Espera primero los Server Components asíncronos: render() no acepta una Promise, así que prueba Server Components asíncronos llamándolos como funciones y esperando el JSX: const ui = await PostList({ id: "1" }); render(ui); — pasar el componente directamente lanza una excepción.
Mockea next/headers y next/cache: cookies(), headers(), revalidatePath y revalidateTag lanzan excepciones fuera del contexto de petición de Next.js, así que sustitúyelos con vi.mock("next/headers", …) y vi.mock("next/cache", …) — también mockea notFound() para que lance un error centinela y await expect(fn()).rejects.toThrow() funcione.
Usa locators accesibles de Playwright + POM: Prefiere page.getByRole, getByLabel y getByText sobre selectores CSS y encapsúlalos en clases Page Object; selectores CSS como .btn-primary.mt-4 se rompen en cuanto alguien renombra una clase.
Reemplaza waitForTimeout con auto-espera: Las aserciones expect() de Playwright reintentan automáticamente hasta 5 segundos, así que await expect(page).toHaveURL("/dashboard") reemplaza cada page.waitForTimeout(500) — las pausas fijas son la causa n.º 1 de tests E2E inestables.
Arranque automático del servidor + trazas en reintento: Configura webServer en playwright.config.ts para arrancar Next.js automáticamente con reuseExistingServer: !CI, y habilita trace: "on-first-retry" para que las ejecuciones fallidas incluyan una línea de tiempo completa de DOM/red/consola que puedas abrir con playwright show-trace.
Autentica una vez, registra rutas antes de goto: Usa un proyecto setup más storageState: "e2e/.auth/user.json" para que cada test empiece autenticado sin pagar el coste del login, y registra mocks de page.route() antes de page.goto() — las rutas configuradas después de la navegación pierden la carga inicial de la página.
Sigue el Testing Trophy y escribe regresiones: Prioriza comprobaciones estáticas (TypeScript strict, ESLint) y tests de integración primero, usa E2E con moderación para flujos críticos (login, checkout), fija la cobertura cerca del 80 % en lugar de perseguir el 100 %, y escribe un test de regresión por cada bug que corrijas.

Un resumen condensado de las 25 mejores prácticas más importantes extraídas de todas las páginas de esta sección.

Prefiere getByRole sobre test IDs: Recorre la prioridad de consultas de Testing Library (getByRole → getByLabelText → getByText → getByTestId) para que las aserciones coincidan con el árbol de accesibilidad; usar getByTestId primero acopla los tests a la implementación y pasa por alto regresiones de a11y.

queryBy para ausencia, getBy para presencia: getBy* lanza una excepción cuando no hay coincidencias y findBy* reintenta, así que solo queryBy* es seguro para aserciones de «no debería existir» — usar getBy* para ausencia produce un error confuso de «no encontrado» en lugar de una aserción fallida clara.

Delimita las consultas con within: Cuando los tests renderizan elementos de lista que comparten etiquetas o botones, envuelve las consultas en within(listItem) (o un aria-label con nombre único) para apuntar exactamente a la fila que quieres en lugar de la primera coincidencia de la página.

Espera (await) cada llamada a userEvent: Cada método de userEvent (v14+) devuelve una Promise, así que olvidar await hace que la siguiente aserción se ejecute antes de que el evento se procese y convierte tests fallidos en falsos positivos silenciosos — siempre await userEvent.click(button).

Prefiere userEvent sobre fireEvent: userEvent.type despacha la secuencia completa focus → keydown → keypress → input → keyup, que es lo que escuchan los componentes y validadores reales; fireEvent.change solo establece el valor y omite los eventos de pulsación de tecla de los que dependen bibliotecas como React Hook Form.

Envuelve Jest con createJestConfig: Exporta tu configuración de Jest a través de createJestConfig de next/jest para obtener gratis las transformaciones SWC, los mocks de módulos CSS y la resolución de env/alias consciente de next.config.js; pon los matchers de jest-dom en setupFilesAfterSetup (no en setupFiles) o las extensiones de expect no estarán en el ámbito.

Configura Vitest explícitamente: Vitest necesita @vitejs/plugin-react para JSX, environment: "jsdom", globals: true, una importación de @testing-library/jest-dom/vitest en el archivo de setup y "vitest/globals" en tsconfig.compilerOptions.types — si falta cualquiera, JSX o los tipos de matchers fallan en silencio.

Usa vi.hoisted para referencias de factory de mocks: vi.mock() se eleva (hoist) por encima de los imports, así que las variables declaradas en el cuerpo del módulo son undefined dentro de la factory; usa vi.hoisted(() => ({ mockPush: vi.fn() })) y referencia esa ref compartida tanto desde la factory como desde tus tests.

Limpia los mocks entre tests: Los valores de retorno y el historial de llamadas de los mocks se filtran entre tests del mismo archivo, así que llama a vi.clearAllMocks() (o jest.clearAllMocks()) en beforeEach; lo mismo aplica a vi.restoreAllMocks() para spies y server.resetHandlers() para MSW.

findBy para aparición, waitFor para estado: Usa findByRole / findByText cuando esperas que aparezca un elemento, y waitFor solo cuando la aserción no es sobre un elemento (p. ej., un contador de llamadas de efecto secundario) — findBy encapsula el reintento y ofrece mejores mensajes de error.

Sin efectos secundarios en waitFor: waitFor sondea su callback cada ~50 ms, así que poner userEvent.click() o un spy de fetch dentro dispara el evento repetidamente y corrompe el state; haz la interacción fuera de waitFor y deja solo las aserciones dentro.

Reinicia MSW entre tests: Llama a server.resetHandlers() en afterEach para que las sobrescrituras por test no se filtren al siguiente, y mantén onUnhandledRequest: "error" para que cualquier endpoint olvidado salga a la superficie de inmediato en lugar de enmascararse como un cuelgue misterioso.

Reinicia el state de Zustand por test: Los stores de Zustand son singletons de módulo, así que el state persiste entre tests del mismo archivo a menos que lo reinicies con useCartStore.setState({ items: [] }) (o getState().reset()) en beforeEach — de lo contrario, las mutaciones de un test presembran invisiblemente el siguiente.

QueryClient nuevo por test: Crea un QueryClient nuevo con retry: false dentro de un helper renderWithProviders para cada test; un cliente compartido cachea respuestas entre tests y cuelga las suites en reintentos fallidos.

Consulta role=alert para errores de RHF: Renderiza los errores de validación con role="alert" para que se anuncien al lector de pantalla y sean consultables como await screen.findAllByRole("alert"); recuerda que React Hook Form valida al enviar por defecto, así que aserciones de errores antes del envío no encuentran nada a menos que configures mode: "onChange".

Mockea useActionState en jsdom: useActionState no puede ejecutar realmente una Server Action bajo jsdom, así que mockea el hook para devolver una tupla controlada [state, formAction, isPending] al probar la UI de error/pendiente del formulario — probar la acción real pertenece a un test de integración en Node/Vitest.

Envuelve las actualizaciones de state del hook en act: En renderHook, cualquier llamada síncrona que provoque una actualización de state necesita act(() => result.current.increment()) o obtienes una advertencia más un result.current obsoleto; con temporizadores falsos, avanza también dentro de act o pasa { shouldAdvanceTime: true }.

No desestructures result.current: result.current es una referencia viva que cambia después de cada renderizado, así que const { count } = result.current captura una instantánea que queda obsoleta — lee siempre result.current.count directamente en cada aserción.

Espera primero los Server Components asíncronos: render() no acepta una Promise, así que prueba Server Components asíncronos llamándolos como funciones y esperando el JSX: const ui = await PostList({ id: "1" }); render(ui); — pasar el componente directamente lanza una excepción.

Mockea next/headers y next/cache: cookies(), headers(), revalidatePath y revalidateTag lanzan excepciones fuera del contexto de petición de Next.js, así que sustitúyelos con vi.mock("next/headers", …) y vi.mock("next/cache", …) — también mockea notFound() para que lance un error centinela y await expect(fn()).rejects.toThrow() funcione.

Usa locators accesibles de Playwright + POM: Prefiere page.getByRole, getByLabel y getByText sobre selectores CSS y encapsúlalos en clases Page Object; selectores CSS como .btn-primary.mt-4 se rompen en cuanto alguien renombra una clase.

Reemplaza waitForTimeout con auto-espera: Las aserciones expect() de Playwright reintentan automáticamente hasta 5 segundos, así que await expect(page).toHaveURL("/dashboard") reemplaza cada page.waitForTimeout(500) — las pausas fijas son la causa n.º 1 de tests E2E inestables.

Arranque automático del servidor + trazas en reintento: Configura webServer en playwright.config.ts para arrancar Next.js automáticamente con reuseExistingServer: !CI, y habilita trace: "on-first-retry" para que las ejecuciones fallidas incluyan una línea de tiempo completa de DOM/red/consola que puedas abrir con playwright show-trace.

Autentica una vez, registra rutas antes de goto: Usa un proyecto setup más storageState: "e2e/.auth/user.json" para que cada test empiece autenticado sin pagar el coste del login, y registra mocks de page.route() antes de page.goto() — las rutas configuradas después de la navegación pierden la carga inicial de la página.

Sigue el Testing Trophy y escribe regresiones: Prioriza comprobaciones estáticas (TypeScript strict, ESLint) y tests de integración primero, usa E2E con moderación para flujos críticos (login, checkout), fija la cobertura cerca del 80 % en lugar de perseguir el 100 %, y escribe un test de regresión por cada bug que corrijas.

Mejores prácticas de testing

Buscar en la documentación

Mejores prácticas de testing