tdd-workflow

What this skill does

# 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:

```typescript
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)
```bash
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 <feature or bug>`
- 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:

```typescript
// 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
```bash
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: <feature or bug>`
- 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 <feature or bug> implementation`
- Verificar que este commit de checkpoint esté en la rama activa actual antes de considerar el ciclo TDD completo

### Paso 7: Verificar Cobertura
```bash
npm run test:coverage
# Verificar que se alcanzó 80%+ de cobertura
```

## Patrones de Prueba

### Patrón de Prueba Unitaria (Jest/Vitest)
```typescript
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
```typescript
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 NextReques