🧪 3.8 · Testing automatizado: Jest, React Testing Library y la pirámide del testing

🎯 Objetivo del tema

🗺️ Mapa del tema

El testing es el SUPERPODER del developer profesional. Te permite cambiar código con confianza: 'estoy rompiendo algo?'. Si tienes tests, lo sabes en 10 segundos. Si no, te enteras cuando el usuario final se queja en producción. En este tema vas a aprender Jest (el test runner #1 de JS), React Testing Library (la librería estándar para testear componentes como los usaría un usuario), mocks, coverage, y el flujo de trabajo de TDD. Al final vas a tener una suite de tests para tu Atlas Mundial con cobertura >70%.

3.8.1 La pirámide del testing: unit, integration, e2e

Antes de escribir tu primer test, necesitas entender la pirámide del testing. Es un modelo mental creado por Martin Fowler que te dice QUÉ tipo de test escribir y CUÁNTOS de cada uno. La regla: muchos tests unitarios (rápidos, baratos), algunos tests de integración (más lentos, más completos), y pocos tests E2E (lentos, frágiles, pero necesarios). Es el balance que mantiene tu app rápida de testear y cobertura alta.

3.8.2 Jest: el framework de testing de JavaScript

Jest es el framework de testing creado por Facebook (Meta) y es el estándar de la industria para JavaScript. Vite lo incluye automáticamente, solo ejecutas npm test. Jest te da: assertions (expect), mocks (jest.mock), spies (jest.spyOn), coverage (--coverage), y watch mode (corre solo los tests que cambiaron). En este bloque vas a aprender la API esencial de Jest: describe, it/test, expect, beforeEach, afterEach.

Anatomía de un test con Jest

// tests/sumar.test.js
// Convención: nombreDelArchivo.test.js o .spec.js

import { sumar, dividir } from '../utils/math';

// describe agrupa tests relacionados (opcional pero recomendado)
describe('utils/math', () => {
  // it() o test() definen UN caso de prueba
  it('sumar(2, 3) devuelve 5', () => {
    // expect es la assertion: 'espero que sumar(2,3) sea 5'
    expect(sumar(2, 3)).toBe(5);
  });

  it('sumar(0, 0) devuelve 0', () => {
    expect(sumar(0, 0)).toBe(0);
  });

  it('sumar(-1, 1) devuelve 0', () => {
    expect(sumar(-1, 1)).toBe(0);
  });

  // Test de un caso de error con toThrow
  it('dividir por 0 lanza error', () => {
    // Para funciones que lanzan error, envuelve en arrow function
    expect(() => dividir(10, 0)).toThrow('No se puede dividir por 0');
  });

  // beforeEach: se ejecuta ANTES de cada test (útil para setup)
  let lista;
  beforeEach(() => {
    lista = [1, 2, 3, 4, 5];
  });

  it('lista tiene 5 elementos', () => {
    expect(lista).toHaveLength(5);
  });

  it('lista incluye el 3', () => {
    expect(lista).toContain(3);
  });
});

Test suite con describe, it, expect, beforeEach

Matchers más usados de Jest

// Matchers de igualdad y comparación
expect(2 + 2).toBe(4);              // === (estricto)
expect({ a: 1 }).toEqual({ a: 1 });  // igualdad profunda (objetos)
expect(0.1 + 0.2).toBeCloseTo(0.3);  // números flotantes

// Matchers de verdad
expect(true).toBeTruthy();
expect(0).toBeFalsy();
expect(null).toBeNull();
expect(undefined).toBeUndefined();

// Matchers de números
expect(10).toBeGreaterThan(5);
expect(10).toBeLessThanOrEqual(10);

// Matchers de strings
expect('Hola Mundo').toMatch(/mundo/i);
expect('Hola Mundo').toContain('Mundo');

// Matchers de arrays e iterables
expect(['a', 'b']).toContain('a');
expect([{a:1}]).toContainEqual({a:1});
expect(new Set([1,2])).toContain(1);

// Matchers de excepciones
expect(() => fn()).toThrow();
expect(() => fn()).toThrow('Error específico');
expect(() => fn()).toThrow(/regex/);

// Negación con .not
expect(sumar(2, 2)).not.toBe(5);
expect(lista).not.toContain(99);

Los 20 matchers de Jest que usarás el 95% del tiempo

3.8.3 React Testing Library: testear como el usuario

React Testing Library (RTL) es la librería estándar para testear componentes React. Su filosofía: testear como el usuario usaría el componente, NO como está implementado internamente. En vez de buscar por clase CSS o ID (que son detalles de implementación), busca por ROL, TEXTO, o LABEL (que es lo que el usuario ve y usa). Esto hace que tus tests no se rompan cuando refactorizas el código interno pero la UI sigue igual.

Queries de RTL: cómo encontrar elementos

// tests/Button.test.jsx
import { render, screen, fireEvent } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { Button } from '../atoms/Button';

describe('<Button />', () => {
  it('renderiza el texto del children', () => {
    render(<Button>Click me</Button>);
    // getByText: busca un elemento con ESE texto
    expect(screen.getByText('Click me')).toBeInTheDocument();
  });

  it('llama onClick cuando se hace click', async () => {
    const handleClick = vi.fn(); // mock function de Vitest
    const user = userEvent.setup();
    render(<Button onClick={handleClick}>Click me</Button>);

    // getByRole: busca por rol ARIA (button, link, heading, etc.)
    const button = screen.getByRole('button', { name: /click me/i });
    await user.click(button);

    expect(handleClick).toHaveBeenCalledTimes(1);
  });

  it('NO llama onClick cuando está disabled', async () => {
    const handleClick = vi.fn();
    const user = userEvent.setup();
    render(<Button disabled onClick={handleClick}>Click</Button>);

    const button = screen.getByRole('button', { name: /click/i });
    await user.click(button);

    expect(handleClick).not.toHaveBeenCalled();
  });

  it('muestra el spinner cuando loading es true', () => {
    render(<Button loading>Guardar</Button>);
    // getByLabelText: busca input por su label asociado
    // getByRole('status'): busca elemento con role='status'
    expect(screen.getByRole('status')).toBeInTheDocument();
  });
});

Tests de Button con React Testing Library

Las queries de RTL: orden de prioridad

// Las queries tienen un ORDEN DE PRIORIDAD recomendado por la doc oficial:
// 1. getByRole: la MEJOR opción (accesibilidad + como lo ve el usuario)
const button = screen.getByRole('button', { name: /enviar/i });

// 2. getByLabelText: para inputs con label
const input = screen.getByLabelText(/email/i);

// 3. getByPlaceholderText: solo si no hay label
const input2 = screen.getByPlaceholderText(/buscar/i);

// 4. getByText: para texto no interactivo (párrafos, headings)
const heading = screen.getByText(/bienvenido/i);

// 5. getByDisplayValue: para inputs con valor
const input3 = screen.getByDisplayValue('Juan');

// 6. getByAltText: para imágenes
const logo = screen.getByAltText(/logo de la empresa/i);

// 7. getByTitle: para elementos con title attribute
const tooltip = screen.getByTitle('Más información');

// 8. getByTestId: ÚLTIMO RECURSO. Es un escape hatch.
//    data-testid solo se usa cuando ninguna otra query funciona.
const weird = screen.getByTestId('custom-chart');

// Variantes:
// getBy: retorna el elemento o falla el test (usar cuando DEBE existir)
// queryBy: retorna null si no existe (usar cuando queremos verificar AUSENCIA)
// findBy: retorna una Promise (usar para elementos que aparecen asíncronamente)

// Ejemplo de findBy (esperar a que aparezca un elemento async):
it('muestra los datos después de cargar', async () => {
  render(<PaisDetalle id='ARG' />);
  // Espera HASTA 1000ms a que aparezca el elemento
  const nombre = await screen.findByText('Argentina', {}, { timeout: 1000 });
  expect(nombre).toBeInTheDocument();
});

Queries de RTL: prioridad y cuándo usar cada una

3.8.4 Mocks: simular APIs y módulos externos

Cuando testeas un componente que hace fetch, no quieres hacer una petición real a la API: sería lento, frágil (si la API está caída, falla el test), y no es determinista. La solución: MOCKEAR la API. Hay 2 formas: (1) jest.mock para módulos completos, (2) MSW (Mock Service Worker) para interceptar fetch a nivel de red. La #1 es más simple; la #2 es más realista. En este bloque aprendes ambas.

Mock simple con vi.mock (Vitest)

// tests/PaisCard.test.jsx
import { render, screen, waitFor } from '@testing-library/react';
import { PaisCard } from '../organisms/PaisCard';

// Mockear el módulo useFetch con un mock simple
vi.mock('../hooks/useFetch', () => ({
  useFetch: vi.fn(),
}));

import { useFetch } from '../hooks/useFetch';

describe('<PaisCard />', () => {
  it('muestra loading mientras carga', () => {
    // useFetch devuelve { loading: true } antes de resolver
    useFetch.mockReturnValue({ data: null, loading: true, error: null });

    render(<PaisCard idPais='ARG' />);
    expect(screen.getByText(/cargando/i)).toBeInTheDocument();
  });

  it('muestra el nombre del país cuando carga', async () => {
    // useFetch devuelve los datos mockeados
    useFetch.mockReturnValue({
      data: { name: { common: 'Argentina' }, capital: ['Buenos Aires'] },
      loading: false,
      error: null,
    });

    render(<PaisCard idPais='ARG' />);
    expect(screen.getByRole('heading', { name: /argentina/i })).toBeInTheDocument();
    expect(screen.getByText(/buenos aires/i)).toBeInTheDocument();
  });

  it('muestra error si la API falla', () => {
    useFetch.mockReturnValue({
      data: null,
      loading: false,
      error: new Error('Network error'),
    });

    render(<PaisCard idPais='ARG' />);
    expect(screen.getByText(/error/i)).toBeInTheDocument();
  });
});

Mockear useFetch con vi.mock

Mock realista con MSW (Mock Service Worker)

// mocks/handlers.js: definir las respuestas mockeadas
import { http, HttpResponse } from 'msw';

export const handlers = [
  // Mockear GET https://restcountries.com/v3.1/alpha/ARG
  http.get('https://restcountries.com/v3.1/alpha/:id', ({ params }) => {
    if (params.id === 'ARG') {
      return HttpResponse.json([{
        name: { common: 'Argentina' },
        capital: ['Buenos Aires'],
        population: 45000000,
        flag: 'https://flagcdn.com/ar.png',
      }]);
    }
    return new HttpResponse(null, { status: 404 });
  }),

  // Mockear GET https://api.open-meteo.com/v1/forecast
  http.get('https://api.open-meteo.com/v1/forecast', () => {
    return HttpResponse.json({
      current_weather: { temperature: 22, windspeed: 10 },
    });
  }),
];

// mocks/server.js: configurar el servidor de MSW
import { setupServer } from 'msw/node';
import { handlers } from './handlers';

export const server = setupServer(...handlers);

// tests/setup.js: setup global para Vitest
import { server } from '../mocks/server';

beforeAll(() => server.listen()); // arrancar MSW antes de todos los tests
afterEach(() => server.resetHandlers()); // reset después de cada test
afterAll(() => server.close()); // cerrar al final

// tests/PaisDetalle.test.jsx: ahora el fetch REAL funciona (mockeado por MSW)
import { render, screen, waitFor } from '@testing-library/react';
import { PaisDetalle } from '../pages/PaisDetalle';

it('carga y muestra datos de Argentina', async () => {
  render(<PaisDetalle id='ARG' />);
  // findByText espera ASÍNCRONAMENTE a que aparezca
  const titulo = await screen.findByRole('heading', { name: /argentina/i });
  expect(titulo).toBeInTheDocument();
});

MSW: interceptar fetch a nivel de red (más realista)

3.8.5 Coverage: medir qué % del código está testeado

El coverage (cobertura) es el % de líneas, funciones y branches de tu código que se EJECUTAN durante los tests. No es la métrica perfecta (puedes tener 100% coverage y 0% de tests útiles), pero es un buen termómetro. La regla profesional: mínimo 70% de coverage. Si tienes menos, probablemente hay código que no has pensado bien. Si tienes 100%, no te confíes: coverage alto != tests útiles.

Cómo generar y leer el reporte de coverage

// vitest.config.js: configurar coverage
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: ['./tests/setup.js'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'html', 'lcov'],  // 3 formatos de salida
      include: ['src/**/*.{js,jsx}'],       // qué analizar
      exclude: ['src/**/*.test.{js,jsx}',   // excluir los tests
                'src/main.jsx',              // excluir entry point
                'src/**/*.stories.jsx'],     // excluir stories de Storybook
      thresholds: {                         // umbrales mínimos (falla si no los cumples)
        lines: 70,
        functions: 70,
        branches: 65,
        statements: 70,
      },
    },
  },
});

