theus-cli-linux-x64 1.2.2 → 1.4.0

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

@@ -1,421 +0,0 @@
----
-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();
-});
-```