Coverage Guard
Garantiza una cobertura de pruebas del 100% para cualquier proyecto JavaScript/TypeScript. Detecta automáticamente el ejecutor de pruebas, configura la infraestructura de pruebas si falta, escribe pruebas para los componentes no cubiertos y repite el proceso hasta que todos los archivos alcancen el 100% de cobertura.
Resumen
Esta habilidad sigue un pipeline completo:
- Detectar ejecutor e infraestructura → 2. Escáner archivos fuente y pruebas → 3. Configurar si falta → 4. Generar nuevas pruebas → 5. Ejecutar cobertura → 6. Completar huecos → 7. Verificar → repetir hasta el 100%
Flujo de trabajo paso a paso
Fase 1: Detectar el entorno
Revisa package.json en la raíz del proyecto para determinar:
cat package.json
Identifica el ejecutor de pruebas y la herramienta de cobertura:
| Indicador | Ejecutor | Comando de cobertura |
|---|---|---|
"vitest" en devDependencies | Vitest | npx vitest --coverage |
"jest" en devDependencies | Jest | npx jest --coverage |
"react-scripts" en devDependencies | react-scripts (Jest) | npx react-scripts test --coverage |
"next" en devDependencies | Next.js (Jest) | npx next test --coverage o revisar jest.config |
"@angular/core" en dependencies | Angular (Karma/Jasmine) | ng test --code-coverage |
"@playwright/test" en devDependencies | Playwright | npx playwright test (sin cobertura integrada; usar @playwright/test con istanbul) |
"mocha" en devDependencies | Mocha | npx mocha (cobertura mediante c8/nyc) |
"cypress" en devDependencies | Cypress | npx cypress run (cobertura mediante @cypress/code-coverage) |
"ava" en devDependencies | AVA | npx ava (cobertura mediante c8) |
| No encontrado | Ninguno → pasar a la Fase 2 → Fase 3 de configuración |
Fase 2: Escanear archivos fuente y pruebas existentes
Busca todos los archivos fuente (componentes, módulos, utilidades) que necesitan pruebas:
# Directorios de origen comunes
find src -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) ! -name "*.test.*" ! -name "*.spec.*" ! -name "*.d.ts" ! -path "*/node_modules/*" ! -path "*/dist/*" ! -path "*/build/*" ! -path "*/.next/*"
Busca todos los archivos de prueba existentes:
find src -type f \( -name "*.test.*" -o -name "*.spec.*" \) ! -path "*/node_modules/*"
Asigna cada archivo fuente a un archivo de prueba:
src/components/Button.tsx→src/components/Button.test.tsxosrc/components/__tests__/Button.test.tsxsrc/utils/format.ts→src/utils/format.test.tsosrc/utils/__tests__/format.test.ts- Sigue la convención existente del proyecto para la ubicación de los archivos de prueba
Clasifica cada archivo fuente:
- Tiene prueba → añadir a la lista de análisis de cobertura
- Sin prueba → marcar para generación de pruebas
Fase 3: Configurar la infraestructura de pruebas (si falta)
Si no se detectó ningún ejecutor de pruebas en la Fase 1, pregunta al usuario de forma interactiva:
? No se detectó ningún framework de pruebas. ¿Cuál te gustaría configurar?
1) Vitest (Recomendado — rápido, moderno, ESM nativo)
2) Jest (El más usado)
3) react-scripts (Create React App)
4) Ninguno — saltar, lo configuraré manualmente
Una vez que el usuario selecciona, instala las dependencias y crea la configuración:
Configuración de Vitest:
npm install -D vitest @vitest/coverage-v8
Crea vitest.config.ts:
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html'],
exclude: [
'**/node_modules/**',
'**/dist/**',
'**/*.config.*',
'**/*.d.ts',
],
},
},
})
Añade a los scripts de package.json:
{
"scripts": {
"test": "vitest",
"test:coverage": "vitest --coverage"
}
}
Configuración de Jest:
npm install -D jest @types/jest ts-jest
npx ts-jest config:init
npm install -D jest @testing-library/react @testing-library/jest-dom jest-environment-jsdom
Crea jest.config.ts:
export default {
testEnvironment: 'jsdom',
transform: {
'^.+\\.tsx?$': 'ts-jest',
},
coverageReporters: ['text', 'json', 'html'],
collectCoverageFrom: ['src/**/*.{ts,tsx}', '!src/**/*.d.ts'],
}
Añade a los scripts de package.json:
{
"scripts": {
"test": "jest",
"test:coverage": "jest --coverage"
}
}
Configuración de react-scripts:
npm install -D @testing-library/react @testing-library/jest-dom @testing-library/user-event
La cobertura viene integrada:
{
"scripts": {
"test": "react-scripts test",
"test:coverage": "react-scripts test --coverage"
}
}
Después de la configuración, ejecuta una prueba rápida para confirmar que todo funciona:
npm test
Si falla, soluciona los problemas de configuración antes de continuar.
Fase 4: Escribir pruebas para archivos fuente sin probar
Para cada archivo fuente que no tiene archivo de prueba, analiza el código fuente:
- Lee el archivo fuente
- Identifica:
- Todas las funciones, clases y componentes exportados
- Tipos de retorno y posibles caminos de retorno
- Parámetros y sus tipos (requeridos, opcionales, valores predeterminados)
- Interfaz de props (para componentes React)
- Comportamiento asíncrono (Promesas, async/await)
- Efectos secundarios (llamadas a API, localStorage, etc.)
- Estados de error y casos límite
- Genera el archivo de prueba siguiendo las convenciones del proyecto:
- Usa la API del ejecutor de pruebas detectado (
describe/it/expectpara Jest/Vitest, etc.) - Para React: usa
@testing-library/react(render,screen,fireEvent) - Simula dependencias externas
- Cubre todas las ramas, casos límite y caminos de error
- Usa la API del ejecutor de pruebas detectado (
Ejemplo de componente React (src/components/Button.tsx → src/components/Button.test.tsx):
import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './Button'
describe('Button', () => {
it('se renderiza con la etiqueta', () => {
render(<Button label="Haz clic" />)
expect(screen.getByText('Haz clic')).toBeInTheDocument()
})
it('llama a onClick al hacer clic', () => {
const onClick = vi.fn() // jest.fn() para Jest
render(<Button label="Haz clic" onClick={onClick} />)
fireEvent.click(screen.getByText('Haz clic'))
expect(onClick).toHaveBeenCalledTimes(1)
})
it('está deshabilitado cuando la prop disabled es true', () => {
render(<Button label="Haz clic" disabled />)
expect(screen.getByText('Haz clic')).toBeDisabled()
})
})
Ejemplo de función utilitaria (src/utils/format.ts → src/utils/format.test.ts):
import { formatCurrency, truncate } from './format'
describe('formatCurrency', () => {
it('formatea cantidades enteras', () => {
expect(formatCurrency(1000)).toBe('$1,000.00')
})
it('formatea cantidades decimales', () => {
expect(formatCurrency(99.95)).toBe('$99.95')
})
it('maneja el cero', () => {
expect(formatCurrency(0)).toBe('$0.00')
})
it('maneja valores negativos', () => {
expect(formatCurrency(-50)).toBe('-$50.00')
})
})
Fase 5: Ejecutar el informe de cobertura
Ejecuta el comando de cobertura adecuado según el ejecutor detectado:
| Ejecutor | Comando |
|---|---|
| Vitest | npx vitest --coverage --reporter=verbose |
| Jest | npx jest --coverage --verbose |
| react-scripts | npx react-scripts test --coverage --watchAll=false |
| Otros | Usa el comando de cobertura configurado en el proyecto |
Analiza la salida para identificar:
- Archivos por debajo del 100% de cobertura
- Líneas, ramas, funciones y sentencias no cubiertas
- Números de línea específicos que necesitan pruebas
- Archivos con 0% de cobertura (no existen pruebas)
Fase 6: Analizar y completar los huecos de cobertura
Para cada archivo por debajo del 100% (incluyendo archivos de la Fase 4 que ahora tienen pruebas pero no están al 100%):
- Lee el archivo fuente y su archivo de prueba uno al lado del otro
- Comprende qué hacen las líneas/funciones/ramas no cubiertas
- Identifica qué casos límite faltan en las pruebas
- Escribe pruebas específicas para cubrir los huecos:
- Ramas no cubiertas: Prueba ambas rutas de
ifyelse, condiciones ternarias - Funciones no cubiertas: Prueba todos los caminos de retorno posibles
- Líneas no cubiertas: Rastrea la lógica y escribe un caso que las alcance
- Rutas asíncronas no cubiertas: Prueba ambas ramas de Promesas (resuelta y rechazada)
- Manejo de errores no cubierto: Prueba callbacks de error, bloques catch, límites de error
Usa los patrones del ejecutor de pruebas detectado:
- Vitest:
vi.mock(),vi.spyOn(),vi.fn() - Jest:
jest.mock(),jest.spyOn(),jest.fn() - react-scripts: Igual que Jest
Fase 7: Verificar
Vuelve a ejecutar la cobertura después de añadir/actualizar pruebas:
# Usa el comando detectado
npx vitest --coverage # para Vitest
npx jest --coverage # para Jest
Confirma que todos los archivos muestran el 100% en sentencias, ramas, funciones y líneas.
Fase 8: Repetir
Si la cobertura sigue por debajo del 100%, vuelve a la Fase 6.
Configuración por ejecutor
Configuración de cobertura de Vitest
Asegúrate de que vitest.config.ts contenga:
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html'],
exclude: [
'**/node_modules/**',
'**/dist/**',
'**/*.config.*',
'**/*.d.ts',
],
},
},
})
Configuración de cobertura de Jest
Asegúrate de que jest.config.ts contenga:
export default {
collectCoverage: true,
coverageReporters: ['text', 'json', 'html'],
collectCoverageFrom: [
'src/**/*.{ts,tsx,js,jsx}',
'!src/**/*.d.ts',
'!src/**/*.test.*',
'!src/**/*.spec.*',
],
}
Consejos
- Empieza con los archivos que ya tienen pruebas pero baja cobertura: son las ganancias más rápidas
- Luego aborda los archivos sin probar con la lógica más simple primero
- Para componentes React: prueba el renderizado, las interacciones del usuario, el renderizado condicional, los estados de error y los estados vacío/carga
- Para funciones utilitarias: prueba casos límite (cadenas vacías, null/undefined, valores límite, caracteres especiales)
- Para servicios API: prueba la respuesta exitosa, la respuesta de error, el estado de carga, el tiempo de espera y la falla de red
- Si se encuentra código muerto (imposible de cubrir), sugiere eliminarlo o añadir un comentario de ignorar cobertura:
- Vitest/V8:
/* c8 ignore next */o/* c8 ignore next 3 */ - Jest/Istanbul:
/* istanbul ignore next */o/* istanbul ignore if */
- Vitest/V8:
- NO modifiques la lógica del código fuente — solo añade o actualiza pruebas
- Sigue los patrones de prueba existentes del proyecto (nomenclatura de archivos, estructura de carpetas, estilo de simulación)
- Para archivos sin pruebas, crea un archivo de prueba completo que cubra las rutas principales primero, luego itera
Prioridad de detección
Al escanear archivos fuente, verifica en este orden de estructuras de directorios comunes:
src/app/(directorio de la aplicación Next.js)components/lib/utils/server/(Next.js/Node.js)pages/(directorio de páginas Next.js)- Archivos
*.ts/*.tsxen la raíz
Ejemplo
Usuario: "el informe de cobertura muestra login.ts al 72%, arréglalo"
Acciones del agente:
- Ejecuta
npx vitest --coverage --reporter=verbose, ve que login.ts tiene líneas no cubiertas 45-52 (rama de error devalidateEmail) - Lee el código fuente, comprende que
validateEmaillanza una excepción en correos electrónicos no válidos - Añade casos de prueba para entradas de correo electrónico no válidas en
login.test.ts - Vuelve a ejecutar la cobertura — login.ts ahora al 100%
Usuario: "usamos jest, comprueba la cobertura"
- Ejecuta
npx jest --coverage --verbose, identifica archivos no cubiertos - Encuentra
src/components/Header.tsxal 0% — no existe prueba - Lee el código fuente de Header.tsx, crea
src/components/Header.test.tsx - Ejecuta la cobertura de nuevo — Header.tsx ahora al 100%
Usuario: "no hay configuración de pruebas en este proyecto, añade cobertura"
- Detecta que no hay ejecutor de pruebas en package.json
- Pregunta al usuario: "No se detectó ningún framework de pruebas. ¿Instalar Vitest? (Recomendado)"
- El usuario confirma → instala vitest + @vitest/coverage-v8, crea vitest.config.ts
- Escanea src/, encuentra 8 archivos fuente, 0 archivos de prueba
- Escribe pruebas para los 8 archivos
- Ejecuta la cobertura — todos al 100%