name: tests-guidelines description: Usar al escribir pruebas o hacer TDD: nuevas funciones, correcciones de errores, refactorizaciones. Promueve el desarrollo primero con pruebas y una cobertura superior al 80% en pruebas unitarias, de integración y E2E. Se activa con /tests-guidelines, "tests", "coverage", "unit test", "integration test", "TDD". license: MIT source: https://github.com/affaan-m/everything-claude-code (skill tdd-workflow, MIT), adaptado
Flujo de Trabajo de Desarrollo Guiado por Pruebas
Esta habilidad asegura que todo el desarrollo de código siga los principios TDD con una cobertura de pruebas integral.
Cuándo Activarlo
- Al escribir nuevas funciones o características
- Al corregir errores o problemas
- Al refactorizar código existente
- Al agregar endpoints de API
- Al crear nuevos componentes
Principios Centrales
1. Pruebas ANTES del Código
SIEMPRE escribe las pruebas primero, luego implementa el código para que las pruebas pasen.
2. Requisitos de Cobertura
- Mínimo 80% de cobertura (unitaria + integración + E2E)
- Todos los casos extremos cubiertos
- Escenarios de error probados
- Condiciones límite verificadas
3. Tipos de Pruebas
Pruebas Unitarias
- Funciones y utilidades individuales
- Lógica de componentes
- Funciones puras
- Ayudantes y utilidades
Pruebas de Integración
- Endpoints de API
- Operaciones de base de datos
- Interacciones entre servicios
- Llamadas a APIs externas
Pruebas E2E (Playwright)
- Flujos de usuario críticos
- Flujos de trabajo completos
- Automatización del navegador
- Interacciones con la UI
Pasos del Flujo TDD
Paso 0: Detectar el Corredor de Pruebas
No asumas npm test. Los comandos en los pasos y ejemplos a continuación usan <test>, <test-watch> y <coverage> como marcadores de posición para el corredor real del proyecto. Resuélvelos una vez antes de comenzar:
-
Encuentra el corredor del proyecto. Lee
package.json(packageManager,scripts.test), el archivo de bloqueo,pyproject.toml/pytest.ini,go.mod,Cargo.toml. La primera coincidencia es la correcta; no asumasnpm test. -
Distingue el gestor de paquetes del corredor de pruebas. No son lo mismo. Un proyecto puede usar Bun para instalar dependencias pero seguir ejecutando Jest o Vitest. Inspecciona
package.jsonscripts.testy los archivos de prueba:scripts.testinvocajest/vitest-> ejecuta a través del PM detectado (npm test,pnpm test,yarn test, obun run test).scripts.testesbun test, o los archivos de prueba importanimport { test, expect } from "bun:test", o no hay configuración de jest/vitest pero Bun está presente -> usa el corredor nativo de Bun (bun test). Consulta el Patrón de Prueba Nativo de Bun a continuación.- Python:
<test>=pytest,<coverage>=pytest --cov --cov-fail-under=80. Go:go test ./...ygo test -cover ./.... Rust:cargo test.
Matriz de comandos del corredor:
| Corredor | <test> | <test-watch> | <coverage> | <lint> |
|---|---|---|---|---|
| npm | npm test | npm test -- --watch | npm run test:coverage | npm run lint |
| pnpm | pnpm test | pnpm test --watch | pnpm test:coverage | pnpm lint |
| yarn | yarn test | yarn test --watch | yarn test:coverage | yarn lint |
| Bun (script ejecuta jest/vitest) | bun run test | bun run test --watch | bun run test:coverage | bun run lint |
Bun (nativo bun:test) | bun test | bun test --watch | bun test --coverage | bun run lint |
bun test(el corredor integrado de Bun) no es lo mismo quebun run test(que ejecuta el scripttestdepackage.json). Elegir incorrectamente es un error común; por ejemplo, invocar Jest a través denpx/bun runen un proyecto solo ESM se rompe, mientras quebun testejecuta el conjunto de pruebas de forma nativa. Confirma cuál espera el proyecto antes de la puerta ROJA, luego sustituye<test>/<coverage>en todas partes donde aparezcanpm testa continuación.
Paso 1: Escribir Historias de Usuario
Como [rol], quiero [acción], para [beneficio]
Ejemplo:
Como usuario, quiero buscar mercados semánticamente,
para poder encontrar mercados relevantes incluso sin palabras clave exactas.
Paso 2: Generar Casos de Prueba
Para cada historia de usuario, crea casos de prueba completos:
describe('Búsqueda Semántica', () => {
it('devuelve mercados relevantes para la consulta', async () => {
// Implementación de la prueba
})
it('maneja una consulta vacía correctamente', async () => {
// Probar caso extremo
})
it('se degrada a búsqueda por subcadena cuando Redis no está disponible', async () => {
// Probar comportamiento de degradación
})
it('ordena los resultados por puntuación de similitud', async () => {
// Probar lógica de ordenamiento
})
})
Paso 3: Ejecutar Pruebas (Deberían Fallar)
<test>
# Las pruebas deberían fallar - aún no hemos implementado
Paso 4: Implementar Código
Escribe el código mínimo para que las pruebas pasen:
// Implementación guiada por las pruebas
export async function searchMarkets(query: string) {
// Implementación aquí
}
Paso 5: Ejecutar Pruebas de Nuevo
<test>
# Las pruebas ahora deberían pasar
Paso 6: Refactorizar
Mejora la calidad del código mientras mantienes las pruebas en verde:
- Elimina duplicaciones
- Mejora la nomenclatura
- Optimiza el rendimiento
- Mejora la legibilidad
Paso 7: Verificar Cobertura
<coverage>
# Verificar que se ha alcanzado una cobertura del 80%+
Patrones de Prueba
Patrón de Prueba Unitaria (Jest/Vitest)
import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './Button'
describe('Componente Button', () => {
it('renderiza con el texto correcto', () => {
render(<Button>Haz clic</Button>)
expect(screen.getByText('Haz clic')).toBeInTheDocument()
})
it('llama a onClick al hacer clic', () => {
const handleClick = jest.fn()
render(<Button onClick={handleClick}>Haz clic</Button>)
fireEvent.click(screen.getByRole('button'))
expect(handleClick).toHaveBeenCalledTimes(1)
})
it('está deshabilitado cuando la prop disabled es true', () => {
render(<Button disabled>Haz clic</Button>)
expect(screen.getByRole('button')).toBeDisabled()
})
})
Patrón de Prueba Nativo de Bun (bun:test)
Cuando el proyecto usa el corredor integrado de Bun (consulta Paso 0), importa desde bun:test y ejecuta con bun test - no bun run test. La API es similar a Jest, por lo que describe / it / expect y la mayoría de los comparadores funcionan.
import { describe, it, expect, mock } from 'bun:test'
import { searchMarkets } from './search'
describe('searchMarkets', () => {
it('devuelve una lista vacía para una consulta vacía', async () => {
expect(await searchMarkets('')).toEqual([])
})
it('ordena los resultados por puntuación de similitud', async () => {
const results = await searchMarkets('elección')
expect(results).toEqual([...results].sort((a, b) => b.score - a.score))
})
})
bun test # ejecutar una vez (puerta ROJA/VERDE)
bun test --watch # modo observador durante el desarrollo
bun test --coverage # informe de cobertura
- Simula módulos con
mock.module(...)/mock(...)debun:testen lugar dejest.mock(...). - Configura umbrales de cobertura en
bunfig.tomlbajo[test](p.ej.coverageThreshold) en lugar del bloque de configuracióncoverageThresholdsde Jest.
Patrón de Prueba de Integración de API
import { NextRequest } from 'next/server'
import { GET } from './route'
describe('GET /api/markets', () => {
it('devuelve mercados correctamente', async () => {
const request = new NextRequest('http://localhost/api/markets')
const response = await GET(request)
const data = await response.json()
expect(response.status).toBe(200)
expect(data.success).toBe(true)
expect(Array.isArray(data.data)).toBe(true)
})
it('valida los parámetros de consulta', async () => {
const request = new NextRequest('http://localhost/api/markets?limit=invalid')
const response = await GET(request)
expect(response.status).toBe(400)
})
it('maneja errores de base de datos correctamente', async () => {
// Simular fallo de base de datos
const request = new NextRequest('http://localhost/api/markets')
// Probar manejo de errores
})
})
Patrón de Prueba E2E (Playwright)
import { test, expect } from '@playwright/test'
test('el usuario puede buscar y filtrar mercados', async ({ page }) => {
// Navegar a la página de mercados
await page.goto('/')
await page.click('a[href="/markets"]')
// Verificar que la página se cargó
await expect(page.locator('h1')).toContainText('Mercados')
// Buscar mercados
await page.fill('input[placeholder="Buscar mercados"]', 'elección')
// Esperar al debounce y resultados
await page.waitForTimeout(600)
// Verificar que los resultados de búsqueda se muestran
const results = page.locator('[data-testid="market-card"]')
await expect(results).toHaveCount(5, { timeout: 5000 })
// Verificar que los resultados contienen el término de búsqueda
const firstResult = results.first()
await expect(firstResult).toContainText('elección', { ignoreCase: true })
// Filtrar por estado
await page.click('button:has-text("Activo")')
// Verificar resultados filtrados
await expect(results).toHaveCount(3)
})
test('el usuario puede crear un nuevo mercado', async ({ page }) => {
// Iniciar sesión primero
await page.goto('/panel-de-creador')
// Rellenar formulario de creación de mercado
await page.fill('input[name="name"]', 'Mercado de Prueba')
await page.fill('textarea[name="description"]', 'Descripción de prueba')
await page.fill('input[name="endDate"]', '2025-12-31')
// Enviar formulario
await page.click('button[type="submit"]')
// Verificar mensaje de éxito
await expect(page.locator('text=Mercado creado exitosamente')).toBeVisible()
// Verificar redirección a la página del mercado
await expect(page).toHaveURL(/\/markets\/mercado-de-prueba/)
})
Organización de Archivos de Prueba
src/
├── componentes/
│ ├── Button/
│ │ ├── Button.tsx
│ │ ├── Button.test.tsx # Pruebas unitarias
│ │ └── Button.stories.tsx # Storybook
│ └── MarketCard/
│ ├── MarketCard.tsx
│ └── MarketCard.test.tsx
├── app/
│ └── api/
│ └── markets/
│ ├── route.ts
│ └── route.test.ts # Pruebas de integración
└── e2e/
├── markets.spec.ts # Pruebas E2E
├── trading.spec.ts
└── auth.spec.ts
Simulación de Servicios Externos
Simulación de Supabase
jest.mock('@/lib/supabase', () => ({
supabase: {
from: jest.fn(() => ({
select: jest.fn(() => ({
eq: jest.fn(() => Promise.resolve({
data: [{ id: 1, name: 'Mercado de Prueba' }],
error: null
}))
}))
}))
}
}))
Simulación de Redis
jest.mock('@/lib/redis', () => ({
searchMarketsByVector: jest.fn(() => Promise.resolve([
{ slug: 'test-market', similarity_score: 0.95 }
])),
checkRedisHealth: jest.fn(() => Promise.resolve({ connected: true }))
}))
Simulación de OpenAI
jest.mock('@/lib/openai', () => ({
generateEmbedding: jest.fn(() => Promise.resolve(
new Array(1536).fill(0.1) // Simular embedding de 1536 dimensiones
))
}))
Verificación de Cobertura de Pruebas
Ejecutar Informe de Cobertura
<coverage>
Umbrales de Cobertura
{
"jest": {
"coverageThresholds": {
"global": {
"branches": 80,
"functions": 80,
"lines": 80,
"statements": 80
}
}
}
}
Errores Comunes al Probar que Debes Evitar
FALLO: INCORRECTO: Probar Detalles de Implementación
// No pruebes el estado interno
expect(component.state.count).toBe(5)
PASA: CORRECTO: Probar Comportamiento Visible por el Usuario
// Probar lo que los usuarios ven
expect(screen.getByText('Contador: 5')).toBeInTheDocument()
FALLO: INCORRECTO: Selectores Frágiles
// Se rompe fácilmente
await page.click('.css-class-xyz')
PASA: CORRECTO: Selectores Semánticos
// Resistente a cambios
await page.click('button:has-text("Enviar")')
await page.click('[data-testid="boton-enviar"]')
FALLO: INCORRECTO: Sin Aislamiento de Pruebas
// Las pruebas dependen unas de otras
test('crea usuario', () => { /* ... */ })
test('actualiza el mismo usuario', () => { /* depende de la prueba anterior */ })
PASA: CORRECTO: Pruebas Independientes
// Cada prueba configura sus propios datos
test('crea usuario', () => {
const user = createTestUser()
// Lógica de prueba
})
test('actualiza usuario', () => {
const user = createTestUser()
// Lógica de actualización
})
Pruebas Continuas
Modo Observador Durante el Desarrollo
<test-watch>
# Las pruebas se ejecutan automáticamente al cambiar archivos
Gancho Pre-Commit
# Se ejecuta antes de cada commit
<test> && <lint>
Integración CI/CD
# GitHub Actions
- name: Ejecutar Pruebas
run: <coverage>
- name: Subir Cobertura
uses: codecov/codecov-action@v3
Mejores Prácticas
- Escribir Pruebas Primero - Siempre TDD
- Una Afirmación por Prueba - Enfocarse en un solo comportamiento
- Nombres de Prueba Descriptivos - Explicar qué se prueba
- Organizar-Actuar-Afirmar - Estructura de prueba clara
- Simular Dependencias Externas - Aislar pruebas unitarias
- Probar Casos Extremos - Null, undefined, vacío, grande
- Probar Rutas de Error - No solo caminos felices
- Mantener Pruebas Rápidas - Pruebas unitarias < 50ms cada una
- Limpiar Después de las Pruebas - Sin efectos secundarios
- Revisar Informes de Cobertura - Identificar brechas
Métricas de Éxito
- Cobertura de código superior al 80%
- Todas las pruebas pasando (verde)
- Sin pruebas omitidas o deshabilitadas
- Ejecución rápida de pruebas (< 30s para pruebas unitarias)
- Pruebas E2E cubren flujos de usuario críticos
- Las pruebas detectan errores antes de la producción
Recuerda: Las pruebas no son opcionales. Son la red de seguridad que permite refactorizaciones confiables, desarrollo rápido y fiabilidad en producción.