# Cebi Tester

Uma ferramenta que executa testes de regressão manual automatizada, por módulo e casos de negócio cadastrado na plataforma.

# O que é, o que faz e o que entrega

## 1. O que é

O CEBI Tester é a ferramenta de **validação funcional de liberação de versão** dos sistemas.

Ele executa, sem intervenção, os casos de teste já catalogados contra o ambiente de um cliente,
recolhe evidência de cada passo e emite um **veredito sobre a versão**: apta, apta com ressalvas
ou não recomendada.

A pergunta que ele responde não é *"a tela abriu?"*, e sim:

> O processo de negócio continuou funcionando do início ao fim, e os dados que ficaram gravados
> estão consistentes?

É a diferença entre a tela dizer que gravou e **ter gravado**. Quando o caso permite, a ferramenta
confere no banco o que a tela afirmou.

---

## 2. O problema que ele resolve

A validação de uma versão era feita a partir de checklists em texto, lidos e executados à mão a
cada liberação. Isso tem três custos:

| Custo | O que acontecia |
| --- | --- |
| **Tempo** | Cada liberação recomeçava do zero, tela a tela |
| **Cobertura** | O que não dava tempo de conferir simplesmente não era conferido — e ninguém sabia o que ficou de fora |
| **Rastro** | "Testei e passou" não é evidência; sem print e sem dado, a conversa com o desenvolvimento vira opinião contra opinião |

O CEBI Tester transforma cada item de checklist em **caso permanente**: escrito uma vez, executado
quantas vezes for preciso, sempre do mesmo jeito, sempre deixando prova.

---

## 3. O que ele faz, numa execução

Cada rodada percorre esta sequência, sozinha:

1. **Identifica o ambiente** do cliente escolhido e valida que ele responde.
2. **Detecta a versão publicada** lendo o próprio sistema — a versão nunca é digitada, porque muda
   várias vezes ao dia e sobe por módulo.
3. **Prepara a base**, quando o cliente exige preparação (perfil de permissão, massa, parâmetros).
4. **Seleciona os casos** no catálogo, conforme o escopo pedido.
5. **Executa** pela interface e pela API, como um usuário faria.
6. **Captura evidência** de cada passo: prints, dados da tela, requisições e respostas, console e
   rede.
7. **Confere na base** o que a tela afirmou, nos casos em que isso é possível.
8. **Classifica a causa** de cada falha — produto, ambiente, base ou a própria ferramenta.
9. **Grava o resultado** e **gera o relatório** da versão.

O passo 8 é o que diferencia a ferramenta de um robô de clique: falha não vira defeito
automaticamente. Falta de massa, ambiente fora do ar e permissão ausente saem como **bloqueio**,
com o motivo medido — não como acusação ao produto.

---

## 4. O que ele entrega

### Veredito da versão
Apta, apta com ressalvas ou não recomendada, com o que **impede liberar** explicitado: reprovados
de severidade Crítica/Alta, casos sem causa identificada e módulos sem nenhuma medição.

### Cobertura
Quanto do catálogo foi efetivamente exercido naquela rodada. Cobertura baixa não é defeito do
produto — é aviso de que a versão foi pouco medida, e isso fica registrado em vez de passar
despercebido.

### Defeitos com evidência
Cada defeito sai com severidade, passo a passo para reproduzir, prints, dados e o contexto
(versão, ambiente, caso). Dá para copiar e abrir o chamado sem reescrever nada.

### Bloqueios por responsável
O que não pôde ser medido, agrupado por **de quem depende destravar**: ambiente, base ou a própria
ferramenta. Isso vira lista de trabalho, não discussão.

### Relatório da versão
Documento completo, com quatro escopos de impressão — do resumo executivo ao dossiê com
evidências.

### Histórico
Defeito que reincide é marcado como tal, inclusive com a contagem de versões seguidas. Registra
também defeito **retirado**, para que uma retratação não suma sem rastro.

### Catálogo permanente
A biblioteca de casos é o ativo que fica: hoje são **388 casos**, **338 automatizados**, em
**15 ambientes de cliente** configurados.