// package.json: scripts
{
  "scripts": {
    "test": "vitest",
    "test:ui": "vitest --ui",           // interfaz gráfica de tests
    "test:coverage": "vitest --coverage",  // genera reporte
    "test:watch": "vitest --watch"      // watch mode
  }
}

// SALIDA del comando npm run test:coverage:
// ----------|---------|----------|---------|---------|-------------------
// File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
// ----------|---------|----------|---------|---------|-------------------
// All files |   78.4  |    72.1  |   80.0  |   78.4  |
//  atoms/   |   95.2  |    88.9  |  100.0  |   95.2  |
//   Button  |   95.2  |    88.9  |  100.0  |   95.2  | 23-25
//  hooks/   |   82.1  |    75.0  |   85.7  |   82.1  |
//   useFetch|   82.1  |    75.0  |   85.7  |   82.1  | 45,67
//  pages/   |   45.2  |    33.3  |   50.0  |   45.2  | (muchas)
// ----------|---------|----------|---------|---------|-------------------

Configurar coverage en Vitest con umbrales

3.8.6 TDD: escribir el test ANTES del código

TDD (Test-Driven Development) es la metodología donde escribes el TEST primero, luego el código para que pase, luego refactorizas. Es contraintuitivo (¿cómo testear algo que no existe?), pero es la forma más rápida de escribir código de calidad. El flujo se llama Red-Green-Refactor: (1) Red: test falla porque el código no existe. (2) Green: escribes el código mínimo para que pase. (3) Refactor: mejoras el código sin romper el test. Cada ciclo es de 5-15 minutos. Al final tienes código + tests juntos.

