CommunityEscrita e Ediçãogithub.com

sametcelikbicak/coverage-guard

Uma habilidade para agente de IA que garante 100% de cobertura de testes em qualquer projeto JavaScript/TypeScript. Funciona com Vitest, Jest, react-scripts e outros executores de teste. Compatível com opencode, Claude Code, Cursor, Windsurf e GitHub Copilot.

O que é coverage-guard?

Esta skill automatiza o processo de alcançar e manter 100% de cobertura de testes em projetos JavaScript/TypeScript. Ela detecta automaticamente o executor de testes (Vitest, Jest, react-scripts, etc.), configura a infraestrutura de testes se estiver ausente, gera testes para arquivos não cobertos e identifica lacunas de cobertura, executando um loop iterativo até que cada arquivo atinja 100% de cobertura. O fluxo de trabalho é dividido em fases: detecção do ambiente, varredura de arquivos fonte e testes existentes, configuração da infraestrutura, geração de novos testes, execução da cobertura, análise e preenchimento de lacunas, verificação e repetição. A skill fornece exemplos detalhados para componentes React e funções utilitárias, bem como orientação sobre como lidar com dead code, mocks e casos de borda. É compatível com os principais assistentes de codificação AI e executores de teste modernos, tornando-se uma ferramenta essencial para equipes que buscam qualidade de código rigorosa.

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

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Coverage Guard

Garanta 100% de cobertura de testes para qualquer projeto JavaScript/TypeScript. Detecta automaticamente o executor de testes, configura a infraestrutura de testes se estiver faltando, escreve testes para componentes não cobertos e itera até que cada arquivo atinja 100% de cobertura.

Visão Geral

Esta skill segue um pipeline completo:

  1. Detectar executor e infraestrutura → 2. Examinar arquivos fonte e testes → 3. Configurar se estiver faltando → 4. Gerar novos testes → 5. Executar cobertura → 6. Preencher lacunas → 7. Verificar → repetir até 100%

Fluxo de Trabalho Passo a Passo

Fase 1: Detectar ambiente

Verifique o package.json na raiz do projeto para determinar:

cat package.json

Identifique o executor de testes e a ferramenta de cobertura:

IndicadorExecutorComando de cobertura
"vitest" em devDependenciesVitestnpx vitest --coverage
"jest" em devDependenciesJestnpx jest --coverage
"react-scripts" em devDependenciesreact-scripts (Jest)npx react-scripts test --coverage
"next" em devDependenciesNext.js (Jest)npx next test --coverage ou verifique jest.config
"@angular/core" em dependenciesAngular (Karma/Jasmine)ng test --code-coverage
"@playwright/test" em devDependenciesPlaywrightnpx playwright test (sem cobertura nativa; use @playwright/test com istanbul)
"mocha" em devDependenciesMochanpx mocha (cobertura via c8/nyc)
"cypress" em devDependenciesCypressnpx cypress run (cobertura via @cypress/code-coverage)
"ava" em devDependenciesAVAnpx ava (cobertura via c8)
Nenhum encontradoNenhum → prossiga para a Fase 2 → Fase 3 configuração

Fase 2: Examinar arquivos fonte e testes existentes

Encontre todos os arquivos fonte (componentes, módulos, utilitários) que precisam de testes:

# Diretórios de origem comuns
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/*"

Encontre todos os arquivos de teste existentes:

find src -type f \( -name "*.test.*" -o -name "*.spec.*" \) ! -path "*/node_modules/*"

Mapeie cada arquivo fonte para um arquivo de teste:

  • src/components/Button.tsx → src/components/Button.test.tsx ou src/components/__tests__/Button.test.tsx
  • src/utils/format.ts → src/utils/format.test.ts ou src/utils/__tests__/format.test.ts
  • Siga a convenção existente do projeto para a localização dos arquivos de teste

Classifique cada arquivo fonte:

  • Tem teste → adicionar à lista de análise de cobertura
  • Sem teste → marcar para geração de teste

Fase 3: Configurar infraestrutura de testes (se estiver faltando)

Se nenhum executor de testes foi detectado na Fase 1, pergunte ao usuário interativamente:

? Nenhum framework de teste detectado. Qual você gostaria de configurar?
  1) Vitest (Recomendado — rápido, moderno, ESM nativo)
  2) Jest (Mais amplamente utilizado)
  3) react-scripts (Create React App)
  4) Nenhum — pular, vou configurar manualmente

Depois que o usuário selecionar, instale as dependências e crie a configuração:

Configuração Vitest:

npm install -D vitest @vitest/coverage-v8

Crie 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',
      ],
    },
  },
})

Adicione aos scripts do package.json:

{
  "scripts": {
    "test": "vitest",
    "test:coverage": "vitest --coverage"
  }
}

Configuração 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

Crie jest.config.ts:

export default {
  testEnvironment: 'jsdom',
  transform: {
    '^.+\\.tsx?$': 'ts-jest',
  },
  coverageReporters: ['text', 'json', 'html'],
  collectCoverageFrom: ['src/**/*.{ts,tsx}', '!src/**/*.d.ts'],
}

