tdd-workflow skill

Flujo de Trabajo de Desarrollo Guiado por Pruebas

Este skill garantiza que todo el desarrollo de código siga los principios TDD con cobertura de pruebas completa.

Cuándo Activar

• Escribir nuevas funcionalidades
• Corregir bugs o problemas
• Refactorizar código existente
• Agregar endpoints de API
• Crear nuevos componentes

Principios Fundamentales

1. Pruebas ANTES del Código

SIEMPRE escribir primero las pruebas, luego implementar el código para que pasen.

2. Requisitos de Cobertura

• Mínimo 80% de cobertura (unit + integración + E2E)
• Todos los casos borde cubiertos
• Escenarios de error probados
• Condiciones de frontera verificadas

3. Tipos de Prueba

Pruebas Unitarias

• Funciones y utilidades individuales
• Lógica de componentes
• Funciones puras
• Helpers 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 críticos de usuario
• Flujos de trabajo completos
• Automatización del navegador
• Interacciones con la UI

4. Checkpoints de Git

• Si el repositorio está bajo Git, crear un commit de checkpoint después de cada etapa TDD
• No hacer squash ni reescribir estos commits de checkpoint hasta completar el flujo de trabajo
• Cada mensaje de commit de checkpoint debe describir la etapa y la evidencia capturada exacta
• Contar solo commits creados en la rama activa actual para la tarea actual
• No tratar commits de otras ramas, trabajo anterior no relacionado o historial lejano de ramas como evidencia válida de checkpoint
• Antes de tratar un checkpoint como satisfecho, verificar que el commit sea alcanzable desde el HEAD actual en la rama activa y pertenezca a la secuencia de la tarea actual
• El flujo de trabajo compacto preferido es:
• un commit para la prueba fallida agregada y ROJO validado
• un commit para la corrección mínima aplicada y VERDE validado
• un commit opcional para refactor completo
• No se requieren commits separados solo de evidencia si el commit de prueba claramente corresponde a ROJO y el commit de corrección claramente corresponde a VERDE

Pasos del Flujo de Trabajo TDD

Paso 1: Escribir Journeys de Usuario

Como [rol], quiero [acción], para que [beneficio]

Ejemplo:
Como usuario, quiero buscar mercados semánticamente,
para encontrar mercados relevantes incluso sin palabras clave exactas.

Paso 2: Generar Casos de Prueba

Para cada journey de usuario, crear casos de prueba completos:

describe('Semantic Search', () => {
  it('returns relevant markets for query', async () => {
    // Implementación de la prueba
  })

  it('handles empty query gracefully', async () => {
    // Probar caso borde
  })

  it('falls back to substring search when Redis unavailable', async () => {
    // Probar comportamiento de fallback
  })

  it('sorts results by similarity score', async () => {
    // Probar lógica de ordenamiento
  })
})

Paso 3: Ejecutar Pruebas (Deben Fallar)

npm test
# Las pruebas deben fallar — aún no hemos implementado

Este paso es obligatorio y es la compuerta ROJO para todos los cambios en producción.

Antes de modificar lógica de negocio u otro código de producción, se debe verificar un estado ROJO válido mediante una de estas rutas:

• ROJO en tiempo de ejecución:
• El objetivo de la prueba relevante compila exitosamente
• La prueba nueva o modificada se ejecuta efectivamente
• El resultado es ROJO
• ROJO en tiempo de compilación:
• La nueva prueba instancia, referencia o ejercita la ruta del código con el bug
• El fallo de compilación es en sí mismo la señal ROJO intencionada
• En cualquier caso, el fallo está causado por el bug de lógica de negocio, comportamiento indefinido o implementación faltante prevista
• El fallo no está causado solo por errores de sintaxis no relacionados, configuración de pruebas rota, dependencias faltantes o regresiones no relacionadas

Una prueba que solo se escribió pero no se compiló y ejecutó no cuenta como ROJO.

No editar código de producción hasta que este estado ROJO esté confirmado.