| Produto | Casos | Automatizados |
| --- | --- | --- |
| Balcão Comercial | 275 | 275 |
| Baixa | 63 | 63 |
| Hidrometria | 49 | — |
| Usuários | — | — |

---

## 5. Como a IA entra (e onde ela não entra)

| | Claude (IA) | CEBI Tester (programa) |
| --- | --- | --- |
| **Quando** | Ao chegar uma versão nova; ao analisar falha sem causa determinada | Em toda execução |
| **Faz** | Interpreta as demandas, faz análise de impacto, seleciona a regressão, escreve os casos que faltam, redige o resumo executivo | Prepara a base, autentica, executa, compara, confere no banco, classifica a causa, gera relatório e evidências |
| **Custa token** | Sim | **Não** |

Depois que um caso é escrito e aprovado, ele roda quantas vezes for preciso **sem IA**. O trabalho
caro acontece uma vez; a execução é barata e repetível.

---

## 6. O que ele não faz

- **Não decide sozinho liberar.** Ele mede e sustenta a decisão com evidência; a decisão é do time.
- **Não testa desempenho nem carga.** O escopo é funcional.
- **Não envia nada para cliente.** E-mail e SMS só saem para destinos autorizados do time — nas
  bases de homologação o contato cadastrado costuma ser de pessoa real.
- **Não inventa resultado.** Quando não dá para medir, o caso sai bloqueado, com a causa. Caso
  bloqueado nunca é contado como aprovado.
- **Não cobre o que não está no catálogo.** O que não tem caso escrito aparece como módulo sem
  medição — a lacuna é exibida, não escondida.

---

## 7. Resultados até aqui

- A ferramenta encontrou defeitos que a conferência manual não pegava — entre eles, um modal de
  pagamento que mostrava só parte do valor devido, uma operação de desagrupamento que falha na
  primeira chamada e deixa o agrupamento pela metade, e uma segunda via de parcela que não é
  emitida em nenhum ambiente.
- E derrubou acusações falsas ao produto: casos que pareciam defeito e eram limitação da própria
  automação — grid paginado lido pela metade, aviso que some da tela em quatro segundos, botão
  julgado antes de preencher os campos obrigatórios. Cada um desses virou regra permanente da
  ferramenta.

A segunda parte vale tanto quanto a primeira: uma ferramenta que acusa o que não existe perde a
confiança do desenvolvimento na primeira reunião.

# Manual de instalação

# Manual de instalação

Como deixar o CEBI Tester rodando numa máquina nova. Os comandos são copiáveis; execute um de
cada vez, na ordem.

Para usar a ferramenta depois de instalada, veja o [Manual do usuário](MANUAL-USUARIO.md).

---

## 1. O que a máquina precisa ter

| Item | Versão | Para quê |
| --- | --- | --- |
| **Windows** | 10 ou 11 | É onde a ferramenta roda hoje |
| **Node.js** | 20 ou superior (testado no 24.15) | Executa a ferramenta |
| **Git** | qualquer recente | Baixa e atualiza o código |
| **Espaço em disco** | ~2 GB | Dependências, navegador de teste e evidências |

Além disso, a máquina precisa **alcançar pela rede**:

- os endereços dos ambientes dos clientes (o Balcão, a Baixa, a Hidrometria e o módulo Usuários);
- os bancos Oracle desses clientes, se for usar a conferência no banco (veja o passo 6).

Para conferir o que já está instalado:

```bash
node -v
```

```bash
git --version
```

Se o Node não estiver instalado, baixe a versão LTS em https://nodejs.org e repita o comando.

---

## 2. Baixar o CEBI Tester

Escolha uma pasta de trabalho e clone o repositório:

```bash
git clone https://bitbucket.org/cebi/cebi.qualityassurance.git
```

Entre na pasta criada:

```bash
cd cebi.qualityassurance
```

Todos os comandos seguintes são executados **dentro dessa pasta**.

---

## 3. Instalar as dependências

```bash
npm install
```

Demora alguns minutos na primeira vez. Ao final, aparece a quantidade de pacotes instalados.

---

## 4. Instalar o navegador de teste

