Skip to content

Playground JSON flowchartIds e links admin

Jump to bottom
ControleOnline Agents edited this page Aug 26, 2026 · 1 revision

Playground JSON: flowchartIds e links do admin por suite

Documentação técnica do contrato de metadados de flowchart no índice público do smoke-tests-playground (GET /tests e aliases).

Issue de origem: smoke-tests-playground#7
Programa pai: app-community#601 (smokes E2E do flowchart Venda / produção, admin id 1, flowKey=sales-production)
Código canônico (master): SmokeFlowchartMetadata, SmokeTestsIndexFactory, SmokeReportReader / SmokeXmlReportParser

Objetivo

Permitir que cada suite (e, opcionalmente, cada teste) declare vínculo com os flowcharts publicados no admin, para:

  • organizar e filtrar o índice agregado por flowchart;
  • expor links estáveis para a UI do admin (/admin/flowcharts/{id});
  • manter suites legadas sem o campo (compatibilidade: flowchartIds: []).

O playground não inventa vínculo. Só propaga o que o report declarar (ou o que já estiver em links válidos do admin).

Escopo e fora de escopo

Em escopo Fora de escopo
Contrato JSON do índice (GET /tests) Implementação dos smokes Playwright
Normalização de IDs / links / flowKey UI HTML no bundle
Agrupamento flowcharts[] no índice Autorização ou multi-tenant no index (metadados de report apenas)
Extração a partir de report.json / campos no payload remoto Alteração do catálogo de flowcharts no admin

Componentes

Classe Papel
SmokeFlowchartMetadata Normaliza flowchartIds, monta flowchartLinks, extrai flowKey, enriquece suite/testes e agrupa suites por id
SmokeTestsIndexFactory Monta o índice: enriquece cada suite via metadata e publica summary.flowcharts + flowcharts[]
SmokeReportReader / SmokeXmlReportParser Leitura local de reports; campos de flowchart passam no payload de suite quando presentes no JSON (ou equivalentes no fluxo de parse)
SmokeRemoteIndexReader Suites remotas também passam por enrichSuite

Base de URL fixa (não configurável por env nesta entrega):

https://admin.controleonline.com/admin/flowcharts

Constante: SmokeFlowchartMetadata::ADMIN_FLOWCHART_BASE.

Contrato por suite (e por teste)

Campos adicionados (ou normalizados) em cada suite do índice:

Campo Tipo Regra
flowchartIds list<int> IDs positivos únicos; vazio se o report não declarar
flowchartLinks list<string> Uma URL por id: {ADMIN_FLOWCHART_BASE}/{id}
flowKey string | null Chave opcional (sales-production, etc.); não implica id

Os mesmos campos podem aparecer em cada item de tests[]:

  • se o teste declarar IDs próprios, usa a normalização do teste;
  • senão, herda o metadata da suite;
  • flowKey do teste, se presente, prevalece sobre o da suite.

Fontes aceitas na normalização

A partir de um array-fonte (suite ou teste), normalize() considera, sem inventar id a partir só do nome da suite:

  • flowchartIds / flowchart_ids (lista ou escalar)
  • flowchartId / flowchart_id
  • flowchart.id / flowchart.ids
  • flowchartLinks / flowchart_links — extrai id via regex #/admin/flowcharts/(\d+)#
  • flowKey / flow_key / flowchartKey

Importante: flowKey=sales-production sozinho não gera flowchartIds: [1]. O vínculo numérico precisa ser declarado (ou recuperável de um link válido do admin).

Exemplo — suite do fluxo Venda / produção

{
  "suite": "balcao-prepaid",
  "displayName": "Balcão prepaid",
  "flowchartIds": [1],
  "flowchartLinks": [
    "https://admin.controleonline.com/admin/flowcharts/1"
  ],
  "flowKey": "sales-production",
  "tests": [
    {
      "title": "pedido prepaid",
      "status": "passed",
      "flowchartIds": [1],
      "flowchartLinks": [
        "https://admin.controleonline.com/admin/flowcharts/1"
      ],
      "flowKey": "sales-production"
    }
  ]
}

Exemplo — suite legada (sem declaração)

{
  "suite": "legacy-suite",
  "flowchartIds": [],
  "flowchartLinks": [],
  "flowKey": null
}

