theus-cli-linux-arm64 0.2.84

package/vendor/theus-arsenal/skills/testing-react/SKILL.md

@@ -0,0 +1,421 @@
+---
+name: testing-react
+description: Testing de componentes React con React Testing Library, Vitest/Jest, MSW para mockear la red, aserciones de accesibilidad con axe y la frontera de decisión entre tests de componentes y ejecuciones end-to-end con Playwright/Cypress. Úsala al escribir o arreglar tests de componentes, hooks o páginas React.
+---
+
+# Testing de React
+
+Patrones integrales de testing de React para tests de componentes centrados en el comportamiento, tests de hooks personalizados, aserciones de accesibilidad y mocking a nivel de red.
+
+## Cuándo activar
+
+- Al escribir tests para componentes React, hooks personalizados o páginas
+- Al añadir cobertura de tests a componentes legados sin tests
+- Al migrar desde Enzyme o patrones de la era de componentes de clase hacia React Testing Library
+- Al configurar Vitest o Jest en un proyecto React nuevo
+- Al mockear peticiones HTTP en tests
+- Al hacer aserciones sobre violaciones de accesibilidad
+- Al decidir qué tests van en RTL vs Playwright Component Testing vs E2E completo
+
+## Principio central
+
+Prueba lo que el usuario ve y hace, no los detalles de implementación.
+
+Un test debe:
+
+- Renderizar el componente con los mismos providers que tiene en producción
+- Interactuar con él mediante consultas accesibles (role, label) y `userEvent`
+- Hacer aserciones sobre la salida visible y los efectos secundarios observables (callback disparado, petición enviada)
+
+Un test NO debe:
+
+- Inspeccionar el estado del componente, las props pasadas a los hijos o qué hooks se llamaron
+- Mockear React en sí ni los hooks del framework
+- Hacer aserciones sobre el número de renders o la estructura del DOM más allá de lo que afecta al usuario
+
+## Elección de librería
+
+| Runner | Cuándo | Nota |
+|---|---|---|
+| **Vitest** | Vite, Remix, configuraciones modernas | Más rápido, ESM nativo, API compatible con Jest |
+| **Jest** | Next.js, CRA, repos establecidos | Predeterminado en muchos proyectos React |
+| **Playwright Component Testing** | Se necesita un motor de navegador real | Úsalo cuando JSDOM carece de la funcionalidad requerida |
+| **Cypress Component Testing** | Navegador real, Cypress ya en uso | Alternativa a Playwright CT |
+
+Elige uno. No ejecutes RTL + Vitest Y Playwright CT en el mismo repo salvo que tengas una separación clara de carriles.
+
+## Prioridad de consultas
+
+React Testing Library expone consultas en tres niveles — úsalas de arriba hacia abajo:
+
+1. **Accesibles para todos**: `getByRole`, `getByLabelText`, `getByPlaceholderText`, `getByText`, `getByDisplayValue`
+2. **Semánticas**: `getByAltText`, `getByTitle`
+3. **Test IDs (vía de escape)**: `getByTestId`
+
+```tsx
+// Lo mejor
+screen.getByRole("button", { name: /save/i });
+
+// Aceptable para inputs
+screen.getByLabelText("Email");
+
+// Último recurso
+screen.getByTestId("save-btn");
+```
+
+Variantes:
+
+- `getBy*` — lanza error si no hay coincidencia
+- `queryBy*` — devuelve `null` (úsala para "afirmar ausencia")
+- `findBy*` — async, devuelve una Promise (úsala para elementos que aparecen tras trabajo asíncrono)
+
+## Interacción de usuario con `userEvent`
+
+```tsx
+import userEvent from "@testing-library/user-event";
+
+test("envía el formulario", async () => {
+  const user = userEvent.setup();
+  const onSubmit = vi.fn();
+  render(<UserForm onSubmit={onSubmit} />);
+
+  await user.type(screen.getByLabelText("Email"), "user@example.com");
+  await user.click(screen.getByRole("button", { name: /save/i }));
+
+  expect(onSubmit).toHaveBeenCalledWith({ email: "user@example.com" });
+});
+```
+
+- Siempre haz `await` de las llamadas a userEvent
+- Llama a `userEvent.setup()` una vez por test y reutiliza el `user` devuelto
+- `userEvent` simula una secuencia real de navegador; `fireEvent` despacha un único evento sintético — prefiere `userEvent`
+
+## Patrones async
+
+```tsx
+// Elemento que aparece tras trabajo asíncrono
+expect(await screen.findByText("Loaded")).toBeInTheDocument();
+
+// Aserción sobre un efecto secundario
+await waitFor(() => expect(saveSpy).toHaveBeenCalled());
+
+// Elemento que debe desaparecer
+await waitForElementToBeRemoved(() => screen.queryByText("Loading"));
+```
+
+Nunca `setTimeout` + aserción — es frágil. Usa los matchers anteriores.
+
+## Mocking de red con MSW
+
+Mock Service Worker mockea en la capa de red. El componente, los hooks y la librería de fetch se comportan exactamente igual que en producción.
+
+### Configuración
+
+```ts
+// test/setup.ts
+import { setupServer } from "msw/node";
+import { http, HttpResponse } from "msw";
+
+export const handlers = [
+  http.get("/api/users/:id", ({ params }) =>
+    HttpResponse.json({ id: params.id, name: "Alice" }),
+  ),
+  http.post("/api/users", async ({ request }) => {
+    const body = await request.json();
+    return HttpResponse.json({ id: "new-id", ...body }, { status: 201 });
+  }),
+];
+
+export const server = setupServer(...handlers);
+
+beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+Configura `onUnhandledRequest: "error"` para que cualquier petición sin mockear haga fallar el test de forma ruidosa — los pases silenciosos son peores que el rojo.
+
+### Sobrescritura por test
+
+```tsx
+test("renderiza error ante un 500", async () => {
+  server.use(
+    http.get("/api/users/:id", () => new HttpResponse(null, { status: 500 })),
+  );
+  render(<UserPage id="1" />);
+  expect(await screen.findByText(/something went wrong/i)).toBeInTheDocument();
+});
+```
+
+## Envoltura de providers
+
+Envuelve los providers una sola vez en un `test-utils.tsx`:
+
+```tsx
+// test-utils.tsx
+import { render, RenderOptions } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+export function renderWithProviders(
+  ui: React.ReactElement,
+  options?: RenderOptions,
+) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ThemeProvider theme={lightTheme}>
+        <MemoryRouter>{ui}</MemoryRouter>
+      </ThemeProvider>
+    </QueryClientProvider>,
+    options,
+  );
+}
+
+export * from "@testing-library/react";
+```
+
+Luego `import { renderWithProviders, screen } from "test-utils"` en cada archivo de tests.
+
+## Testing de hooks personalizados
+
+```tsx
+import { renderHook, act } from "@testing-library/react";
+
+test("useCounter incrementa y decrementa", () => {
+  const { result } = renderHook(() => useCounter(0));
+
+  expect(result.current.count).toBe(0);
+
+  act(() => result.current.increment());
+  expect(result.current.count).toBe(1);
+
+  act(() => result.current.decrement());
+  expect(result.current.count).toBe(0);
+});
+
+test("useCounter acepta un valor inicial", () => {
+  const { result } = renderHook(() => useCounter(10));
+  expect(result.current.count).toBe(10);
+});
+
+test("useUser obtiene los datos del usuario", async () => {
+  // Instancia el QueryClient UNA vez por test fuera del wrapper para que sobreviva a los re-renders.
+  // Crearlo dentro del closure del wrapper reinicia el estado de la caché en cada render, produciendo tests frágiles.
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+
+  const { result } = renderHook(() => useUser("1"), { wrapper });
+
+  await waitFor(() => expect(result.current.isSuccess).toBe(true));
+  expect(result.current.data).toEqual({ id: "1", name: "Alice" });
+});
+```
+
+- Envuelve las llamadas que cambian el estado en `act`
+- Prueba solo a través de la API pública del hook
+- Para hooks que usan contexto, pasa un `wrapper`
+
+## Aserciones de accesibilidad
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"; // o vitest-axe
+expect.extend(toHaveNoViolations);
+
+test("UserCard no tiene violaciones de a11y", async () => {
+  const { container } = render(<UserCard user={mockUser} />);
+  expect(await axe(container)).toHaveNoViolations();
+});
+```
+
+Ejecuta axe en los tests de componentes de cada componente interactivo. Detecta:
+
+- Etiquetas ausentes en inputs de formulario
+- Uso inválido de ARIA
+- Contraste de color deficiente (limitado — JSDOM no tiene motor CSS real, así que solo funciona con estilos inline; el contraste visual pertenece a Playwright)
+- Texto alt ausente en imágenes
+- Violaciones del orden de encabezados
+
+Enlace cruzado: [skills/accesibilidad/SKILL.md](../accesibilidad/SKILL.md) para el playbook más amplio de testing de accesibilidad.
+
+## Cuándo NO usar tests de snapshot
+
+Los snapshots de la salida renderizada:
+
+- Se rompen con cada cambio de estilos
+- Se aprueban sin mirar durante la revisión
+- Prueban un detalle de implementación (la estructura del DOM), no el comportamiento
+
+Usos aceptables de snapshots:
+
+- Funciones puras de serialización de datos (`formatInvoice(invoice)` -> cadena estable)
+- Archivos de configuración generados (p. ej., la salida de una config de webpack)
+
+Para regresión visual de componentes, usa capturas de Playwright/Cypress o Percy/Chromatic — diffs visuales reales, no cadenas de DOM.
+
+## Cuándo recurrir a Playwright / Cypress
+
+JSDOM (usado por Vitest/Jest) no puede:
+
+- Renderizar layout real (flexbox, grid, media queries de viewport)
+- Ejecutar animaciones nativas del navegador ni transiciones CSS
+- Probar comportamiento de scroll, drag-and-drop, pegar desde el portapapeles
+- Manejar iframes, popups, descargas, flujos cross-origin
+- Ejecutar red real en un entorno controlado con soporte completo de DevTools
+
+Para cualquiera de esos casos, usa Playwright Component Testing (test de componente en navegador real) o E2E completo. Ver la [skill testing-e2e](../testing-e2e/SKILL.md).
+
+Frontera de decisión:
+
+- Un hook, un componente presentacional, un formulario con lógica -> RTL
+- Un componente cuyo layout importa o que usa APIs de navegador ausentes en JSDOM -> Playwright CT
+- Un flujo de usuario completo a través de varias páginas -> E2E con Playwright/Cypress
+
+## Objetivos de cobertura
+
+| Capa | Objetivo |
+|---|---|
+| Utilidades puras | >=90% |
+| Hooks personalizados | >=85% |
+| Componentes presentacionales | >=80% — comportamiento, no líneas |
+| Componentes contenedores | >=70% — rutas felices + estados de error |
+| Páginas | Cubiertas aparte por E2E; smoke test como mínimo |
+
+Configúralo vía `vitest.config.ts` / `jest.config.js`:
+
+```ts
+// vitest.config.ts
+test: {
+  coverage: {
+    provider: "v8",
+    reporter: ["text", "html", "lcov"],
+    thresholds: {
+      lines: 80,
+      functions: 80,
+      branches: 70,
+      statements: 80,
+    },
+  },
+}
+```
+
+## Antipatrones
+
+- `container.querySelector("...")` — se salta las consultas de accesibilidad y deja pasar tests donde los usuarios reales fallarían
+- Hacer aserciones sobre el número de renders — detalle de implementación
+- `jest.mock("react", ...)` — nunca mockees React. Refactoriza el componente en su lugar
+- Mockear componentes hijos por defecto — se prueba la integración, no el aislamiento. Mockea solo cuando el hijo tiene efectos secundarios pesados
+- Ignorar las advertencias de `act()` — señalan bugs reales (actualización de estado tras el desmontaje, envoltura async ausente)
+- Compartir estado mutable entre tests — produce fallos intermitentes cuando cambia el orden de ejecución
+- Tests que pasan al quitar el `it.skip()` — tu test no afirma realmente lo que crees
+
+## Flujo TDD
+
+```
+ROJO     -> Escribe el test que falla para el siguiente requisito
+VERDE    -> Escribe el código mínimo del componente para pasar
+REFACTOR -> Mejora el componente, los tests siguen en verde
+REPITE   -> Siguiente requisito
+```
+
+Para componentes nuevos:
+
+1. Define el tipo de props y la firma del componente
+2. Escribe el primer test para el caso más simple
+3. Verifica que falla por la razón correcta
+4. Implementa lo justo para pasar
+5. Añade el siguiente caso de test
+6. Refactoriza cuando el tercer test similar revele un patrón
+
+## Comandos de tests
+
+```bash
+# Vitest
+vitest                            # modo watch
+vitest run                        # una sola pasada
+vitest run --coverage             # con cobertura
+vitest run path/to/file.test.tsx  # un solo archivo
+
+# Jest
+jest --watch
+jest --coverage
+jest path/to/file.test.tsx
+
+# Modo CI
+CI=true vitest run --coverage
+```
+
+## Relacionados
+
+- Skills: [patrones-react](../patrones-react/SKILL.md), [accesibilidad](../accesibilidad/SKILL.md), [testing-e2e](../testing-e2e/SKILL.md), [flujo-tdd](../flujo-tdd/SKILL.md)
+- Agentes: `revisor-react` (revisa la calidad de los tests durante la revisión de código), `guia-tdd` (hace cumplir el proceso TDD)
+- Comandos: `/test-react`, `/revisar-react`
+
+## Ejemplos
+
+### Envío de formulario con MSW y userEvent
+
+```tsx
+test("envía el formulario de usuario y muestra éxito", async () => {
+  server.use(
+    http.post("/api/users", () =>
+      HttpResponse.json({ id: "1", name: "Alice" }, { status: 201 }),
+    ),
+  );
+
+  const user = userEvent.setup();
+  renderWithProviders(<UserForm />);
+
+  await user.type(screen.getByLabelText("Name"), "Alice");
+  await user.type(screen.getByLabelText("Email"), "alice@example.com");
+  await user.click(screen.getByRole("button", { name: /save/i }));
+
+  expect(await screen.findByText(/saved successfully/i)).toBeInTheDocument();
+});
+```
+
+### Probar un error boundary
+
+```tsx
+function Broken() {
+  throw new Error("boom");
+}
+
+test("el error boundary renderiza el fallback", () => {
+  // Silencia el ruido de console.error de React para el throw esperado, y luego restaura
+  // para que el spy no se filtre a otros tests y oculte errores reales en otra parte.
+  const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  try {
+    render(
+      <ErrorBoundary fallback={<div>Something went wrong</div>}>
+        <Broken />
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByText("Something went wrong")).toBeInTheDocument();
+  } finally {
+    errorSpy.mockRestore();
+  }
+});
+```
+
+### Probar una frontera de Suspense
+
+```tsx
+test("muestra la carga y luego el contenido", async () => {
+  renderWithProviders(
+    <Suspense fallback={<div>Loading...</div>}>
+      <UserDetail id="1" />
+    </Suspense>,
+  );
+
+  expect(screen.getByText("Loading...")).toBeInTheDocument();
+  expect(await screen.findByText("Alice")).toBeInTheDocument();
+});
+```