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:
- 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:
| Indicador | Executor | Comando de cobertura |
|---|---|---|
"vitest" em devDependencies | Vitest | npx vitest --coverage |
"jest" em devDependencies | Jest | npx jest --coverage |
"react-scripts" em devDependencies | react-scripts (Jest) | npx react-scripts test --coverage |
"next" em devDependencies | Next.js (Jest) | npx next test --coverage ou verifique jest.config |
"@angular/core" em dependencies | Angular (Karma/Jasmine) | ng test --code-coverage |
"@playwright/test" em devDependencies | Playwright | npx playwright test (sem cobertura nativa; use @playwright/test com istanbul) |
"mocha" em devDependencies | Mocha | npx mocha (cobertura via c8/nyc) |
"cypress" em devDependencies | Cypress | npx cypress run (cobertura via @cypress/code-coverage) |
"ava" em devDependencies | AVA | npx ava (cobertura via c8) |
| Nenhum encontrado | Nenhum → 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.tsxousrc/components/__tests__/Button.test.tsxsrc/utils/format.ts→src/utils/format.test.tsousrc/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:
- Leia o arquivo fonte
- 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
- Gere o arquivo de teste seguindo as convenções do projeto:
- Use a API do executor de testes detectado (
describe/it/expectpara 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
- Use a API do executor de testes detectado (
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:
| Executor | Comando |
|---|---|
| Vitest | npx vitest --coverage --reporter=verbose |
| Jest | npx jest --coverage --verbose |
| react-scripts | npx react-scripts test --coverage --watchAll=false |
| Outros | Use 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%):
- Leia o arquivo fonte e seu arquivo de teste lado a lado
- Entenda o que as linhas/funções/ramos não cobertos fazem
- Identifique quais casos de borda estão faltando nos testes
- Escreva testes direcionados para cobrir as lacunas:
- Ramos não cobertos: Teste ambos os caminhos
ifeelse, 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 */
- Vitest/V8:
- 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:
src/app/(diretório app do Next.js)components/lib/utils/server/(Next.js/Node.js)pages/(diretório pages do Next.js)- Arquivos
*.ts/*.tsxno nível raiz
Exemplo
Usuário: "o relatório de cobertura mostra login.ts em 72%, corrija"
Ações do agente:
- Execute
npx vitest --coverage --reporter=verbose, veja login.ts com linhas não cobertas 45-52 (ramo de erro devalidateEmail) - Leia o fonte, entenda que
validateEmaillança exceção em emails inválidos - Adicione casos de teste para entradas de email inválidas em
login.test.ts - Execute novamente a cobertura — login.ts agora em 100%
Usuário: "usamos jest, verifique a cobertura"
- Execute
npx jest --coverage --verbose, identifique arquivos não cobertos - Encontre
src/components/Header.tsxem 0% — nenhum teste existe - Leia o fonte de Header.tsx, crie
src/components/Header.test.tsx - Execute cobertura novamente — Header.tsx agora em 100%
Usuário: "não há configuração de teste neste projeto, adicione cobertura"
- Detecte nenhum executor de teste em package.json
- Pergunte ao usuário: "Nenhum framework de teste detectado. Instalar Vitest? (Recomendado)"
- Usuário confirma → instale vitest + @vitest/coverage-v8, crie vitest.config.ts
- Examine src/, encontre 8 arquivos fonte, 0 arquivos de teste
- Escreva testes para todos os 8 arquivos
- Execute cobertura — todos em 100%