Estratégia de Testes — Cypress Core

Mapa dos formatos de teste usados na prática de QA (smoke, regressão, contrato...) contra o que já existe neste projeto e qual ferramenta cada um usa. Diferente de regras-de-negocio.md (o produto) e historico-de-falhas.md (incidentes) — este arquivo documenta a cobertura de teste em si: o que já roda, o que está pela metade e o que ainda não existe. Atualizar sempre que um formato novo entrar (ex.: virou de "não implementado" pra "em andamento") ou sair do ar.

Índice

• Formatos de teste
• Teste de sanity (implementado)
• Teste de contrato (em andamento)
• Inventário de testes por módulo
• Inventário de testes por tipo
• Backlog de segurança (priorizado)
• Convenção: toda API nova exige teste de autenticação

Formatos de teste

Teste de sanity (implementado)

Diferença pra smoke: smoke é largo e raso (todas as telas, só confere que montaram); sanity é estreito e um pouco mais fundo (1 módulo, 1 ação rápida real — ex.: aplicar 1 filtro, buscar 1 registro). Existe pra cobrir o meio-termo entre "a tela abriu" e "rodar a suíte de regressão/funcional inteira daquele módulo", que seria overkill logo depois de um deploy pontual numa área só.

Estrutura: cypress/e2e/sanity/, 1 spec por módulo — loginSanity.cy.js, contaCorrenteSanity.cy.js, boletoSanity.cy.js, relatorioSanity.cy.js, aplicacaoSanity.cy.js, contaGeradoraSanity.cy.js. Roda tudo com npm run cy:run:sanity, ou só o(s) módulo(s) afetado(s) via --spec (ver README). Nenhum cria dado real.

Ação rápida de cada módulo (reaproveitando Page Objects e valores já validados por outros specs, não inventados na hora):

O Guid usado em boletoSanity.cy.js (6c62f012-49de-47e5-a2c6-90b2b366356f, vindo de postman/core-homol2.postman_environment.json → guid_boleto) foi confirmado em 25/08/2026 tanto via API (collection de contrato) quanto na própria tela — busca real, 1 resultado, status GERADO, Aplicação V1, cliente João da Silva.

Teste de contrato (em andamento)

O que já está pronto: uma collection Postman dedicada, só leitura (nenhum request de efeito colateral) — postman/CORE_HOMOL_V1_contrato.postman_collection.json. 17 requisições GET cobrindo autenticação, conta digital, boletos, termo de aceite e movimentações, rodando via npm run postman:contract (Newman). Cada request confere:

• Status code 200
• Corpo da resposta é JSON válido
• Tempo de resposta abaixo de 3s
• Schema do corpo (nomes de campo + tipo — string/number/boolean/object/array/null), via pm.response.to.have.jsonSchema(schema), em 15 das 17 requests — as 2 restantes não têm nenhuma resposta real (nem sucesso nem erro) pra basear schema em cima (ver pendências).

O ambiente (postman/core-homol2.postman_environment.json) já vem com GUIDs reais e fixos de homologação pré-preenchidos (guid_condominio, guid_administradora, guid_boleto) — o token (token_v1) é obtido sozinho pela primeira request da collection ("Autentica Aplicação").

Schema de sucesso (7 requests, resposta 200 real): "Autentica Aplicação", "Buscar config boleto", "termo-aceite", "Consulta CEP", "Consulta Termo Vigente", "Consulta boleto", "Buscar Status da Remessa".

Schema de erro — permissão (8 requests, sem acesso ao recurso hoje — ver pendência de permissão abaixo, mas o formato do erro em si é real e validado): "Buscar Informações da Conta Digital", "Exibir plano da Conta Digital", "Configurações da Conta Digital", "Buscar Subconta", "Consultar aplicações", "Consulta Usuários", "Buscar Termo Aceito", "Consulta Histórico Boleto". Confirmamos que a API usa dois envelopes de erro consistentes: {code, domain, description} nos 404 e {title, status, detail} nos 403 — o teste de schema garante que esse formato não muda mesmo que o conteúdo do erro surpreenda depois.

