Skip to content

Smoke Test Flows

Jump to bottom
technical-documenter edited this page Aug 26, 2026 · 6 revisions

Smoke Test Flows — app-community

Espelho técnico do catálogo canônico de fluxos de negócio usados em smoke tests no ecossistema ControleOnline.

Fonte canônica (agents-mcp): smoke-test-flows.md

Alterações no catálogo só por solicitação humana explícita. Agents não inventam novos fluxos.

Gate obrigatório de evidência visual

QA não pode aprovar smoke test de UI/browser se a evidência não cobrir o fluxo inteiro com prints/screenshot.

Para cada smoke de UI/browser, a evidência mínima é:

  1. fluxo: <id> declarado no teste, manifesto, comentário ou evidência da issue.
  2. Lista de passos do fluxo executado.
  3. Print/screenshot de cada passo relevante, incluindo:
    • estado inicial / tela de entrada;
    • preenchimentos ou seleção de dados críticos;
    • ação principal;
    • feedback visual de sucesso, erro esperado ou estado final;
    • qualquer transição que prove integração entre módulos.
  4. Artefatos persistidos em diretório de resultados do smoke, com manifesto ou resumo indicando o fluxo.
  5. Justificativa explícita quando um passo não puder gerar print por limitação técnica.

Falta de prints por etapa, prints que não permitem reconstruir a jornada ou smoke sem fluxo declarado bloqueiam agent:qa:accepted.

Relação com qualidade de código: code-quality.md — evidência parcial bloqueia QA; manifesto deve permitir reconstruir a jornada.

Flowcharts publicados no admin (vínculo operacional)

O catálogo de fluxos de negócio não substitui os flowcharts do tenant admin. Soma-se a eles.

Antes de dar agent:qa:accepted em smoke de UI dos produtos POS, SHOP, PPC, DELIVERY, CHECKOUT ou MANAGER, o QA deve ler os flowcharts habilitados:

  1. GET https://api.controleonline.com/flowcharts (e /flowcharts/{id} quando precisar do diagrama).
  2. Headers permitidos (token nunca no git): api-token e app-domain: admin.controleonline.com.
  3. Credencial: Drive admin-api.json (pasta de credenciais do ecossistema). Não colar o token em issue, PR, wiki ou arquivo versionado.
  4. UI de conferência: https://admin.controleonline.com/admin/flowcharts/{id}.

O smoke só é aceito se:

  • declarar um ou mais flowchartIds existentes e enabled no admin;
  • tiver prints/screenshot de cada etapa relevante da jornada daquele flowchart;
  • continuar declarando fluxo: <id> deste catálogo (não substitui, soma).

Smoke órfão (fluxo: outros sem flowchartId válido) em entrega de UI desses produtos bloqueia aceite. O comentário de recusa do QA deve citar falta de flowchart ou falta de print por etapa.

Fonte canônica da regra: smoke-test-flows.md · qa/agent.md · issue agents-mcp#177.

Catálogo oficial

id ator principal nome
produto-cadastro backoffice / gestor Cadastro de produtos
compra-fluxo comprador / loja / POS Compra
device-configuracao admin / operador Configuração de devices
pedido-criacao vendedor / operador Criação de pedido
producao-fluxo produção / operação Produção
cliente-cadastro CRM / atendimento Cadastro de cliente
usuario-permissao admin Usuários, permissões e autenticação
financeiro-cobranca financeiro Cobrança, pagamento e conciliação
logistica-entrega logística / entrega Entrega e logística
relatorio-consulta gestor Relatórios e consultas gerenciais
integracao-api sistema / API Integração API entre módulos
outros qualquer Outros (fallback com justificativa obrigatória)

Regras de uso

  1. Todo smoke novo ou alterado deve referenciar exatamente um id da tabela (preferir o mais específico).
  2. Preferir o fluxo de negócio real exercitado pelo teste; usar outros só quando não houver correspondência razoável e justificar na issue.
  3. Em comentários de issue, evidência de QA ou descrição do smoke, declarar: fluxo: <id>.
  4. Não criar aliases, sub-fluxos ou nomes paralelos sem atualização humana da skill canônica.
  5. Smokes de infraestrutura, login genérico, healthcheck ou UI pontual sem jornada de negócio → outros, com justificativa objetiva.
  6. Testes espalhados por módulo devem ser encaixados em um manifesto por fluxo; o módulo/arquivo executado é detalhe de implementação.

