teqo-backup/docs/plans/hardening-e2e-dev-compile-frio.md

Hardening e2e em dev: prewarm de rotas frias + login resiliente a compile

Status: rascunho Atualizado em: 2026-08-10 Issue: #586 Priority: P2 Model: composer-2.5 Impeccable: A — N/A (sem UI; infra de testes) Canvas UI: N/A — sem UI Appetite: ~0,5–1 dia eng; um outcome verificável Responsável: —

Intenção

Dois flakes e2e reproduzidos nesta sessão em dev (worktree, 2 workers) na suíte que a CI roda verde — a classe "compile-frio do dev server" que faz pnpm test:e2e local acusar vermelho em main verde:

1. campaignMunicipalities "coordinator opens the municipalities list, edits strategy and assigns an advisor" — 3/4 runs falharam com page.goto: net::ERR_ABORTED; maybe frame was detached? navegando para /campanha/municipios/<slug>/editar (linha 107). O mecanismo está documentado no próprio setup.e2e.spec.ts (linhas 26-30): "Next dev compiles a route on its first hit, and that compile can trigger a full-page reload for any client currently connected — which aborts an in-flight fetch mid test". O setup prewarms o detail (/campanha/municipios/e2e-prewarm) mas não a rota /editar — que é a única rota de edição que specs navegam (verificado por grep) e compila fria no meio do teste.
2. campaignMunicipalities "coordinator sets trend status and justification with auto-save (B24)" — 1/2 runs falhou com page.waitForURL (login do fixture) estourando os 60 s: o login é a primeira jornada pesada do teste e o compile frio do server action de login + as rotas do (app) sob 2 workers não couberam no budget. O comentário do playwright.config.ts já registra a classe (P3-C mediu login estourando o budget antigo); o budget de 60 s cobre a maioria, mas não todas.

Ambos são infra de teste/dev-mode, não defeito de produto: o fluxo real do usuário (clicar em Editar; fazer login) funciona — é a navegação do browser racionando contra o rebuild do dev server. A CI usa o build de produção (pnpm start) e não tem esse mecanismo.

Persona e fluxo

• Persona / contexto: agente ou humano rodando pnpm test:e2e em dev (padrão local, inclusive worktrees).
• Job principal: rodar a suíte local e ler o resultado como espelho da CI.
• Fluxo desejado: pnpm test:e2e em dev → verde estável para o que é verde em prod/CI; vermelho só por regressão real.
• Anti-goals de produto: não tocar asserções de produto (nenhuma asserção desses testes está errada); não mudar o comportamento do app para satisfazer o dev server.

Objetivo e aceite

• campaignMunicipalities (arquivo inteiro) roda verde ×3 consecutivos em dev a 2 workers — incluindo :78 e :518 — nesta sessão de verificação.
• O setup do e2e prewarms as rotas que specs navegam de fato (incl. /campanha/municipios/e2e-prewarm/editar e qualquer outra rota de edição usada por specs — verificar por grep, não por palpite), seguindo o mecanismo já documentado no setup.
• O login do fixture fica resiliente a compile frio (ex.: retry-único da espera de navegação, ou budget maior só no login) sem enfraquecer asserção de produto — login é setup, não contrato.
• P4-L verificado e fechado no ledger: campaignLeaderships (chips) era "falha determinística em dev na árvore limpa" (row 59 do TECH-DEBT); o spec foi reescrito pelo B34 desde então e passou 2/2 nesta sessão — re-rodar ×3 em dev + 1× com E2E_PROD=1 e atualizar o ledger com a evidência.

Dados (intenção)

• Vou apresentar dados? Não — confiabilidade do gate local; o "dado" é estabilidade de execução.
• Decisões desbloqueadas: "e2e local verde = entrega pronta para CI" sem re-tentativas de máquina.

Direção no codebase (hipótese)

• Áreas prováveis: tests/e2e/setup.e2e.spec.ts (lista de prewarm — GET e POST), tests/e2e/fixtures/campaignE2EFixtures.ts (campaign.login, linha ~546-555), docs/TECH-DEBT.md (row 59 — fechar P4-L com evidência).
• Precedente a olhar: o guard e2eNavigationConventions (miss #54) que bane goto→goto sem settle; o comentário do próprio setup sobre o mecanismo de full-reload; P4-L documentado em docs/plans/entrega-engenharia-p4.md (onda 4, "Debug com evidência").
• Risco de acoplamento: o prewarm não pode virar "aguardar resposta 200 de rota autenticada" (o setup roda sem sessão — as GETs de prewarm usam e2e-prewarm justamente por isso); o retry de login não pode engolir falha real de credencial (o retry só na espera de navegação, não na validação de credenciais).

Dependências

• Nenhuma (a investigação do B188 — chat Sollinha — é da #562, em progresso; se o executor encontrar evidência de que o contexto do chat interfere nessas navegações, registrar como achado da #562, não reabrir o assunto aqui).

Fora de escopo

• Flake de dados de seed (campaignMunicipalities FAB suggest, campaignSavedFilters) → OPS28 (provisionamento) / OPS29 (estado vazio).
• Flakes já registrados: #562 (agenda mobile, em progresso), #553, #573.
• Refatorar o spec campaignMunicipalities além do mínimo para a estabilidade.

Rabbit holes de produto

• "Adicionar waitForLoadState('networkidle') antes de todo goto." Esconde o flake por sorte e deixa a suíte mais lenta; o prewarm ataca a causa (rota quente antes do teste). Corte neste item: prewarm das rotas reais + retry-único só no login.
• "Aproveitar e trocar o dev server por build de produção no padrão local." Isso é decisão de fluxo de dev (já existe E2E_PROD=1 como modo honesto documentado); muda o trade-off de velocidade para todo mundo. Corte: deixar o padrão pnpm dev intacto.

Questões em aberto (produto)

• O retry de login deve ser no fixture (para todos os specs) ou um helper opcional? Opções: A) retry-único dentro do campaign.login (todos os specs herdam) | B) helper que os specs chamam quando sabem que estão em dev. Recomendação: A — login é infra em todos os specs; um helper opcional volta a depender de cada spec lembrar. (assumido — validar com quem mantém os fixtures)
• P4-L: fechar o ledger ou manter aberto com "verificado"? Opções: A) fechar com evidência (×3 dev + 1 prod) | B) manter aberto como dívida de verificação contínua. Recomendação: A — dívida fechada com evidência é o padrão do ledger; reabrir se um agente reproduzir com a spec nova.

Referências

• Evidência da sessão: :78 falhou 3× e passou 1× (sempre ERR_ABORTED no goto de /editar); :518 falhou 1× (waitForURL do login, 60 s); campaignLeaderships 2/2 verde (spec reescrita pós-B34).
• tests/e2e/setup.e2e.spec.ts (mecanismo do full-reload + lista de prewarm atual), playwright.config.ts (comentários de budget P3-C).
• docs/TECH-DEBT.md row 59 (P4-L) e docs/plans/entrega-engenharia-p4.md (onda 4).