Armadilhas conhecidas de ambiente¶

Registro do que não se descobre rodando de novo — causa de teste intermitente, dívida conhecida, armadilha de ambiente. Contagens (quantos testes, cobertura, apontamentos de lint) não vivem aqui porque envelhecem em silêncio — pergunte-as ao comando (ver CLAUDE.md da raiz, seção "Estado do ferramental", que é a fonte viva desta página).

Dois testes intermitentes na API, mesma causa¶

test_partner_agency_search.py::test_busca_alcanca_quem_esta_fora_da_primeira_pagina e test_partner_agency_status_filter.py::test_alcanca_quem_esta_fora_da_primeira_pagina criam vários registros no mesmo segundo e supõem que o último não caia na primeira página — mas em SQLite created_at empata no segundo e o desempate é id desc sobre UUID aleatório, então a posição é sorteada. Falham em ~1 a 2 de 3 execuções, isoladas ou em conjunto — rode um teste suspeito isolado umas cinco vezes antes de concluir qualquer coisa sobre ele; uma execução só não decide nada.

Suíte da API não roda no host desta máquina¶

Não há uv nem apps/api/.venv aqui — make test falha com uv: No such file or directory. A suíte roda pelo container do dev-remote: docker exec garantora-devremote-api-1 uv run pytest. A imagem embute o código — testar por ela mede o que a imagem tem, não a árvore de trabalho. Durante iteração, docker cp do arquivo alterado antes do pytest resolve (procedimento completo em apps/api/CLAUDE.md); ao fechar, /devremote-rebuild. Vale também para o e2e.

Consulta ao bureau ou job agendado que não aconteceu¶

A consulta ao bureau de crédito (run_credit_check_job) e os jobs agendados — o das 6h (purga de payload bruto vencido, sincronização de extrato e preços das consultas) e o das 7h (cobranças vencidas) — rodam no worker arq, um processo à parte da API, com o Redis por fila (spec 0050). Subir só a API não dá erro nenhum: esses processos simplesmente não acontecem. No local, make worker-dev (e make local-up para o Redis); no dev-remote e na produção, confira o serviço worker com make ps em infra/dev-remote ou infra/prd.

`make lint` não passa hoje¶

A maior parte é line-too-long do ruff — o código nunca passou por ruff format. Não rode ruff format na árvore inteira por conta própria; o diff é enorme e a hora de pagar essa dívida é decisão do usuário. O tsc do web está limpo.

`mypy` sem plugins configurados¶

Sem [tool.mypy] com os plugins de pydantic/SQLAlchemy, a maioria dos erros reportados é falso positivo (forward-refs Mapped["User"], defaults Field(None, ...) lidos como obrigatórios).

Cobertura nunca remedida desde a criação do monorepo¶

Os módulos de maior risco financeiro estavam entre os menos cobertos (credit.py, decision_service.py, guarantee_service.py — que sucedeu o contract_service.py na spec 0027 — e billing_service.py, todos abaixo de um terço, contra a cobertura total). Trate como ordem de grandeza — rode make test-cov antes de afirmar qualquer coisa sobre cobertura.

e2e — pegadinhas de ambiente (`apps/e2e/CLAUDE.md`)¶

Login é lento na suíte — não reduza timeout sem entender por quê.
URL precisa ser absoluta com /app — não use page.goto relativo confiando no baseURL sozinho.
Navegue pela interface, não por goto direto — pula estado que a jornada real monta.
Código de verificação (OTP) sai pelo Mailpit, não por variável de ambiente.
Local roda com --workers=1; alguns testes são seriais por desenho.
goBack() do Playwright tem comportamento específico neste app — ver o arquivo fonte antes de usar.

Sem CI¶

Não há pipeline de CI configurado neste repositório — toda verificação (make preflight, make test, make lint, make e2e) roda localmente ou pelo dev-remote, por decisão explícita de quem chama. O make e2e inteiro, em particular, nunca roda por iniciativa própria — só os specs das telas que a branch alterou, depois de /devremote-rebuild (ver Política de testes no CLAUDE.md da raiz).