Manual para incluir casos de teste e módulos

Como entra um caso novo, um módulo novo e um sistema novo na ferramenta — e, em cada etapa,
quem faz o quê.
Para usar a ferramenta, veja o Manual do usuário.
1. Primeiro: quem precisa de IA e quem não precisa
Um caso passa por três estágios. Só um deles exige quem saiba programar.
Estágio
O que é
Quem faz
1. Caso descrito
O que se vai testar, com qual critério de aceite
Você. Conhecimento de negócio, não de código
2. Caso catalogado
A ficha no catálogo: ID, módulo, criticidade, tags
Você, por um comando — sem IA ou solicite a uma IA
3. Caso automatizado
O arquivo 
.spec.ts que executa e confere
IA ou desenvolvedor. É código
Três consequências práticas:
Cadastrar não precisa de IA. Um caso catalogado e ainda não automatizado já é útil: aparece
no catálogo, entra nas contas de cobertura e sai no relatório como roteiro manual. Mas, pode utilizar uma de desejar.
Automatizar precisa. O 
.spec.ts não é gravação de cliques: ele mede, confere o resultado na
base e trata as armadilhas da tela. Hoje quem escreve é a IA, a partir da sua descrição.
Depois de escrito, roda sem IA para sempre — e sem custo de token. O trabalho caro acontece
uma vez por caso.
O que determina a qualidade do caso automatizado é o estágio 1. Um caso descrito como
"verificar a tela" vira automação que só confere que a tela abriu. O critério de aceite é o que
a IA transforma em medição.
2. Como descrever um caso que dá para automatizar
Quatro perguntas. Se as quatro tiverem resposta, o caso é automatizável.
O que o usuário faz? Caminho até a tela e os passos, na ordem.
O que caracteriza sucesso? O que precisa aparecer na tela e o que precisa ficar gravado.
De que dado ele precisa? Qual ligação, conta, carnê ou cadastro serve — e o que torna um
registro elegível.
Como se desfaz? Se o caso grava algo que muda a operação — conta paga, lote, agrupamento —
ele precisa reverter ao final.
Exemplo de descrição suficiente:
Agrupar duas contas vencidas da mesma ligação. Sucesso: o agrupamento é criado, o valor do
código de barras é igual à soma da coluna Total da revisão, e as duas contas aparecem como
agrupadas na base. Precisa de ligação com duas contas vencidas, não retidas e não negociadas.
Desfazer: desagrupar ao final.
3. Anatomia de um caso no catálogo
O catálogo é o arquivo 
catalogo/testes.json. Cada caso é uma ficha:
{
  "id": "CT-SSB-CON-010",
  "titulo": "Busca pelo painel: consulta por CDC",
  "produto": "SSB",
  "sistema": "balcao",
  "modulo": "Consultas",
  "funcionalidade": "Consultas - Busca pelo painel inicial",
  "demanda": "REGRESSAO",
  "tipo": "regressao",
  "criticidade": "Alta",
  "categoria": "principal",
  "tags": ["busca", "painel", "cdc"],
  "spec": "tests/biblioteca/ssb/consultas/CT-SSB-CON-010-busca-pelo-painel.spec.ts",
  "automatizado": true,
  "escopo": "produto",
  "origem": "checklist-balcao-release / Crítico item 1.1",
  "ativo": true
}
Campos obrigatórios
Campo
O que é
id
Identificador único — veja a convenção abaixo
titulo
O que o caso mede, numa frase
produto
SSB
sistema
balcao, 
baixa, 
hidrometria, 
usuarios
modulo
Módulo dentro do sistema (
Consultas, 
Arrecadacao, …)
funcionalidade
A tela ou fluxo específico
demanda
REGRESSAO ou o número do IC/RM que originou
tipo
regressao ou 
funcional
criticidade
Alta, 
Media ou 
Baixa
categoria
principal ou 
alternativo
tags
Palavras para filtrar depois
spec
Caminho do arquivo de automação (vazio enquanto não houver)
automatizado
true só quando o spec existe e roda
escopo
produto (vale para todos) ou 
cliente
origem
De onde o caso veio — checklist, demanda, reunião
ativo
false aposenta sem apagar o histórico
Campos opcionais que mudam o comportamento
Campo
Quando usar
ambienteObrigatorio + 
motivoAmbienteObrigatorio
O caso só roda num cliente. Ex.: penhora, que só existe em Poços. O motivo é obrigatório junto
ambientePreferido
Roda melhor num cliente, mas aceita outro
aplicavelQuando
Condição medida que torna o caso aplicável. Se não vale, o caso sai como não se aplica, com a condição medida, em vez de reprovar
dependencias
IDs de casos que precisam rodar antes
severidadeSeFalhar
Sobrepõe a criticidade na hora de classificar o defeito
observacao
Tudo que quem for automatizar precisa saber
Convenção de ID
CT-SSB-CON-010
│  │   │   └── número sequencial dentro do módulo
│  │   └────── três letras do módulo (CON=Consultas, ARR=Arrecadação, BXA=Baixa…)
│  └────────── produto
└───────────── caso de teste
Deixe espaço entre blocos (010, 011, 012… e o bloco seguinte em 020) — assim dá para inserir caso
relacionado depois sem renumerar nada.
4. Incluir um caso novo
Não edite 
catalogo/testes.json na mão. O arquivo é grande e, quando vários casos são
escritos ao mesmo tempo, abrir o arquivo inteiro e regravar faz um autor apagar o trabalho do
outro sem erro nenhum. Use o comando, que grava sob trava e mescla só os campos informados:
npx tsx scripts/_catalogo-upsert.ts --id CT-SSB-CON-020 --campos '{"titulo":"Consulta por telefone com DDD e sem DDD","produto":"SSB","sistema":"balcao","modulo":"Consultas","funcionalidade":"Consultas - Por telefone","demanda":"REGRESSAO","tipo":"regressao","criticidade":"Media","categoria":"principal","tags":["busca","telefone"],"spec":"","automatizado":false,"escopo":"produto","origem":"checklist-balcao-release / item 1.9","ativo":true}'
O mesmo comando serve para alterar um caso: informe só o campo que muda.
npx tsx scripts/_catalogo-upsert.ts --id CT-SSB-CON-020 --campos '{"criticidade":"Alta"}'
Confira que entrou:
npm run catalogo -- --modulo Consultas
5. Declarar a massa de que o caso precisa
Se o caso depende de um registro com característica específica, declare isso em
catalogo/massa.json como um pedido — assim a ferramenta encontra o registro sozinha, em
qualquer cliente, em vez de depender de um CDC fixo que some.
Cada pedido tem nome, descrição, o porquê (por que esse recorte importa), as colunas e a
consulta que o encontra:
{
  "nome": "ligacao-com-duas-contas-vencidas",
  "produto": "SSB",
  "descricao": "Ligação com ao menos duas contas vencidas, não retidas e não negociadas.",
  "porque": "Agrupar exige duas contas elegíveis; conta retida muda o resultado e viraria defeito falso.",
  "colunas": ["cdc", "conta1", "conta2"],
  "sql": "select ..."
}
Regra do projeto: falta de massa não bloqueia caso. Antes de desistir, a ferramenta procura o
registro em outro cliente configurado e, quando o cenário permite, cria a massa pela própria
interface.
6. Automatizar o caso
O arquivo de automação vive em:
tests/biblioteca/<produto>/<modulo>/CT-SSB-XXX-000-nome-curto.spec.ts
É o estágio que precisa de IA ou de um desenvolvedor. O que esse arquivo tem de fazer, além de
clicar:
Usar o page object do módulo (
src/pages/ssb/<modulo>.page.ts), não seletores soltos.
Pedir a massa pelo nome do pedido, nunca fixar um CDC no código.
Conferir o resultado na base, e não só na tela.
Reverter o que alterou a operação.
Bloquear com a causa medida quando não der para testar — jamais acusar o produto por falta
de instrumento.
As armadilhas que já viraram regra
Cada uma dessas gerou, um dia, um defeito falso. Hoje são regra escrita no código:
Armadilha
O que acontece
O que o spec tem de fazer
Grid paginado
A tabela mostra 10 por página; ler só a visível "prova" que o registro não existe
Ampliar a página e conferir o indicador de truncado
Aviso efêmero
A faixa de mensagem dura ~4 segundos
Deixar a captura de avisos ligada antes da ação
Campo obrigatório
Botão nasce desabilitado; julgar aí acusa o produto
Preencher os obrigatórios e só então julgar o botão
Cadeia de modais
Até três modais em sequência; não responder um faz parecer que nada aconteceu
Responder a cadeia inteira
Sonda vazia
Inventário vazio parece "a tela não tem isso"
Se a leitura voltou vazia, bloquear dizendo isso
Depois de escrever, rode só o caso novo
npm run validar-versao -- --ambiente guaratingueta-qa --sistema balcao --test CT-SSB-CON-020
E só então marque como automatizado:
npx tsx scripts/_catalogo-upsert.ts --id CT-SSB-CON-020 --campos '{"spec":"tests/biblioteca/ssb/consultas/CT-SSB-CON-020-consulta-por-telefone.spec.ts","automatizado":true}'
7. Incluir um módulo novo
Módulo é um bloco de telas dentro de um sistema que já existe — por exemplo, Leituras dentro da
Hidrometria. A ordem que funciona:
Levantar as telas do módulo no menu, em um cliente que o utilize.
Escolher o prefixo de ID (três letras livres) e reservar a faixa numérica.
Descrever os casos (seção 2) e catalogá-los sem automação (seção 4) — isso já dá
cobertura visível e roteiro manual.
Declarar os pedidos de massa do módulo (seção 5). Massa de outro módulo quase nunca serve.
Criar o page object em 
src/pages/ssb/<modulo>.page.ts, com os caminhos e as leituras da
tela.
Automatizar caso a caso, do mais crítico para o menos.
Conferir em quais clientes o módulo é publicado e configurar esses ambientes — um módulo que
só existe em dois clientes precisa que esses dois estejam configurados, ou "não configurado"
vira "funcionalidade não existe".
8. Incluir um sistema novo
Sistema é um produto inteiro — Balcão, Baixa, Hidrometria, Usuários. Para acrescentar outro:
Descobrir a rota em que ele é publicado (
/balcao_ssb, 
/baixa, 
/ssb_hidrometria…) e
confirmar que responde 
Api/AppInfo.
Acrescentar o bloco em cada ambiente que o publica, em 
config/ambientes/<cliente>.json,
dentro de 
sistemas:
"nomedosistema": {
  "produto": "SSB",
  "nome": "Nome que aparece na interface",
  "rota": "/rota/index.html",
  "login": { "rota": "/rota/index.html", "seletorUsuario": "#username", "seletorSenha": "#password", "seletorEntrar": "button[type='submit']", "seletorPosLogin": "ul.page-sidebar-menu" },
  "api": { "autenticacao": "storage", "base": "/rota", "chaveStorage": "ls.authorizationData", "caminhoToken": "token" }
}
Reiniciar o servidor — o sistema novo passa a aparecer no passo 1 da aba Executar.
Seguir, daí em diante, os passos de módulo novo (seção 7).
9. Regras do projeto, que valem para todo caso novo
Nunca bloquear por massa, parâmetro, ambiente ou permissão sem antes tentar: criar a massa,
procurar o cliente que usa a funcionalidade, trocar de base ou conceder a permissão.
Medir antes de julgar. Nada de concluir pelo que "parece" na tela — nem ausência, nem
sucesso.
Caso bloqueado diz de quem depende destravar: ambiente, base ou ferramenta.
Reverter o que altera a operação. Cadastro de teste inativo pode ficar; conta paga, lote e
agrupamento, não.
Envio para fora permanece bloqueado, mesmo em base de homologação.
Um caso, um arquivo, um ID. Casos irmãos podem dividir o mesmo spec, desde que cada um tenha
seu ID e seu resultado próprio.