A automação usa um navegador próprio, separado do Chrome do dia a dia:

```bash
npx playwright install chromium
```

---

## 5. Criar o arquivo de credenciais

As senhas ficam num arquivo chamado `.env`, que **nunca** é enviado ao repositório. Comece pelo
modelo que acompanha o projeto:

```bash
cp .env.example .env
```

Abra o `.env` num editor de texto e preencha os blocos dos clientes que você vai usar. Cada
cliente tem três linhas principais:

```
POCOS_BASE_URL=http://devlocal.cebi.com.br:40054
POCOS_USUARIO=
POCOS_SENHA=
```

Duas observações:

- **Não precisa preencher tudo.** Quem usa a interface web digita usuário e senha a cada execução;
  o `.env` serve para rodar pela linha de comando sem digitar toda vez.
- **O `.env` é só desta máquina.** Ao atualizar a ferramenta, ele não é tocado.

---

## 6. (Opcional) Ligar a conferência no banco

Parte dos casos confere na base o que a tela mostrou — é o que diferencia "a tela disse que
gravou" de "gravou mesmo". Para isso a ferramenta usa o **Dicionário de Dados**, que é um produto
à parte, com repositório próprio.

Sem ele, a ferramenta roda e aprova a maioria dos casos; os que dependem de conferência no banco
ficam **bloqueados**, com o motivo escrito no resultado.

Para ligar:

1. Instale o Dicionário de Dados na mesma máquina.
2. Cadastre nele a conexão de cada banco que será usado — **o cadastro é feito por quem tem a
   senha**, no aplicativo do Dicionário, e fica protegido pelo usuário do Windows que o cadastrou.
   Por isso o cadastro precisa ser refeito em cada máquina nova.
3. No arquivo de cada ambiente, em `config/ambientes/<cliente>-master.json`, confirme que o nome
   em `basePreparation.opcoes.banco` é exatamente o nome cadastrado no Dicionário.

---

## 7. Subir a interface

```bash
npm run servidor -- --http --porta 4480 --host 127.0.0.1
```

A tela mostra o endereço, os ambientes carregados e dois avisos — que não há autenticação e que,
em HTTP, a senha trafega em texto claro. Abra no navegador:

```bash
start http://localhost:4480
```

Para que outras pessoas da rede interna acessem, troque o host:

```bash
npm run servidor -- --http --porta 4480 --host 0.0.0.0
```

> **Mantenha dentro da rede interna.** A interface não tem login e dispara escrita em base de
> cliente — foi uma decisão de projeto, não um esquecimento.

Enquanto esse comando estiver aberto, o servidor está no ar. Fechá-lo derruba a interface.

---

## 8. Conferir se ficou tudo certo

Liste os ambientes que a instalação enxerga:

```bash
npm run clientes
```

E peça a versão publicada de um deles, sem executar nada:

```bash
npm run validar-versao -- --ambiente guaratingueta-qa --sistema balcao --somente-versao
```

Se vier a versão do ambiente, a instalação está completa: a ferramenta alcançou o cliente,
autenticou e leu a versão.

---

## 9. Acrescentar um ambiente novo

Cada cliente é um arquivo em `config/ambientes/`. O caminho mais seguro é copiar um que já
funciona e trocar o endereço, o nome e o banco:

```bash
cp config/ambientes/guaratingueta-qa.json config/ambientes/novocliente-qa.json
```

Depois edite, no arquivo novo: `slug`, `nome`, `cliente`, `baseUrl` e, se for usar conferência no
banco, `basePreparation.opcoes.banco`. Reinicie o servidor para que ele apareça na lista.

---

## 10. Problemas comuns

| Sintoma | Causa provável | Solução |
| --- | --- | --- |
| `node` ou `git` não é reconhecido | Não instalado, ou terminal aberto antes da instalação | Instale e **abra um terminal novo** |
| `npm install` falha ao baixar | Rede ou proxy da empresa | Falar com a infraestrutura |
| A interface não abre no navegador | O servidor não está no ar | O comando do passo 7 precisa ficar aberto |
| "porta já em uso" | Já existe um servidor rodando | Use outra porta (`--porta 4481`) ou feche o anterior |
| Nenhum ambiente na lista | Nenhum arquivo em `config/ambientes/` | Veja o passo 9 |
| Tudo bloqueado por banco | Dicionário de Dados não instalado ou sem a conexão cadastrada | Passo 6 |

