name: diretrizes-testes description: Use ao escrever testes ou fazer TDD: novas funcionalidades, correções de bugs, refatorações. Impõe o desenvolvimento orientado a testes com cobertura mínima de 80% em testes unitários, de integração e E2E. Acionado por /tests-guidelines, "tests", "coverage", "unit test", "integration test", "TDD". license: MIT source: https://github.com/affaan-m/everything-claude-code (skill tdd-workflow, MIT), adaptado
Fluxo de Trabalho de Desenvolvimento Orientado a Testes
Esta habilidade garante que todo o desenvolvimento de código siga os princípios TDD com cobertura abrangente de testes.
Quando Ativar
- Escrevendo novas funcionalidades ou funcionalidades
- Corrigindo bugs ou problemas
- Refatorando código existente
- Adicionando endpoints de API
- Criando novos componentes
Princípios Fundamentais
1. Testes ANTES do Código
Sempre escreva os testes PRIMEIRO, depois implemente o código para fazer os testes passarem.
2. Requisitos de Cobertura
- Mínimo de 80% de cobertura (unitário + integração + E2E)
- Todos os casos de borda cobertos
- Cenários de erro testados
- Condições de limite verificadas
3. Tipos de Teste
Testes Unitários
- Funções e utilitários individuais
- Lógica de componentes
- Funções puras
- Helpers e utilitários
Testes de Integração
- Endpoints de API
- Operações de banco de dados
- Interações entre serviços
- Chamadas de API externas
Testes E2E (Playwright)
- Fluxos críticos do usuário
- Fluxos de trabalho completos
- Automação de navegador
- Interações de interface
Etapas do Fluxo de Trabalho TDD
Etapa 0: Detectar o Executor de Testes
Não assuma npm test. Os comandos nas etapas e exemplos abaixo usam <test>, <test-watch> e <coverage> como placeholders para o executor real do projeto. Resolva-os uma vez antes de começar:
-
Encontre o executor do projeto. Leia
package.json(packageManager,scripts.test), o arquivo de lockfile,pyproject.toml/pytest.ini,go.mod,Cargo.toml. A primeira correspondência vence; não assumanpm test. -
Distinga o gerenciador de pacotes do executor de testes. Eles não são a mesma coisa. Um projeto pode usar Bun para instalar dependências, mas ainda executar Jest ou Vitest. Inspecione
package.jsonscripts.teste os arquivos de teste:scripts.testinvocajest/vitest-> execute através do PM detectado (npm test,pnpm test,yarn test, oubun run test).scripts.testébun test, ou arquivos de testeimport { test, expect } from "bun:test", ou não há configuração jest/vitest, mas Bun está presente -> use o executor nativo do Bun (bun test). Veja Padrão de Teste Nativo Bun abaixo.- Python:
<test>=pytest,<coverage>=pytest --cov --cov-fail-under=80. Go:go test ./...ego test -cover ./.... Rust:cargo test.
Matriz de comandos do executor:
| Executor | <test> | <test-watch> | <coverage> | <lint> |
|---|---|---|---|---|
| npm | npm test | npm test -- --watch | npm run test:coverage | npm run lint |
| pnpm | pnpm test | pnpm test --watch | pnpm test:coverage | pnpm lint |
| yarn | yarn test | yarn test --watch | yarn test:coverage | yarn lint |
| Bun (script executa jest/vitest) | bun run test | bun run test --watch | bun run test:coverage | bun run lint |
Bun (nativo bun:test) | bun test | bun test --watch | bun test --coverage | bun run lint |
bun test(executor interno do Bun) não é o mesmo quebun run test(que executa o scripttestdopackage.json). Escolher o errado é uma falha comum - por exemplo, invocar Jest através denpx/bun runem um projeto exclusivo ESM quebra, enquantobun testexecuta a suíte nativamente. Confirme qual o projeto espera antes da barreira VERMELHA, então substitua<test>/<coverage>em todos os lugares ondenpm testaparece abaixo.
Etapa 1: Escrever Jornadas do Usuário
Como um [papel], quero [ação], para que [benefício]
Exemplo:
Como um usuário, quero pesquisar mercados semanticamente,
para que eu possa encontrar mercados relevantes mesmo sem palavras-chave exatas.
Etapa 2: Gerar Casos de Teste
Para cada jornada do usuário, crie casos de teste abrangentes:
describe('Pesquisa Semântica', () => {
it('retorna mercados relevantes para a consulta', async () => {
// Implementação do teste
})
it('trata consulta vazia graciosamente', async () => {
// Teste de caso de borda
})
it('recorre à pesquisa por substring quando Redis está indisponível', async () => {
// Teste de comportamento de fallback
})
it('ordena resultados por pontuação de similaridade', async () => {
// Teste de lógica de ordenação
})
})
Etapa 3: Executar Testes (Eles Devem Falhar)
<test>
# Testes devem falhar - ainda não implementamos
Etapa 4: Implementar Código
Escreva código mínimo para fazer os testes passarem:
// Implementação guiada pelos testes
export async function searchMarkets(query: string) {
// Implementação aqui
}
Etapa 5: Executar Testes Novamente
<test>
# Testes agora devem passar
Etapa 6: Refatorar
Melhore a qualidade do código mantendo os testes verdes:
- Remover duplicação
- Melhorar nomenclatura
- Otimizar desempenho
- Melhorar legibilidade
Etapa 7: Verificar Cobertura
<coverage>
# Verificar se 80%+ de cobertura foi alcançada
Padrões de Teste
Padrão de Teste Unitário (Jest/Vitest)
import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './Button'
describe('Componente Button', () => {
it('renderiza com o texto correto', () => {
render(<Button>Clique em mim</Button>)
expect(screen.getByText('Clique em mim')).toBeInTheDocument()
})
it('chama onClick quando clicado', () => {
const handleClick = jest.fn()
render(<Button onClick={handleClick}>Clique</Button>)
fireEvent.click(screen.getByRole('button'))
expect(handleClick).toHaveBeenCalledTimes(1)
})
it('está desabilitado quando a prop disabled é true', () => {
render(<Button disabled>Clique</Button>)
expect(screen.getByRole('button')).toBeDisabled()
})
})
Padrão de Teste Nativo Bun (bun:test)
Quando o projeto usa o executor interno do Bun (veja Etapa 0), importe de bun:test e execute com bun test - não bun run test. A API é semelhante ao Jest, então describe / it / expect e a maioria dos matchers funcionam.
import { describe, it, expect, mock } from 'bun:test'
import { searchMarkets } from './search'
describe('searchMarkets', () => {
it('retorna uma lista vazia para uma consulta vazia', async () => {
expect(await searchMarkets('')).toEqual([])
})
it('ordena resultados por pontuação de similaridade', async () => {
const results = await searchMarkets('eleição')
expect(results).toEqual([...results].sort((a, b) => b.score - a.score))
})
})
bun test # executar uma vez (barreira VERMELHA/VERDE)
bun test --watch # modo de observação durante o desenvolvimento
bun test --coverage # relatório de cobertura
- Módulos mock com
mock.module(...)/mock(...)debun:testem vez dejest.mock(...). - Configure limites de cobertura em
bunfig.tomlsob[test](ex.:coverageThreshold) em vez do bloco de configuraçãocoverageThresholdsdo Jest.
Padrão de Teste de Integração de API
import { NextRequest } from 'next/server'
import { GET } from './route'
describe('GET /api/markets', () => {
it('retorna mercados com sucesso', 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('valida parâmetros de consulta', async () => {
const request = new NextRequest('http://localhost/api/markets?limit=invalido')
const response = await GET(request)
expect(response.status).toBe(400)
})
it('trata erros de banco de dados graciosamente', async () => {
// Simular falha no banco de dados
const request = new NextRequest('http://localhost/api/markets')
// Testar tratamento de erro
})
})
Padrão de Teste E2E (Playwright)
import { test, expect } from '@playwright/test'
test('usuário pode pesquisar e filtrar mercados', async ({ page }) => {
// Navegar para a página de mercados
await page.goto('/')
await page.click('a[href="/markets"]')
// Verificar se a página carregou
await expect(page.locator('h1')).toContainText('Mercados')
// Pesquisar mercados
await page.fill('input[placeholder="Pesquisar mercados"]', 'eleição')
// Aguardar debounce e resultados
await page.waitForTimeout(600)
// Verificar se os resultados da pesquisa são exibidos
const results = page.locator('[data-testid="market-card"]')
await expect(results).toHaveCount(5, { timeout: 5000 })
// Verificar se os resultados contêm o termo da pesquisa
const firstResult = results.first()
await expect(firstResult).toContainText('eleição', { ignoreCase: true })
// Filtrar por status
await page.click('button:has-text("Ativo")')
// Verificar resultados filtrados
await expect(results).toHaveCount(3)
})
test('usuário pode criar um novo mercado', async ({ page }) => {
// Fazer login primeiro
await page.goto('/painel-de-criacao')
// Preencher formulário de criação de mercado
await page.fill('input[name="name"]', 'Mercado de Teste')
await page.fill('textarea[name="description"]', 'Descrição de teste')
await page.fill('input[name="endDate"]', '2025-12-31')
// Enviar formulário
await page.click('button[type="submit"]')
// Verificar mensagem de sucesso
await expect(page.locator('text=Mercado criado com sucesso')).toBeVisible()
// Verificar redirecionamento para a página do mercado
await expect(page).toHaveURL(/\/markets\/mercado-de-teste/)
})
Organização dos Arquivos de Teste
src/
├── components/
│ ├── Button/
│ │ ├── Button.tsx
│ │ ├── Button.test.tsx # Testes unitários
│ │ └── Button.stories.tsx # Storybook
│ └── MarketCard/
│ ├── MarketCard.tsx
│ └── MarketCard.test.tsx
├── app/
│ └── api/
│ └── markets/
│ ├── route.ts
│ └── route.test.ts # Testes de integração
└── e2e/
├── markets.spec.ts # Testes E2E
├── trading.spec.ts
└── auth.spec.ts
Simulação de Serviços Externos
Mock do Supabase
jest.mock('@/lib/supabase', () => ({
supabase: {
from: jest.fn(() => ({
select: jest.fn(() => ({
eq: jest.fn(() => Promise.resolve({
data: [{ id: 1, name: 'Mercado de Teste' }],
error: null
}))
}))
}))
}
}))
Mock do Redis
jest.mock('@/lib/redis', () => ({
searchMarketsByVector: jest.fn(() => Promise.resolve([
{ slug: 'mercado-teste', similarity_score: 0.95 }
])),
checkRedisHealth: jest.fn(() => Promise.resolve({ connected: true }))
}))
Mock do OpenAI
jest.mock('@/lib/openai', () => ({
generateEmbedding: jest.fn(() => Promise.resolve(
new Array(1536).fill(0.1) // Mock de embedding de 1536 dimensões
))
}))
Verificação de Cobertura de Teste
Executar Relatório de Cobertura
<coverage>
Limites de Cobertura
{
"jest": {
"coverageThresholds": {
"global": {
"branches": 80,
"functions": 80,
"lines": 80,
"statements": 80
}
}
}
}
Erros Comuns de Teste a Evitar
FALHA: ERRADO: Testar Detalhes de Implementação
// Não testar estado interno
expect(component.state.count).toBe(5)
PASSOU: CORRETO: Testar Comportamento Visível ao Usuário
// Testar o que os usuários veem
expect(screen.getByText('Contagem: 5')).toBeInTheDocument()
FALHA: ERRADO: Seletores Frágeis
// Quebra facilmente
await page.click('.css-class-xyz')
PASSOU: CORRETO: Seletores Semânticos
// Resiliente a mudanças
await page.click('button:has-text("Enviar")')
await page.click('[data-testid="submit-button"]')
FALHA: ERRADO: Sem Isolamento de Teste
// Testes dependem uns dos outros
test('cria usuário', () => { /* ... */ })
test('atualiza mesmo usuário', () => { /* depende do teste anterior */ })
PASSOU: CORRETO: Testes Independentes
// Cada teste configura seus próprios dados
test('cria usuário', () => {
const user = createTestUser()
// Lógica do teste
})
test('atualiza usuário', () => {
const user = createTestUser()
// Lógica de atualização
})
Testes Contínuos
Modo de Observação Durante o Desenvolvimento
<test-watch>
# Testes executados automaticamente em alterações de arquivos
Hook Pré-Commit
# Executa antes de cada commit
<test> && <lint>
Integração CI/CD
# GitHub Actions
- name: Executar Testes
run: <coverage>
- name: Enviar Cobertura
uses: codecov/codecov-action@v3
Melhores Práticas
- Escreva Testes Primeiro - Sempre TDD
- Uma Afirmação por Teste - Foco em comportamento único
- Nomes Descritivos de Teste - Explique o que está sendo testado
- Arrange-Act-Assert - Estrutura clara de teste
- Simular Dependências Externas - Isolar testes unitários
- Testar Casos de Borda - Nulo, indefinido, vazio, grande
- Testar Caminhos de Erro - Não apenas caminhos felizes
- Manter Testes Rápidos - Testes unitários < 50ms cada
- Limpar Após os Testes - Sem efeitos colaterais
- Revisar Relatórios de Cobertura - Identificar lacunas
Métricas de Sucesso
- 80%+ de cobertura de código alcançada
- Todos os testes passando (verde)
- Nenhum teste ignorado ou desabilitado
- Execução rápida dos testes (< 30s para testes unitários)
- Testes E2E cobrindo fluxos críticos do usuário
- Testes capturam bugs antes da produção
Lembre-se: Testes não são opcionais. Eles são a rede de segurança que permite refatoração confiante, desenvolvimento rápido e confiabilidade em produção.