Nota de confiabilidade do schema, já confirmada na prática: cada um foi gerado a partir de uma única resposta real capturada (não inventado) — então um campo que veio null nessa amostra vira type: "null" no schema, mesmo que na prática ele possa às vezes vir string/number também. Isso realmente aconteceu: ao trocar guid_condominio por um outro condomínio real, o schema de "Consulta boleto" passou a falhar porque cliente.email, fornecedor.telefone e outros campos vieram null nesses boletos (tinham vindo string na amostra original). Corrigido ampliando o tipo desses campos pra ["string", "null"] — mais uma amostra real incorporada, não um chute. Se esse padrão se repetir, é sinal de ampliar o tipo, não de remover o teste.

Pendências conhecidas:

Nota de escopo mais ampla: avaliamos gerar um spec OpenAPI formal (schema centralizado, sincronizado automaticamente com a collection via MCP do Postman) e descartamos — sem ganho claro pro tamanho atual do projeto. O JSON Schema por request acima é a versão simples desse mesmo objetivo (validar campo/tipo), sem precisar de um spec separado nem de sincronização via MCP. Se o projeto crescer a ponto de precisar de schema centralizado/versionado, reavaliar a ideia do spec formal do zero.

Inventário de testes por módulo

Todo it() que existe hoje, agrupado por módulo/função do sistema (não por pasta) — pra ver de uma vez o que já está coberto e o que falta. Categoria = pasta onde mora (ver Smoke, sanity, regressão e testes pontuais no README).

Login

Aplicações

Contas Correntes

Contas Geradoras

Boletos

Subconta

Relatórios

Segurança (cruza módulos)

Backlog de segurança (priorizado)

Consolidado em 28/08/2026 — antes vivia espalhado em comentários soltos por vários arquivos. 2 de 2 endpoints de Entidade testados pra cross-tenant já confirmaram falta de checagem de posse — por isso os outros endpoints de Entidade (mesma família, mesmo padrão de teste) entram como alta prioridade, não como "seria bom ter".

⚠️ Gravidade real das 4 linhas "cross-tenant" abaixo (Gerar Boleto, Cancelar Boleto, Buscar Boletos, Cria Condomínio) depende de uma pergunta ainda sem resposta (esclarecido 02/09/2026): o Core é ferramenta interna da Partner — a tela de backoffice mostrar qualquer Administradora/Condomínio é o design, não bug. O token AuthCG de Entidade (o que essas 4 linhas usam) é outra coisa — não confirmado se ele chega a ser usado por algum ERP externo do cliente final, ou se é estritamente interno à Partner. Achado técnico (API não confere posse) continua confirmado do mesmo jeito nos 2 casos — só muda se é exposição real entre clientes ou falta de camada de proteção sem exploração ativa hoje. Perguntar isso pro time do Core junto do reporte.

Fonte: docs/regras-de-negocio.md#autenticação-e-permissões, conversa de 28/08/2026 sobre próximos passos pós-confirmação dos 2 achados.

Convenção: toda API nova exige teste de autenticação

Regra, a partir de 01/09/2026 (decisão explícita do usuário): toda vez que este projeto passa a usar de verdade um endpoint novo (Postman confirma o contrato, um Cypress spec chama ele pela 1ª vez), esse endpoint precisa ganhar 2 it()s em autenticacaoObrigatoria.cy.js — mesmo padrão dos já existentes: chamar sem o header de auth, e chamar com um valor inválido; esperar que nenhum dos dois "funcione" (expectNaoFuncionaSemAutenticacao — status fora de [200, 201, 202, 204]).

Por que essa regra existe: o job atualizarFlagEmissao (ver entrada de 01/09/2026 em docs/historico-de-falhas.md) ficou semanas sem esse teste — só foi descoberto que ele não exigia mais autenticação (possível regressão da migração Java 25/Spring Boot 3.5.7) porque o usuário pediu explicitamente pra confirmar isso numa demanda específica. Sem o teste automatizado rodando desde o começo, uma regressão de segurança dessas passa despercebida indefinidamente — o mesmo risco existe agora pras ~30 rotas novas de ADM/ContaDigital/ADM/ContaDigitalApi descobertas em 31/08/2026 (Postman) e ainda sem nenhum teste de autenticação escrito.

