CommunityProgramación y desarrollogithub.com

tests-guidelines

Habilidad de codificación. 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".

¿Qué es tests-guidelines?

Esta habilidad guía el desarrollo de software siguiendo los principios de TDD (Test-Driven Development), asegurando que todas las funciones, correcciones y refactorizaciones estén respaldadas por pruebas exhaustivas. Soporta múltiples tipos de pruebas: unitarias, de integración y E2E (con Playwright), y exige una cobertura mínima del 80%. La habilidad detecta automáticamente el gestor de paquetes y el corredor de pruebas del proyecto (npm, pnpm, yarn, Bun, pytest, go test, cargo test) y proporciona plantillas de código para Jest/Vitest, Bun, y Playwright. También incluye patrones para simular servicios externos (Supabase, Redis, OpenAI), organización de archivos de prueba, y mejores prácticas para evitar errores comunes. Es ideal para equipos que buscan estandarizar su flujo TDD y mantener una alta calidad de código.

Compatible con✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/orenatobr/tests-guidelines/tree/HEAD/skills/tests-guidelines

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación


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:

  1. 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 asumas npm test.

  2. 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.json scripts.test y los archivos de prueba:

    • scripts.test invoca jest / vitest -> ejecuta a través del PM detectado (npm test, pnpm test, yarn test, o bun run test).
    • scripts.test es bun test, o los archivos de prueba importan import { 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 ./... y go test -cover ./.... Rust: cargo test.

Matriz de comandos del corredor:

Corredor<test><test-watch><coverage><lint>
npmnpm testnpm test -- --watchnpm run test:coveragenpm run lint
pnpmpnpm testpnpm test --watchpnpm test:coveragepnpm lint
yarnyarn testyarn test --watchyarn test:coverageyarn lint
Bun (script ejecuta jest/vitest)bun run testbun run test --watchbun run test:coveragebun run lint
Bun (nativo bun:test)bun testbun test --watchbun test --coveragebun run lint

bun test (el corredor integrado de Bun) no es lo mismo que bun run test (que ejecuta el script test de package.json). Elegir incorrectamente es un error común; por ejemplo, invocar Jest a través de npx/bun run en un proyecto solo ESM se rompe, mientras que bun test ejecuta 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 aparezca npm test a 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(...) de bun:test en lugar de jest.mock(...).
  • Configura umbrales de cobertura en bunfig.toml bajo [test] (p.ej. coverageThreshold) en lugar del bloque de configuración coverageThresholds de 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

  1. Escribir Pruebas Primero - Siempre TDD
  2. Una Afirmación por Prueba - Enfocarse en un solo comportamiento
  3. Nombres de Prueba Descriptivos - Explicar qué se prueba
  4. Organizar-Actuar-Afirmar - Estructura de prueba clara
  5. Simular Dependencias Externas - Aislar pruebas unitarias
  6. Probar Casos Extremos - Null, undefined, vacío, grande
  7. Probar Rutas de Error - No solo caminos felices
  8. Mantener Pruebas Rápidas - Pruebas unitarias < 50ms cada una
  9. Limpiar Después de las Pruebas - Sin efectos secundarios
  10. 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.

Skills relacionados