Ejemplo de TDD: función validarEmail

// PASO 1 (RED): Escribir el test ANTES del código
// tests/validarEmail.test.js
import { validarEmail } from '../utils/validar';

describe('validarEmail', () => {
  it('rechaza email sin @', () => {
    expect(validarEmail('usuario.example.com')).toBe(false);
  });

  it('acepta email válido', () => {
    expect(validarEmail('usuario@example.com')).toBe(true);
  });

  it('rechaza string vacío', () => {
    expect(validarEmail('')).toBe(false);
  });

  it('rechaza email sin dominio', () => {
    expect(validarEmail('usuario@')).toBe(false);
  });
});

// Ejecutar: npm test --> TODOS FALLAN (RED) porque validarEmail no existe

// PASO 2 (GREEN): Escribir el código MÍNIMO para que los tests pasen
// utils/validar.js
export function validarEmail(email) {
  if (!email) return false;
  if (!email.includes('@')) return false;
  if (email.endsWith('@')) return false;
  return true;  // versión simple, suficiente para pasar los tests
}

// Ejecutar: npm test --> TODOS PASAN (GREEN)

// PASO 3 (REFACTOR): Mejorar el código sin romper los tests
// utils/validar.js (versión mejorada con regex robusto)
export function validarEmail(email) {
  if (typeof email !== 'string') return false;
  if (email.length < 5) return false;
  // Regex: algo@algo.algo (versión simplificada)
  const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return regex.test(email);
}

// Ejecutar: npm test --> SIGUEN PASANDO (los tests no se rompieron)
// Y ahora el código es más robusto.

// CICLO TDD:
//   RED  →  GREEN  →  REFACTOR  →  (siguiente test)  →  RED  →  ...
//   5min    5min        10min          5min            5min

TDD en acción: 3 pasos para validarEmail

📚 Contenido ampliado

Material adicional, referencias externas verificadas y ejemplos extendidos.