# Manual de atualização

Como atualizar uma instalação que já existe, sem perder configuração nem resultados.

Para instalar do zero, veja o [Manual de instalação](MANUAL-INSTALACAO.md).

> **Duas coisas diferentes se chamam "versão".** Este manual trata de atualizar **a ferramenta**
> (o CEBI Tester). Atualizar **a versão do sistema que será validado** é outra coisa — está no
> fim, na seção 7.

---

## 1. Antes de começar

A atualização leva poucos minutos, mas **não faça com execução em andamento**: abra a aba
*Execuções* e confirme que nada está rodando.

Depois, pare o servidor: volte ao terminal onde ele está no ar e pressione `Ctrl + C`.

---

## 2. Conferir se há algo local a preservar

Dentro da pasta do projeto:

```bash
git status
```

- **"nothing to commit, working tree clean"** → pode seguir para o passo 3.
- Se aparecer uma lista de arquivos, há alterações feitas nesta máquina. Normalmente são
  ambientes novos em `config/ambientes/`. Guarde-as antes de atualizar:

```bash
git stash
```

Depois da atualização, para trazê-las de volta:

```bash
git stash pop
```

O arquivo `.env` **nunca** aparece nessa lista e nunca é alterado pela atualização — ele não é
versionado de propósito.

---

## 3. Baixar a versão nova

```bash
git pull
```

O resumo no final mostra quantos arquivos mudaram. Se aparecer `Already up to date.`, não havia
nada novo e o trabalho acaba aqui.

---

## 4. Atualizar as dependências

Sempre que o `package-lock.json` aparecer entre os arquivos alterados:

```bash
npm install
```

E, se a versão do Playwright tiver mudado:

```bash
npx playwright install chromium
```

Na dúvida, rodar os dois não causa problema: quando não há nada a fazer, eles terminam em
segundos.

---

## 5. Subir o servidor de novo

```bash
npm run servidor -- --http --porta 4480 --host 127.0.0.1
```

No navegador, recarregue a página com `Ctrl + F5` — isso descarta a versão antiga da interface que
o navegador guardou.

---

## 6. Conferir se a atualização funcionou

Três checagens rápidas, em ordem de custo:

```bash
npm run clientes
```

Todos os ambientes que você usa continuam na lista?

```bash
npm run validar-versao -- --ambiente guaratingueta-qa --sistema balcao --somente-versao
```

A ferramenta ainda alcança o ambiente e lê a versão?

```bash
npm run test:harness
```

Esta é a bateria de testes **da própria ferramenta** — ela não toca em ambiente de cliente. Se
terminar tudo verde, a atualização está sadia.

---

## 7. Atualizar a versão do sistema a ser validado

Isso **não** se faz pela ferramenta: a publicação é feita pela infraestrutura, a pedido do time.

O fluxo é:

1. Vocês pedem a publicação da versão no ambiente.
2. Na aba *Executar*, passo 4, clique em **Detectar no ambiente**.
3. Confirme que a versão detectada é a que você pediu — e só então execute.

A versão muda várias vezes ao dia e sobe por módulo. Em execução longa, vale repetir a detecção ao
final: se a versão mudou no meio, o resultado é de duas versões diferentes e precisa ser refeito.

---

## 8. Voltar para a versão anterior da ferramenta

Se algo passar a falhar depois de atualizar, dá para voltar. Primeiro veja o histórico:

```bash
git log --oneline -10
```

Depois volte para o ponto anterior, usando o código que aparece à esquerda:

```bash
git checkout <codigo-do-commit>
```

Para retornar à versão mais nova depois:

```bash
git checkout master
```

Nenhum desses comandos apaga resultados gravados nem o `.env`.

---

## 9. Problemas comuns