Adicione aos scripts do package.json:

{
  "scripts": {
    "test": "jest",
    "test:coverage": "jest --coverage"
  }
}

Configuração react-scripts:

npm install -D @testing-library/react @testing-library/jest-dom @testing-library/user-event

A cobertura já vem integrada:

{
  "scripts": {
    "test": "react-scripts test",
    "test:coverage": "react-scripts test --coverage"
  }
}

Após a configuração, execute um teste rápido para confirmar que tudo funciona:

npm test

Se falhar, corrija os problemas de configuração antes de prosseguir.

Fase 4: Escrever testes para arquivos fonte não testados

Para cada arquivo fonte que não tem arquivo de teste, analise o código fonte:

  1. Leia o arquivo fonte
  2. Identifique:
    • Todas as funções, classes, componentes exportados
    • Tipos de retorno e possíveis caminhos de retorno
    • Parâmetros e seus tipos (obrigatórios, opcionais, valores padrão)
    • Interface de props (para componentes React)
    • Comportamento assíncrono (Promises, async/await)
    • Efeitos colaterais (chamadas de API, localStorage, etc.)
    • Estados de erro e casos de borda
  3. Gere o arquivo de teste seguindo as convenções do projeto:
    • Use a API do executor de testes detectado (describe/it/expect para Jest/Vitest, etc.)
    • Para React: use @testing-library/react (render, screen, fireEvent)
    • Mocke dependências externas
    • Cubra todos os ramos, casos de borda e caminhos de erro

Exemplo 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('renderiza com rótulo', () => {
    render(<Button label="Clique aqui" />)
    expect(screen.getByText('Clique aqui')).toBeInTheDocument()
  })

  it('chama onClick quando clicado', () => {
    const onClick = vi.fn() // jest.fn() para Jest
    render(<Button label="Clique" onClick={onClick} />)
    fireEvent.click(screen.getByText('Clique'))
    expect(onClick).toHaveBeenCalledTimes(1)
  })

  it('está desabilitado quando a prop disabled é true', () => {
    render(<Button label="Clique" disabled />)
    expect(screen.getByText('Clique')).toBeDisabled()
  })
})

Exemplo de função utilitária (src/utils/format.ts → src/utils/format.test.ts):

import { formatCurrency, truncate } from './format'

describe('formatCurrency', () => {
  it('formata valor inteiro', () => {
    expect(formatCurrency(1000)).toBe('$1,000.00')
  })

  it('formata valor decimal', () => {
    expect(formatCurrency(99.95)).toBe('$99.95')
  })

  it('lida com zero', () => {
    expect(formatCurrency(0)).toBe('$0.00')
  })

  it('lida com valores negativos', () => {
    expect(formatCurrency(-50)).toBe('-$50.00')
  })
})

Fase 5: Executar relatório de cobertura

Execute o comando de cobertura apropriado com base no executor detectado:

ExecutorComando
Vitestnpx vitest --coverage --reporter=verbose
Jestnpx jest --coverage --verbose
react-scriptsnpx react-scripts test --coverage --watchAll=false
OutrosUse o comando de cobertura configurado do projeto

Analise a saída para identificar:

  • Arquivos abaixo de 100% de cobertura
  • Linhas, ramos, funções e declarações não cobertas
  • Números de linha específicos que precisam de testes
  • Arquivos com 0% de cobertura (nenhum teste existe)

Fase 6: Analisar e preencher lacunas de cobertura

Para cada arquivo abaixo de 100% (incluindo arquivos da Fase 4 que agora têm testes, mas não estão em 100%):

  1. Leia o arquivo fonte e seu arquivo de teste lado a lado
  2. Entenda o que as linhas/funções/ramos não cobertos fazem
  3. Identifique quais casos de borda estão faltando nos testes
  4. Escreva testes direcionados para cobrir as lacunas:
  • Ramos não cobertos: Teste ambos os caminhos if e else, condições ternárias
  • Funções não cobertas: Teste todos os caminhos de retorno possíveis
  • Linhas não cobertas: Trace a lógica e escreva um caso que as alcance
  • Caminhos assíncronos não cobertos: Teste ramos de Promise resolvida e rejeitada
  • Tratamento de erro não coberto: Teste callbacks de erro, blocos catch, limites de erro