Si el repositorio está bajo Git, crear un commit de checkpoint inmediatamente después de que esta etapa esté validada. Formato de mensaje de commit recomendado:

• test: add reproducer for
• Este commit también puede servir como checkpoint de validación ROJO si el reproductor fue compilado, ejecutado y falló por la razón prevista
• Verificar que este commit de checkpoint esté en la rama activa actual antes de continuar

Paso 4: Implementar el Código

Escribir 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í
}

Si el repositorio está bajo Git, preparar la corrección mínima ahora pero diferir el commit de checkpoint hasta que VERDE esté validado en el Paso 5.

Paso 5: Ejecutar Pruebas Nuevamente

npm test
# Las pruebas ahora deben pasar

Volver a ejecutar el mismo objetivo de prueba relevante después de la corrección y confirmar que la prueba anteriormente fallida ahora está en VERDE.

Solo después de un resultado VERDE válido se puede proceder a refactorizar.

Si el repositorio está bajo Git, crear un commit de checkpoint inmediatamente después de que VERDE esté validado. Formato de mensaje de commit recomendado:

• fix:
• El commit de corrección también puede servir como checkpoint de validación VERDE si el mismo objetivo de prueba relevante fue re-ejecutado y pasó
• Verificar que este commit de checkpoint esté en la rama activa actual antes de continuar

Paso 6: Refactorizar

Mejorar la calidad del código manteniendo las pruebas en verde:

• Eliminar duplicación
• Mejorar nombres
• Optimizar rendimiento
• Mejorar legibilidad

Si el repositorio está bajo Git, crear un commit de checkpoint inmediatamente después de que el refactor esté completo y las pruebas sigan en verde. Formato de mensaje de commit recomendado:

• refactor: clean up after implementation
• Verificar que este commit de checkpoint esté en la rama activa actual antes de considerar el ciclo TDD completo

Paso 7: Verificar Cobertura

npm run test:coverage
# Verificar que se alcanzó 80%+ de cobertura

Patrones de Prueba

Patrón de Prueba Unitaria (Jest/Vitest)

import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './Button'

describe('Button Component', () => {
  it('renders with correct text', () => {
    render(<Button>Click me</Button>)
    expect(screen.getByText('Click me')).toBeInTheDocument()
  })

  it('calls onClick when clicked', () => {
    const handleClick = jest.fn()
    render(<Button onClick={handleClick}>Click</Button>)

    fireEvent.click(screen.getByRole('button'))

    expect(handleClick).toHaveBeenCalledTimes(1)
  })

  it('is disabled when disabled prop is true', () => {
    render(<Button disabled>Click</Button>)
    expect(screen.getByRole('button')).toBeDisabled()
  })
})

Patrón de Prueba de Integración de API

import { NextRequest } from 'next/server'
import { GET } from './route'

describe('GET /api/markets', () => {
  it('returns markets successfully', 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('validates query parameters', async () => {
    const request = new NextRequest('http://localhost/api/markets?limit=invalid')
    const response = await GET(request)

    expect(response.status).toBe(400)
  })

  it('handles database errors gracefully', async () => {
    // Mockear 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('user can search and filter markets', async ({ page }) => {
  // Navegar a la página de mercados
  await page.goto('/')
  await page.click('a[href="/markets"]')

  // Verificar que la página cargó
  await expect(page.locator('h1')).toContainText('Markets')

  // Buscar mercados
  await page.fill('input[placeholder="Search markets"]', 'election')

  // Esperar debounce y resultados
  await page.waitForTimeout(600)

  // Verificar resultados de búsqueda mostrados
  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('election', { ignoreCase: true })

  // Filtrar por estado
  await page.click('button:has-text("Active")')

  // Verificar resultados filtrados
  await expect(results).toHaveCount(3)
})

test('user can create a new market', async ({ page }) => {
  // Hacer login primero
  await page.goto('/creator-dashboard')

  // Completar formulario de creación de mercado
  await page.fill('input[name="name"]', 'Test Marke

Organización de Archivos de Prueba

src/
├── components/
│   ├── 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

Mocking de Servicios Externos