Índice agregado: seção flowcharts

Além de enriquecer cada suite, o factory publica:

{
  "summary": {
    "flowcharts": {
      "total": 1
    }
  },
  "flowcharts": [
    {
      "id": 1,
      "link": "https://admin.controleonline.com/admin/flowcharts/1",
      "flowKeys": ["sales-production"],
      "suites": [ /* suites que declararam id 1 */ ]
    }
  ]
}

Regras de groupSuites:

  • só entra suite com flowchartIds não vazio;
  • uma suite pode aparecer em mais de um id se declarar vários;
  • flowKeys é lista única de chaves não vazias vistas nas suites daquele id;
  • ordenação numérica crescente por id.

Isso permite filtrar/agrupar no consumidor (tests-frontend-tool ou scripts) sem varrer todas as suites.

Fluxo de montagem do índice

flowchart LR
  local["SmokeReportReader<br/>var/tests/**/report.*"] --> enrich
  remote["SmokeRemoteIndexReader"] --> enrich
  enrich["SmokeFlowchartMetadata.enrichSuite"] --> sort["usort suites"]
  sort --> index["SmokeTestsIndexFactory.create"]
  index --> out["GET /tests<br/>types + suites + flowcharts"]
Loading
  1. Descobre reports locais e suites remotas.
  2. Cada payload passa por enrichSuite (IDs/links/flowKey + propagação aos testes).
  3. Ordena suites por timestamp / id.
  4. Constrói seções types, summary e flowcharts (agrupamento).

Rotas que expõem o contrato

Inalteradas em path; o payload do índice ganha os campos acima:

  • GET /tests
  • GET /tests/index.json
  • GET /tests/api

Compatibilidade: consumidores antigos que ignoram campos extras continuam válidos. Suites sem declaração não quebram o schema (listas vazias / flowKey null).

Papel no ecossistema (APP_TYPE / modos)

O playground é infra de qualidade, não uma visão de produto (MANAGER, POS, PPC, etc.).

  • Não substitui o admin de flowcharts nem a API GET /flowcharts/{id}.
  • Não decide regras de negócio de venda/produção; apenas amarra suites de smoke ao diagrama oficial (ex.: admin id 1).
  • Os smokes que cobrem jornadas reais (balcão, garçom/mesa, multi-comanda, PCP, delivery) vivem nos módulos de produto e no programa app-community#601; este módulo só indexa e linka.

Referência visual do fluxo id 1: admin flowchart 1.

Testes unitários de contrato

tests/Service/SmokeFlowchartMetadataTest.php cobre, entre outros:

  • report sem IDs → listas vazias e flowKey null;
  • IDs declarados → links admin corretos + flowKey;
  • flowKey sozinho não inventa id;
  • extração de id a partir de flowchartLinks válidos;
  • propagação suite → testes e agrupamento groupSuites.

Arquivos da entrega permanecem ≤ 500 linhas (SmokeFlowchartMetadata, factory, reader, parser).

Manutenção

  1. Novos flowcharts no admin: o smoke declara flowchartIds (e opcionalmente flowKey) no report; o índice passa a listar o id e o link sem mudança de código no playground.
  2. Não hardcode lista de ids no factory — a fonte é o report.
  3. Se a base pública do admin mudar de host/path, atualizar ADMIN_FLOWCHART_BASE e os testes de link.
  4. Manter a regra “não inventar vínculo” ao estender o parser (XML/JSON).

Links relacionados

Destino URL
Issue #7 https://github.com/ControleOnline/smoke-tests-playground/issues/7
Programa pai #601 https://github.com/ControleOnline/app-community/issues/601
Admin flowchart 1 https://admin.controleonline.com/admin/flowcharts/1
Home deste módulo Home
Instalação Instalacao
Wiki API https://github.com/ControleOnline/api-community/wiki
Wiki App https://github.com/ControleOnline/app-community/wiki
Código SmokeFlowchartMetadata https://github.com/ControleOnline/smoke-tests-playground/blob/master/src/Service/SmokeFlowchartMetadata.php
Código SmokeTestsIndexFactory https://github.com/ControleOnline/smoke-tests-playground/blob/master/src/Service/SmokeTestsIndexFactory.php

Clone this wiki locally