Encaixe por visão (APP_TYPE)

Os fluxos acima atravessam várias visões do produto. Exemplos de encaixe (não exaustivo):

fluxo visões típicas módulos de UI comuns
produto-cadastro MANAGER, SHOP ui-products, ui-config
compra-fluxo SHOP, POS ui-shop, ui-orders
device-configuracao MANAGER, ADMIN ui-common, ui-config, ui-manager
pedido-criacao POS, CRM, MANAGER ui-orders, ui-crm
producao-fluxo MANAGER, SERVICE ui-orders, ui-logistic
cliente-cadastro CRM, MANAGER ui-customers, ui-people, ui-crm
usuario-permissao ADMIN, MANAGER ui-login, ui-people, ui-users
financeiro-cobranca MANAGER ui-financial
logistica-entrega DELIVERY, MANAGER ui-logistic, ui-orders
relatorio-consulta MANAGER ui-report, ui-dashboard
integracao-api sistema backends api-platform-* / api-community

Cada módulo deve documentar o que faz e o que não deve assumir na visão envolvida; detalhes de implementação ficam na wiki do submódulo.

Scripts e validação no app-community

Artefato Uso
scripts/browser-smoke-flows.cjs agrupamento / execução de smokes browser
scripts/browser-smoke-groups.cjs grupos de smoke
scripts/run-browser-smokes.cjs runner
scripts/validate-smoke-flow-catalog.cjs validação do catálogo local vs canônico

Suites de referência (flowchart 1)

Exemplos de smoke E2E amarrados ao flowchart admin id=1 (Venda / produção):

Suite Módulo Issue Contrato documentado
flowchart1WaiterTabs (mesa + ≥2 comandas → settlement → Ready) ui-orders #605 LinkedOrderSettlement — Mesa com múltiplas comandas

Links relacionados

Destino URL
Skill canônica (agents-mcp) https://github.com/ControleOnline/agents-mcp/blob/master/agents/skills/shared/quality/smoke-test-flows.md
code-quality https://github.com/ControleOnline/agents-mcp/blob/master/agents/skills/shared/quality/code-quality.md
Papel QA https://github.com/ControleOnline/agents-mcp/blob/master/agents/roles/qa/agent.md
Wiki API — Fluxos de Smoke https://github.com/ControleOnline/api-community/wiki/Fluxos-de-Smoke
Issue de origem (hotfix visual) https://github.com/ControleOnline/agents-mcp/issues/175
Gate flowcharts admin + flowchartIds https://github.com/ControleOnline/agents-mcp/issues/177
Programa E2E flowchart 1 (Venda/produção) Flowchart-1-Venda-Producao-E2E-Smokes · app-community#601

Fora de escopo desta página

  • Implementação dos arquivos de teste (Playwright, etc.) nos repositórios de produto.
  • Runners, workflows de CI ou inventário completo de arquivos de teste.
  • Alteração do catálogo sem solicitação humana.

Helpers reutilizáveis — device-configuracao

Biblioteca de smoke (login ADMIN + DeviceConfig PDV/DISPLAY/PRINT + troca de app) usada como pré-condição das jornadas do flowchart 1.

Documentação técnica completa: Smoke helpers — device-configuracao.

  • Código: ui-tests src/tests/helpers/adminDeviceFlow.js (+ adminLogin, deviceConfig, switchApp, smokeCredentials, smokeEvidence).
  • Spec isolado: ui-tests src/tests/browser/admin/device-configuracao.spec.js.
  • Manifesto: flowchartIds: [1], fluxo: device-configuracao, prints: login → lista-devices → pdv/display/print salvos → app-pos-aberto.
  • Issue: app-community#602.

Clone this wiki locally