diretrizes-testes

Habilidade de codificação. 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".

O que é diretrizes-testes?

Esta habilidade implementa um fluxo de trabalho completo de Desenvolvimento Orientado a Testes (TDD) para agentes de IA, garantindo que todo código seja desenvolvido com testes escritos antes da implementação. Ela impõe uma cobertura mínima de 80% em três níveis: testes unitários (funções e componentes individuais), testes de integração (APIs, banco de dados e serviços externos) e testes E2E (fluxos críticos do usuário com Playwright). A habilidade detecta automaticamente o executor de testes do projeto (npm, pnpm, yarn, Bun nativo ou nativo do Python/Go/Rust) e fornece padrões de código prontos para Jest/Vitest, Bun e Playwright. Ao seguir este guia, os desenvolvedores garantem testes isolados, independentes e focados no comportamento visível ao usuário, evitando armadilhas comuns como testar detalhes de implementação ou usar seletores frágeis. O resultado é uma base de código robusta que permite refatoração confiante e entrega rápida com segurança contra regressões.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/orenatobr/tests-guidelines/tree/HEAD/skills/tests-guidelines

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

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

Documentação


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:

  1. 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 assuma npm test.

  2. 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.json scripts.test e os arquivos de teste:

    • scripts.test invoca jest / vitest -> execute através do PM detectado (npm test, pnpm test, yarn test, ou bun run test).
    • scripts.test é bun test, ou arquivos de teste import { 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 ./... e go test -cover ./.... Rust: cargo test.

Matriz de comandos do executor:

Executor<test><test-watch><coverage><lint>
npmnpm testnpm test -- --watchnpm run test:coveragenpm run lint
pnpmpnpm testpnpm test --watchpnpm test:coveragepnpm lint
yarnyarn testyarn test --watchyarn test:coverageyarn lint
Bun (script executa jest/vitest)bun run testbun run test --watchbun run test:coveragebun run lint
Bun (nativo bun:test)bun testbun test --watchbun test --coveragebun run lint

bun test (executor interno do Bun) não é o mesmo que bun run test (que executa o script test do package.json). Escolher o errado é uma falha comum - por exemplo, invocar Jest através de npx/bun run em um projeto exclusivo ESM quebra, enquanto bun test executa a suíte nativamente. Confirme qual o projeto espera antes da barreira VERMELHA, então substitua <test> / <coverage> em todos os lugares onde npm test aparece 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(...) de bun:test em vez de jest.mock(...).
  • Configure limites de cobertura em bunfig.toml sob [test] (ex.: coverageThreshold) em vez do bloco de configuração coverageThresholds do 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

  1. Escreva Testes Primeiro - Sempre TDD
  2. Uma Afirmação por Teste - Foco em comportamento único
  3. Nomes Descritivos de Teste - Explique o que está sendo testado
  4. Arrange-Act-Assert - Estrutura clara de teste
  5. Simular Dependências Externas - Isolar testes unitários
  6. Testar Casos de Borda - Nulo, indefinido, vazio, grande
  7. Testar Caminhos de Erro - Não apenas caminhos felizes
  8. Manter Testes Rápidos - Testes unitários < 50ms cada
  9. Limpar Após os Testes - Sem efeitos colaterais
  10. 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.

Habilidades Relacionadas