Use os padrões do executor de testes detectado:

  • Vitest: vi.mock(), vi.spyOn(), vi.fn()
  • Jest: jest.mock(), jest.spyOn(), jest.fn()
  • react-scripts: Mesmo que Jest

Fase 7: Verificar

Execute novamente a cobertura após adicionar/atualizar testes:

# Use o comando detectado
npx vitest --coverage   # para Vitest
npx jest --coverage      # para Jest

Confirme que todos os arquivos mostram 100% para declarações, ramos, funções e linhas.

Fase 8: Repetir

Se a cobertura ainda estiver abaixo de 100%, volte para a Fase 6.


Configuração por executor

Configuração de cobertura Vitest

Garanta que 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',
      ],
    },
  },
})

Configuração de cobertura Jest

Garanta que jest.config.ts contenha:

export default {
  collectCoverage: true,
  coverageReporters: ['text', 'json', 'html'],
  collectCoverageFrom: [
    'src/**/*.{ts,tsx,js,jsx}',
    '!src/**/*.d.ts',
    '!src/**/*.test.*',
    '!src/**/*.spec.*',
  ],
}

Dicas

  • Comece com arquivos que já têm testes, mas com cobertura baixa — vitórias mais rápidas
  • Depois, aborde arquivos não testados com a lógica mais simples primeiro
  • Para componentes React: teste renderização, interações do usuário, renderização condicional, estados de erro e estados vazios/carregamento
  • Para funções utilitárias: teste casos de borda (strings vazias, null/undefined, valores limite, caracteres especiais)
  • Para serviços de API: teste resposta de sucesso, resposta de erro, estado de carregamento, timeout e falha de rede
  • Se código morto for encontrado (impossível de cobrir), sugira removê-lo ou adicionar um comentário de ignorar cobertura:
    • Vitest/V8: /* c8 ignore next */ ou /* c8 ignore next 3 */
    • Jest/Istanbul: /* istanbul ignore next */ ou /* istanbul ignore if */
  • NÃO modifique a lógica do código fonte — apenas adicione ou atualize testes
  • Siga os padrões de teste existentes do projeto (nomenclatura de arquivos, estrutura de pastas, estilo de mocking)
  • Para arquivos com 0 testes, crie um arquivo de teste abrangente que atinja todos os caminhos principais primeiro, depois itere

Prioridade de detecção

Ao examinar arquivos fonte, verifique nesta ordem de estruturas de diretórios comuns:

  1. src/
  2. app/ (diretório app do Next.js)
  3. components/
  4. lib/
  5. utils/
  6. server/ (Next.js/Node.js)
  7. pages/ (diretório pages do Next.js)
  8. Arquivos *.ts / *.tsx no nível raiz

Exemplo

Usuário: "o relatório de cobertura mostra login.ts em 72%, corrija"

Ações do agente:

  1. Execute npx vitest --coverage --reporter=verbose, veja login.ts com linhas não cobertas 45-52 (ramo de erro de validateEmail)
  2. Leia o fonte, entenda que validateEmail lança exceção em emails inválidos
  3. Adicione casos de teste para entradas de email inválidas em login.test.ts
  4. Execute novamente a cobertura — login.ts agora em 100%

Usuário: "usamos jest, verifique a cobertura"

  1. Execute npx jest --coverage --verbose, identifique arquivos não cobertos
  2. Encontre src/components/Header.tsx em 0% — nenhum teste existe
  3. Leia o fonte de Header.tsx, crie src/components/Header.test.tsx
  4. Execute cobertura novamente — Header.tsx agora em 100%

Usuário: "não há configuração de teste neste projeto, adicione cobertura"

  1. Detecte nenhum executor de teste em package.json
  2. Pergunte ao usuário: "Nenhum framework de teste detectado. Instalar Vitest? (Recomendado)"
  3. Usuário confirma → instale vitest + @vitest/coverage-v8, crie vitest.config.ts
  4. Examine src/, encontre 8 arquivos fonte, 0 arquivos de teste
  5. Escreva testes para todos os 8 arquivos
  6. Execute cobertura — todos em 100%

Habilidades Relacionadas