tdd-workflow

name	tdd-workflow
description	Usar este skill al escribir nuevas funcionalidades, corregir bugs o refactorizar código. Aplica el desarrollo guiado por pruebas con 80%+ de cobertura incluyendo pruebas unitarias, de integración y E2E.
origin	ECC

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

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

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 Market')
  await page.fill('textarea[name="description"]', 'Test description')
  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=Market created successfully')).toBeVisible()

  // Verificar redirección a la página del mercado
  await expect(page).toHaveURL(/\/markets\/test-market/)
})

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

Mock de Supabase

jest.mock('@/lib/supabase', () => ({
  supabase: {
    from: jest.fn(() => ({
      select: jest.fn(() => ({
        eq: jest.fn(() => Promise.resolve({
          data: [{ id: 1, name: 'Test Market' }],
          error: null
        }))
      }))
    }))
  }
}))

Mock 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 }))
}))

Mock de OpenAI

jest.mock('@/lib/openai', () => ({
  generateEmbedding: jest.fn(() => Promise.resolve(
    new Array(1536).fill(0.1) // Mock de embedding de 1536 dimensiones
  ))
}))

Verificación de Cobertura de Pruebas

Ejecutar Reporte de Cobertura

npm run test:coverage

Umbrales de Cobertura

{
  "jest": {
    "coverageThresholds": {
      "global": {
        "branches": 80,
        "functions": 80,
        "lines": 80,
        "statements": 80
      }
    }
  }
}

Errores Comunes de Pruebas a Evitar

FALLA: INCORRECTO: Probar Detalles de Implementación

// No probar estado interno
expect(component.state.count).toBe(5)

PASA: CORRECTO: Probar Comportamiento Visible para el Usuario

// Probar lo que los usuarios ven
expect(screen.getByText('Count: 5')).toBeInTheDocument()

FALLA: INCORRECTO: Selectores Frágiles

// Se rompe fácilmente
await page.click('.css-class-xyz')

PASA: CORRECTO: Selectores Semánticos

// Resiliente a cambios
await page.click('button:has-text("Submit")')
await page.click('[data-testid="submit-button"]')

FALLA: INCORRECTO: Sin Aislamiento de Pruebas

// Las pruebas dependen unas de otras
test('creates user', () => { /* ... */ })
test('updates same user', () => { /* depende de la prueba anterior */ })

PASA: CORRECTO: Pruebas Independientes

// Cada prueba configura sus propios datos
test('creates user', () => {
  const user = createTestUser()
  // Lógica de prueba
})

test('updates user', () => {
  const user = createTestUser()
  // Lógica de actualización
})

Pruebas Continuas

Modo Watch Durante el Desarrollo

npm test -- --watch
# Las pruebas se ejecutan automáticamente al cambiar archivos

Hook Pre-Commit

# Se ejecuta antes de cada commit
npm test && npm run lint

Integración CI/CD

# GitHub Actions
- name: Run Tests
  run: npm test -- --coverage
- name: Upload Coverage
  uses: codecov/codecov-action@v3

Buenas Prácticas

1. Escribir Pruebas Primero — Siempre TDD
2. Una Aserción por Prueba — Enfocarse en un solo comportamiento
3. Nombres de Prueba Descriptivos — Explicar qué se prueba
4. Arrange-Act-Assert — Estructura clara de la prueba
5. Mockear Dependencias Externas — Aislar pruebas unitarias
6. Probar Casos Borde — Null, undefined, vacío, grande
7. Probar Rutas de Error — No solo los caminos felices
8. Mantener Pruebas Rápidas — Pruebas unitarias < 50ms cada una
9. Limpiar Después de las Pruebas — Sin efectos secundarios
10. Revisar Reportes de Cobertura — Identificar gaps

Métricas de Éxito

• 80%+ de cobertura de código alcanzada
• Todas las pruebas pasando (verde)
• Sin pruebas omitidas o deshabilitadas
• Ejecución rápida de pruebas (< 30s para pruebas unitarias)
• Pruebas E2E cubren flujos críticos de usuario
• Las pruebas detectan bugs antes de producción

---

Recuerda: Las pruebas no son opcionales. Son la red de seguridad que permite refactorización con confianza, desarrollo rápido y confiabilidad en producción.