| Sintoma | Causa provável | Solução |
| --- | --- | --- |
| `git pull` reclama de alterações locais | Há arquivos modificados nesta máquina | Passo 2 (`git stash`) |
| A interface parece a antiga | O navegador guardou a página | `Ctrl + F5` |
| Erro de módulo não encontrado ao subir | Dependência nova não instalada | `npm install` |
| Erro do navegador ao executar casos | Playwright desatualizado | `npx playwright install chromium` |
| Ambiente sumiu da lista | A alteração local se perdeu | `git stash pop`, ou recriar o arquivo em `config/ambientes/` |
| Falha só depois da atualização | Regressão da ferramenta | Volte pelo passo 8 e registre o que quebrou |

# 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](MANUAL-USUARIO.md).

---

## 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.

1. **O que o usuário faz?** Caminho até a tela e os passos, na ordem.
2. **O que caracteriza sucesso?** O que precisa aparecer na tela **e** o que precisa ficar gravado.
3. **De que dado ele precisa?** Qual ligação, conta, carnê ou cadastro serve — e o que torna um
   registro elegível.
4. **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:

```json
{
  "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:

```bash
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.

```bash
npx tsx scripts/_catalogo-upsert.ts --id CT-SSB-CON-020 --campos '{"criticidade":"Alta"}'
```

Confira que entrou:

```bash
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:

```json
{
  "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:

1. **Usar o page object do módulo** (`src/pages/ssb/<modulo>.page.ts`), não seletores soltos.
2. **Pedir a massa pelo nome do pedido**, nunca fixar um CDC no código.
3. **Conferir o resultado na base**, e não só na tela.
4. **Reverter** o que alterou a operação.
5. **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

```bash
npm run validar-versao -- --ambiente guaratingueta-qa --sistema balcao --test CT-SSB-CON-020
```

E só então marque como automatizado:

```bash
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:

1. **Levantar as telas** do módulo no menu, em um cliente que o utilize.
2. **Escolher o prefixo de ID** (três letras livres) e reservar a faixa numérica.
3. **Descrever os casos** (seção 2) e **catalogá-los** sem automação (seção 4) — isso já dá
   cobertura visível e roteiro manual.
4. **Declarar os pedidos de massa** do módulo (seção 5). Massa de outro módulo quase nunca serve.
5. **Criar o page object** em `src/pages/ssb/<modulo>.page.ts`, com os caminhos e as leituras da
   tela.
6. **Automatizar caso a caso**, do mais crítico para o menos.
7. **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:

1. **Descobrir a rota** em que ele é publicado (`/balcao_ssb`, `/baixa`, `/ssb_hidrometria`…) e
   confirmar que responde `Api/AppInfo`.
2. **Acrescentar o bloco em cada ambiente** que o publica, em `config/ambientes/<cliente>.json`,
   dentro de `sistemas`:

```json
"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" }
}
```

3. **Reiniciar o servidor** — o sistema novo passa a aparecer no passo 1 da aba *Executar*.
4. Seguir, daí em diante, os passos de módulo novo (seção 7).

---

## 9. Regras do projeto, que valem para todo caso novo

1. **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.
2. **Medir antes de julgar.** Nada de concluir pelo que "parece" na tela — nem ausência, nem
   sucesso.
3. **Caso bloqueado diz de quem depende destravar:** ambiente, base ou ferramenta.
4. **Reverter o que altera a operação.** Cadastro de teste inativo pode ficar; conta paga, lote e
   agrupamento, não.
5. **Envio para fora permanece bloqueado**, mesmo em base de homologação.
6. **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.

# Manual do usuário

Este manual é para quem **usa** o CEBI Tester para validar uma versão. Não é preciso saber programar nem abrir terminal: tudo acontece numa página do navegador.

Para instalar pela primeira vez, veja a página **Manual de instalação**. Para atualizar uma instalação existente, **Manual de atualização**.

## 1. O que o CEBI Tester faz

Ele executa, sozinho, os casos de teste já catalogados contra um ambiente de cliente, recolhe evidência de cada passo e diz, ao final, **se a versão está apta a ser liberada**.

A pergunta que ele responde não é "a tela abriu?", e sim: *o processo de negócio funcionou do início ao fim, e o que ficou gravado está correto?*

Quem decide o veredito é a medição — não há opinião no meio.

## 2. Entrar

Abra o endereço do CEBI Tester no navegador

Na primeira vez ele pergunta de qual time você faz parte:

![Tela de entrada, com os times SSB, SFI, STM e Folha](https://wiki.cebi.com.br/uploads/images/gallery/2026-10/00-entrada.png)

Escolha **SSB**. Os demais times ainda não têm casos catalogados e aparecem como "em breve".

A escolha fica guardada **neste navegador**: nas próximas vezes a página abre direto em *Executar*. Para trocar, use o botão **trocar**, ao lado de "Time SSB", no alto da tela.

## 3. As cinco abas

| Aba | Para quê |
| --- | --- |
| **Executar** | Disparar uma validação |
| **Execuções** | Acompanhar a que está rodando e ver as rodadas anteriores |
| **Resultados** | Ler o veredito de uma versão, com defeitos e evidências |
| **Histórico** | Comparar versões ao longo do tempo |
| **Catálogo de testes** | Consultar os casos que existem |

No canto superior direito aparecem, sempre, quantos ambientes estão configurados, quantos casos existem no catálogo e quantos já são automatizados.

## 4. Executar uma validação

![Aba Executar, com os cinco passos numerados](https://wiki.cebi.com.br/uploads/images/gallery/2026-10/01-executar.png)

A tela é numerada. Percorra de cima para baixo.

### 1 · O que testar

Escolha o produto: **Balcão Comercial**, **Baixa**, **Hidrometria** ou **Usuários**. Cada cartão mostra quantos casos existem e quantos estão automatizados — produto marcado como *sem automação* ainda não tem caso que rode sozinho.

### 2 · Onde rodar

Lista só os ambientes **configurados**. Oferecer um ambiente que não está configurado seria armadilha: ele falharia por falta de configuração, e não por defeito do produto.

### 3 · Quem entra

Usuário e senha do ambiente. **A senha é digitada a cada execução e nunca é gravada** — ela vive só na memória do servidor enquanto os testes rodam.

### 4 · Qual versão está publicada

Clique em **Detectar no ambiente**. A versão não é digitada: o próprio sistema é consultado com a credencial informada.

Isso é deliberado. A versão muda várias vezes ao dia, e já aconteceu de subir no meio de uma execução — detectar evita atribuir a uma versão um resultado que é de outra.

### 5 · O que rodar

Quatro opções prontas: **Tudo**, **Só o que falhou**, **Só bloqueados** e **Um caso...**.

![Parte de baixo da aba Executar: escopo, repetição automática e as seções recolhidas](https://wiki.cebi.com.br/uploads/images/gallery/2026-10/02-executar-escopo.png)

Vem marcada a opção **"Repetir automaticamente o caso que falhar por instabilidade do ambiente"**. Ela só vale para causa de ambiente — servidor reciclando, navegador que morre. **Defeito do produto nunca é repetido**, para não maquiar o resultado.

As duas seções recolhidas no fim — *Restringir mais* e *Preparação da base* — não são necessárias no dia a dia. A primeira filtra por demanda, módulo, tipo ou tag; a segunda controla o preparo da base antes dos testes.

## 5. Acompanhar a execução

![Aba Execuções, com o log ao vivo e a lista de rodadas anteriores](https://wiki.cebi.com.br/uploads/images/gallery/2026-10/03-execucoes.png)

No alto fica o **log ao vivo** da execução em andamento, com os botões **Avisar quando terminar** (notificação do sistema operacional) e **Cancelar execução**. O título da aba do navegador também mostra o progresso, no formato "(41/63) CEBI Tester" — funciona mesmo sem permissão de notificação.

Abaixo, as **rodadas** já realizadas: versão, quantos Masters, quantos casos, tempo de máquina, veredito e um botão de **Relatório** por rodada.

**Uma execução por Master de cada vez.** Dois testes na mesma base disputariam a mesma massa — o mesmo carnê, a mesma conta. Masters diferentes podem rodar ao mesmo tempo.

## 6. Ler o resultado

![Aba Resultados, com o veredito da versão e a cobertura do catálogo](https://wiki.cebi.com.br/uploads/images/gallery/2026-10/04-resultados.png)

Escolha **Sistema**, **Ambiente** e **Versão**. O ambiente filtra de onde veio a evidência, mas o **veredito é da versão**, não do cliente.

O bloco colorido traz o veredito — *liberada*, *liberada com ressalvas* ou *não recomendada* — e, logo abaixo, **o que impede liberar**: quantos casos reprovaram em severidade Crítica/Alta, quantos ficaram sem causa identificada e quantos módulos não tiveram nada medido.

A **cobertura do catálogo** mostra quanto do que existe foi efetivamente exercido naquela rodada. Cobertura baixa não é defeito do produto — é aviso de que a versão foi pouco medida.

![Blocos do resultado: defeitos, bloqueados, não se aplicam e o botão Relatório](https://wiki.cebi.com.br/uploads/images/gallery/2026-10/04b-resultados-defeitos.png)

Os blocos abrem um a um:

- **Pesa na decisão** — o que efetivamente mudou o veredito.
- **Por módulo** — onde houve medição e onde não houve.
- **De onde veio a evidência** — em quais Masters os casos rodaram.
- **Defeitos** — agrupados por severidade, cada um com as evidências (prints e dados) e o botão de copiar para abrir o chamado.
- **Bloqueados** — agrupados por **de quem depende**: ambiente, base ou harness. Bloqueado não é defeito do produto; é caso que não pôde ser medido.
- **Não se aplicam a este cliente** — com a condição **medida** que os torna inaplicáveis. Não contam contra a cobertura.
- **Preparação do ambiente** — como a base foi preparada antes dos testes.

O botão **Relatório** abre o documento completo da versão, com quatro escopos de impressão, do resumo executivo ao dossiê com evidências.

## 7. Histórico

![Aba Histórico](https://wiki.cebi.com.br/uploads/images/gallery/2026-10/05-historico.png)

Defeitos por versão, funcionalidades que mais reincidem e o que foi retirado. É aqui que se vê se um problema é novo ou se já vem se repetindo há versões — informação que muda a conversa com o desenvolvimento.

## 8. Catálogo de testes

![Aba Catálogo de testes, com os casos do Balcão carregados](https://wiki.cebi.com.br/uploads/images/gallery/2026-10/06-catalogo.png)

A biblioteca permanente: todos os casos, com filtro por módulo, por automatizado ou não, e busca por ID, título ou tag. Escolha primeiro o sistema — carregar os três de uma vez misturaria o que não se compara.

## 9. Cinco regras que evitam erro

1. **A base é de homologação, mas é real.** A execução grava: cria, baixa, estorna. É por isso que a tela avisa antes de disparar.
2. **Envio para fora é bloqueado.** E-mail e SMS só saem para destino autorizado do time — o contato cadastrado na ligação costuma ser de cliente de verdade.
3. **A senha nunca fica gravada.** Digitada a cada execução, mantida só em memória.
4. **A versão é detectada, não digitada.** E vale conferir de novo ao final de uma execução longa.
5. **Bloqueado não é reprovado.** Reprovado é defeito do produto; bloqueado é caso que não pôde ser medido, e o resultado já diz de quem depende destravar.

## 10. Quando algo dá errado

| O que você vê | O que provavelmente é | O que fazer |
| --- | --- | --- |
| Muitos casos **bloqueados por ambiente** | O servidor do cliente está fora ou lento | Conferir o ambiente e repetir depois |
| Bloqueados por **base** | Falta massa, parâmetro ou permissão | Está escrito no próprio bloco qual é a falta |
| Bloqueados por **harness** | A ferramenta não soube medir | Registrar: é correção nossa, não do produto |
| **Causa não identificada** | Não se sabe se é produto ou ferramenta | Não vira defeito sem análise — é o que o relatório sinaliza |
| O botão de executar está **desabilitado** | Já existe execução em andamento | Use o link de acompanhar, na aba Execuções |