CommunityRedacción y edicióngithub.com

sametcelikbicak/coverage-guard

Una habilidad de agente de IA que garantiza una cobertura de pruebas del 100% para cualquier proyecto JavaScript/TypeScript. Compatible con Vitest, Jest, react-scripts y otros ejecutores de pruebas. Funciona con opencode, Claude Code, Cursor, Windsurf y GitHub Copilot.

¿Qué es coverage-guard?

Esta habilidad permite a un agente de IA (como Claude Code, Cursor o GitHub Copilot) lograr una cobertura de pruebas del 100% en proyectos JavaScript y TypeScript de forma automática. El agente primero detecta el ejecutor de pruebas configurado (Vitest, Jest, react-scripts, etc.) y, si no encuentra ninguno, guía al usuario en la instalación interactiva del entorno. Luego escanea los archivos fuente, escribe pruebas unitarias para los componentes y funciones no cubiertos, y ejecuta el informe de cobertura. Finalmente, itera identificando líneas y ramas no cubiertas, añadiendo casos de prueba específicos hasta alcanzar el 100% en todas las métricas (sentencias, ramas, funciones y líneas). La habilidad está diseñada para ser compatible con múltiples plataformas de agentes y ejecutores de pruebas, y sigue las convenciones del proyecto (estructura de carpetas, estilo de simulación y formato de pruebas).

Compatible con✓Claude Code~Codex CLI✓Cursor✓OpenCode✓Windsurf
npx skills add sametcelikbicak/coverage-guard

Installed? Explore more Redacción y edición skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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:

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

IndicadorEjecutorComando de cobertura
"vitest" en devDependenciesVitestnpx vitest --coverage
"jest" en devDependenciesJestnpx jest --coverage
"react-scripts" en devDependenciesreact-scripts (Jest)npx react-scripts test --coverage
"next" en devDependenciesNext.js (Jest)npx next test --coverage o revisar jest.config
"@angular/core" en dependenciesAngular (Karma/Jasmine)ng test --code-coverage
"@playwright/test" en devDependenciesPlaywrightnpx playwright test (sin cobertura integrada; usar @playwright/test con istanbul)
"mocha" en devDependenciesMochanpx mocha (cobertura mediante c8/nyc)
"cypress" en devDependenciesCypressnpx cypress run (cobertura mediante @cypress/code-coverage)
"ava" en devDependenciesAVAnpx ava (cobertura mediante c8)
No encontradoNinguno → 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.tsx o src/components/__tests__/Button.test.tsx
  • src/utils/format.ts → src/utils/format.test.ts o src/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:

  1. Lee el archivo fuente
  2. 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
  3. Genera el archivo de prueba siguiendo las convenciones del proyecto:
    • Usa la API del ejecutor de pruebas detectado (describe/it/expect para 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

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:

EjecutorComando
Vitestnpx vitest --coverage --reporter=verbose
Jestnpx jest --coverage --verbose
react-scriptsnpx react-scripts test --coverage --watchAll=false
OtrosUsa 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%):

  1. Lee el archivo fuente y su archivo de prueba uno al lado del otro
  2. Comprende qué hacen las líneas/funciones/ramas no cubiertas
  3. Identifica qué casos límite faltan en las pruebas
  4. Escribe pruebas específicas para cubrir los huecos:
  • Ramas no cubiertas: Prueba ambas rutas de if y else, 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 */
  • 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:

  1. src/
  2. app/ (directorio de la aplicación Next.js)
  3. components/
  4. lib/
  5. utils/
  6. server/ (Next.js/Node.js)
  7. pages/ (directorio de páginas Next.js)
  8. Archivos *.ts / *.tsx en la raíz

Ejemplo

Usuario: "el informe de cobertura muestra login.ts al 72%, arréglalo"

Acciones del agente:

  1. Ejecuta npx vitest --coverage --reporter=verbose, ve que login.ts tiene líneas no cubiertas 45-52 (rama de error de validateEmail)
  2. Lee el código fuente, comprende que validateEmail lanza una excepción en correos electrónicos no válidos
  3. Añade casos de prueba para entradas de correo electrónico no válidas en login.test.ts
  4. Vuelve a ejecutar la cobertura — login.ts ahora al 100%

Usuario: "usamos jest, comprueba la cobertura"

  1. Ejecuta npx jest --coverage --verbose, identifica archivos no cubiertos
  2. Encuentra src/components/Header.tsx al 0% — no existe prueba
  3. Lee el código fuente de Header.tsx, crea src/components/Header.test.tsx
  4. Ejecuta la cobertura de nuevo — Header.tsx ahora al 100%

Usuario: "no hay configuración de pruebas en este proyecto, añade cobertura"

  1. Detecta que no hay ejecutor de pruebas en package.json
  2. Pregunta al usuario: "No se detectó ningún framework de pruebas. ¿Instalar Vitest? (Recomendado)"
  3. El usuario confirma → instala vitest + @vitest/coverage-v8, crea vitest.config.ts
  4. Escanea src/, encuentra 8 archivos fuente, 0 archivos de prueba
  5. Escribe pruebas para los 8 archivos
  6. Ejecuta la cobertura — todos al 100%

Skills relacionados