Onde essa regra bate no escopo já documentado do spec: o próprio autenticacaoObrigatoria.cy.js hoje só cobre a API de Entidade (/api/v1/*) — as rotas de /adm/* (backoffice) ficaram de fora por decisão de 26/08/2026 ("mecanismo de autenticação diferente, merece investigação própria"). Essa exclusão não é permanente — é só "ainda não investigado". A regra desta seção vale pra qualquer rota nova, /api/v1/*, /adm/* ou /job/* — a decisão de 26/08 só adiou a tarefa pras rotas de backoffice que já existiam na época, não isenta rotas novas.

Mapeamento completo (feito em 01/09/2026, baseado em uso real — grep em todo cypress/ pelas chamadas config.baseUrl/config.adminBaseUrl, não em achismo):

Por que a linha 🔴 importa mais que as 🟡: é a única que já está em uso real, ativo, em vários specs — exatamente o padrão que o job (atualizarFlagEmissao) mostrou ser arriscado deixar sem teste. As 🟡 ainda nem têm confirmação de que fazem parte do fluxo real de algum teste, então o risco de "regressão silenciosa" é menor (ninguém depende delas ainda).

Ainda não implementado — precisa de decisão antes: testar a linha 🔴 exige logar via cy.login() (2FA) pra conseguir um tokenSessao válido antes de testar sem/com ele inválido — mais pesado que os testes atuais (só precisam de /auth com credenciais de Aplicação, sem 2FA). As linhas 🟡 dependem de confirmar o payload mínimo válido de cada endpoint contra a API real antes de escrever qualquer teste (mesma regra de sempre: nunca no chute).

Smoke — só "a tela carrega" (sem módulo de negócio próprio)

Unidade Organizacional, Usuários (Listar/Perfil), Contas Digitais Boleto, Termos Aceite, Conta Condominial (Geral/Dashboard/Despesas/Webhook), Integrador, Notificações > Cadastros, DDA > Empresas, DDA > Consumo — 13 telas cobertas só por smoke.cy.js, sem spec pontual/regressão próprio ainda.

Inventário de testes por tipo

Mesmo conjunto de testes do inventário acima, agora agrupado por categoria/pasta em vez de módulo — 1 linha por spec, não por it() (contagem exata em cada linha).

Smoke (smoke/) — 26 testes

A tela carrega, sem quebrar? Raso, roda rápido, não valida regra de negócio nenhuma.

Sanity (sanity/) — 6 testes

A área que acabou de sofrer deploy pontual ainda funciona? 1 ação rápida real por módulo, meio-termo entre smoke e regressão/pontual.

Casos de teste (casos_de_teste/) — 14 testes

Um bug específico, já confirmado antes, voltou? 1:1 com uma entrada de historico-de-falhas.md. (Nomenclatura trocada em 09/09/2026 — este era o conteúdo de regressao/ antes disso.)

Segurança (seguranca/) — 12 testes

Varredura sistemática de autorização/autenticação, cruzando módulos — não é por tela, é por preocupação de segurança.

Regressão — cria dado real (regressao/<módulo>/) — 27 testes

Regra de negócio de ponta a ponta, fundo — cria Administradora/Condomínio/Boleto de verdade em homologação a cada execução (ver SPECS_COM_DADOS_REAIS em scripts/specs-utils.js — nomenclatura trocada em 09/09/2026, era casos_de_teste/com_dados/ antes disso).

Regressão — sem dado real (regressao/<módulo>/) — 19 testes

Mesma profundidade da linha acima, mas seguro de rodar a qualquer momento — sem efeito colateral real (nomenclatura trocada em 09/09/2026, era casos_de_teste/sem_dados/ antes disso).