teqo-backup/docs/plans/ops90-skills-piramide-testes.md

79 lines
7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Skills e docs: codificar a pirâmide de testes (unit primeiro, int depois, E2E só com benefício real por fluxo)
Status: rascunho
Atualizado em: 2026-08-24
Issue: #838
Priority: P2
Impeccable: A — N/A (sem UI)
Rascunho UI: N/A — sem UI
Appetite: ~0,5–1 dia eng; um outcome verificável
Responsável: —
## Intenção
Revisar as skills de desenvolvimento do repo e os docs de teste para codificar, nos donos certos, a pirâmide de testes na ordem unit → int → e2e-com-benefício: preferir testes unitários para lógica pura, integração para fronteiras Payload/DB, e E2E **somente** quando o fluxo tiver benefício real (fluxo crítico de usuário, navegação/UX ou contrato de URL que as camadas inferiores não cobrem). É um meta-chore de guia de agente: não muda código de produto, não muda UI, não muda schema, e mantém a política OPS72 intacta.
## Persona e fluxo
- **Persona / contexto:** agentes que executam entregas (`work-issue`/`agent-work-issue`) e quem revisa (`code-review-and-quality`), apoiados por `test-driven-development` e `engineering-audit`.
- **Job principal:** escolher o nível de teste certo para cada mudança, com a ordem explícita unit→int→e2e-com-benefício, sem inventar métrica de gate.
- **Fluxo desejado:** ao planejar/executar uma entrega, consultar a skill que já orienta a escolha de nível → decidir o nível pela natureza da mudança (lógica pura→unit; cruza boundary API/DB→int; fluxo crítico/contrato de URL/UX real→e2e) → seguir a política OPS72 para rodar/gatear (local discricionário, CI `selected`, full só no verify do deploy) → na revisão, validar que o nível escolhido é o certo.
- **Anti-goals de produto:** NÃO virar um rewrite massivo de skills nem uma "cartilha de boas práticas" genérica; NÃO introduzir regra dura de % de cobertura nem proibição de e2e; NÃO mudar gate nem CI.
## Objetivo e aceite
- Ao planejar qualquer entrega, a decisão de nível de teste é orientada pela ordem unit→int→e2e-com-benefício, e a política OPS72 continua a valer intacta.
- O dono natural da pirâmide (`test-driven-development`) fica ancorado ao contexto Teqo (camadas de `tests/`, política OPS72), sem recriar a definição do zero.
- As skills de execução (`work-issue`) e de revisão (`code-review-and-quality`) enunciam a preferência de nível, ao lado das políticas de e2e já existentes.
- `docs/TESTING.md` e a linha das 3 camadas do mapa de codebase explicitam a ordem de preferência unit→int→e2e-com-benefício.
- Guardrails: política OPS72 intacta (gate local, CI blast radius `selected`, full só no verify do deploy); nenhuma regra de % de cobertura; nenhuma proibição de e2e.
## Dados (intenção)
- **Vou apresentar dados?** Não — meta-chore de guias; sem métrica de produto.
- **Decisões desbloqueadas:** N/A
## Direção no codebase (hipótese)
- **Áreas prováveis:**
- `.agents/skills/test-driven-development/SKILL.md` — reforçar a pirâmide existente (§144–186) e ancorar ao contexto Teqo; é o dono natural da ideia.
- `.agents/skills/work-issue/SKILL.md` + `execution-pipeline.md` — adicionar a preferência de nível à política e2e OPS72 já documentada.
- `.agents/skills/agent-work-issue/SKILL.md` — delegado ao pipeline; sem preferência própria (ação mínima ou nenhuma).
- `.agents/skills/browser-testing-with-devtools/SKILL.md` — reconhecer verificação em browser como caso legítimo de "e2e com benefício real" (unit não testa CSS/layout/rendering real).
- `.agents/skills/improve-code-quality/SKILL.md` e `.agents/skills/code-review-and-quality/SKILL.md` — checklist de nível de teste.
- `.agents/skills/ci-cd-and-automation/SKILL.md` — diagrama genérico unit→integration→e2e; confirmar que não precisa de mudança (é exemplo, não regra do repo).
- `.agents/skills/engineering-audit/SKILL.md` — avaliação por classes; sem preferência de nível (ação mínima ou nenhuma).
- `.agents/rules/codebase-map.mdc` (L26) e `docs/TESTING.md` — explicitar a ordem de preferência na definição das 3 camadas.
- `AGENTS.md`/`AGENTS-infra.md` — só gates e política OPS72; sem pirâmide explícita (ação mínima ou nenhuma).
- **Precedente a olhar:** OPS87 (#833) e OPS88 (#834) são engineering-e2e/CI — NÃO sobrepostos; `docs/TESTING.md` já materializa a preferência na prática ("maioria do comportamento de campanha pinada na camada int"; CI nunca full e2e) — o trabalho é codificar/fortalecer, não criar política nova.
- **Risco de acoplamento:** manter política OPS72 intacta (gate local, CI `selected`, full no verify); não criar guard que vigie conteúdo de skill neste item (os guards `tests/unit/opencodeCommands.unit.spec.ts` e `agentPoolPrompt.unit.spec.ts` acoplam comando↔skill por nome; `codebaseConventions.unit.spec.ts` não varre `.agents/skills` — decisão de engenharia, não deste plano).
## Dependências
- Nenhuma
## Fora de escopo
- OPS87/OPS88 (engineering de e2e/CI) — itens separados e não sobrepostos.
- Guards que vigiem conteúdo de skill (não criar neste item).
- Rewrite massivo de skills ou "cartilha de boas práticas" genérica.
## Rabbit holes de produto
- **Risco:** virar "documentação de boas práticas" sem dente → corte: mudança mínima, só nos donos listados, sem novo documento canônico.
- **Risco:** tocar na política OPS72 ao reescrever trechos de `work-issue`/`execution-pipeline.md` → corte: edição cirúrgica, preservando gate local/CI `selected`/full no verify.
- **Risco:** gastar tempo "harmonizando" skills que já estão consistentes (ex.: `agent-work-issue` é só delegação) → corte: ação mínima ou nenhuma onde não há lacuna real.
## Questões em aberto (produto)
- **Onde fixar a âncora canônica da pirâmide?** **Opções:** `test-driven-development` como dono da definição (A) | `docs/TESTING.md` como única fonte (B) | ambos. **Recomendação:** A — `test-driven-development` é o dono da definição, com `docs/TESTING.md` como referência operacional, evitando duplicação entre skills.
- **`browser-testing-with-devtools` ganha rótulo explícito de "e2e com benefício real"?** **Recomendação:** sim, uma linha de justificativa no fluxo desejado, sem mudar a skill.
- **`AGENTS.md`/`AGENTS-infra.md` recebem a pirâmide?** **Recomendação:** ação mínima — só se houver uma linha curta já dedicada a testes que a receba naturalmente; sem bloco novo.
## Referências
- `.agents/skills/test-driven-development/SKILL.md` (§144–186: pirâmide + Decision Guide)
- `.agents/skills/work-issue/SKILL.md` e `execution-pipeline.md` (política e2e OPS72)
- `.agents/skills/agent-work-issue/SKILL.md`, `browser-testing-with-devtools/SKILL.md`, `improve-code-quality/SKILL.md`, `code-review-and-quality/SKILL.md`, `ci-cd-and-automation/SKILL.md`, `engineering-audit/SKILL.md`
- `docs/TESTING.md`, `.agents/rules/codebase-map.mdc`, `AGENTS.md`, `AGENTS-infra.md`
- `tests/unit/opencodeCommands.unit.spec.ts`, `tests/unit/agentPoolPrompt.unit.spec.ts`, `tests/unit/codebaseConventions.unit.spec.ts` (contexto de guards, sem ação neste item)