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 Escribir Pruebas Primero — Siempre TDD Una Aserción por Prueba — Enfocarse en un solo comportamiento Nombres de Prueba Descriptivos — Explicar qué se prueba Arrange-Act-Assert — Estructura clara de la prueba Mockear Dependencias Externas — Aislar pruebas unitarias Probar Casos Borde — Null, undefined, vacío, grande Probar Rutas de Error — No solo los caminos felices Mantener Pruebas Rápidas — Pruebas unitarias < 50ms cada una Limpiar Después de las Pruebas — Sin efectos secundarios 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.