Smokes de integrações¶

Um smoke é uma verificação manual de configuração e contrato com um provider selecionado. O runner não substitui uma conversa completa de homologação. Ele pode consultar rede e, com autorização por flag, criar dados ou enviar mensagens reais.

Implementação: scripts/smoke.py; src/core/application/smokes/runner.py, models.py, sanitization.py e os quatro arquivos *_smoke.py. A dashboard chama esses mesmos runners.

Alvos, preflight e efeitos¶

Alvo CLI	Antes de autorizar efeitos	Com autorização
`whatsapp`	Confere habilitação, token, Phone Number ID, Graph API version e `SMOKE_WHATSAPP_TO`. Sem flag não constrói/envia a mensagem real.	Envia texto `[TESTE GoGenetic]` ao destino configurado
`egestor`	Confere URL/token por env ou SSM e constrói client. Pode ler SSM; não faz health HTTP. Retorna `skipped` sem escrita.	Executa `upsert_customer()` com payload do builder de produção e cadastro de teste embutido
`crm`	Exige base `https://crm-comercial-nine.vercel.app`, token, factory HTTP, `GET /health` e busca autenticada de contato. São chamadas de rede mesmo sem escrita.	Upsert de contato fictício, novo upsert para verificar atualização/duplicidade e criação de deal associado `[TESTE]`
`handoff-ses`	Confere notificador habilitado, tipo `email`, remetente e destinatário	Envia e-mail fictício pelo SES

O smoke CRM bloqueia outras bases pelo código _CRM_BASE_URL; não é um runner genérico para qualquer sandbox compatível HubSpot. O smoke eGestor não tem endpoint de leitura seguro confirmado no próprio runner: construir o client não prova autenticação ou disponibilidade do serviço.

Flags reais e carregamento¶

CLI	Variável correspondente	Autoriza
`--allow-real-send`	`SMOKE_ALLOW_REAL_SEND=true`	WhatsApp
`--allow-real-write`	`SMOKE_ALLOW_REAL_WRITE=true`	CRM e eGestor
`--allow-real-email`	`SMOKE_ALLOW_REAL_EMAIL=true`	SES

A CLI carrega .env sem substituir variáveis já exportadas e só altera flags cujo argumento foi passado. Portanto, omitir --allow-real-write não desliga uma variável que já estava true. Para um preflight de leitura, force explicitamente as três permissões para false:

Windows / PowerShellLinux / macOS

$env:SMOKE_ALLOW_REAL_SEND = "false"
$env:SMOKE_ALLOW_REAL_WRITE = "false"
$env:SMOKE_ALLOW_REAL_EMAIL = "false"
python scripts/smoke.py --target crm --format json

SMOKE_ALLOW_REAL_SEND=false SMOKE_ALLOW_REAL_WRITE=false SMOKE_ALLOW_REAL_EMAIL=false \
  python scripts/smoke.py --target crm --format json

Esse preflight ainda consulta o CRM real. Para todos os alvos, use --all em lugar de --target crm, mantendo as três variáveis falsas. Na dashboard, os valores dos formulários sobrescrevem explicitamente as permissões com False no caminho safe.

O launcher scripts/dashboard.py mantém mock_aws() ativo para o processo inteiro. Clientes boto3, incluindo SES/SSM, ficam nesse contexto simulado; um resultado SES na dashboard local não comprova entrega de e-mail real. Clientes HTTP de CRM, eGestor, Meta e OpenAI não são isolados por esse mock AWS. Para homologar o SES real, o caminho previsto é a CLI fora de moto, com autorização e credenciais do ambiente correto.

Execuções com efeito externo¶

Somente após combinar ambiente, destinatário e dados de teste com os responsáveis:

python scripts/smoke.py --target whatsapp --allow-real-send --format json
python scripts/smoke.py --target crm --allow-real-write --format json
python scripts/smoke.py --target egestor --allow-real-write --format json
python scripts/smoke.py --target handoff-ses --allow-real-email --format json

Execute um alvo por vez. Não há argumento CLI para substituir o documento do smoke eGestor nem limpeza automática dos objetos criados. O cadastro eGestor usa um documento fixo embutido no runner, então uma repetição pode atualizar o mesmo registro; confirme seu uso exclusivo no ambiente de teste. Os exemplos desta documentação não reproduzem os números/documentos do runner.

--all executa todos os alvos, inclusive os que estão habilitados no ambiente; as três permissões são independentes. WHATSAPP_FREE_ONLY não substitui autorização de envio nem garante que o número destino tenha uma janela aberta na Meta.

Pré-requisitos por provider¶

Além dos settings globais exigidos por load_settings(), configure as variáveis de referência: grupo WHATSAPP_* e destino de smoke; EGESTOR_ENABLED e URL/token; HUBSPOT_ENABLED, base, token, pipeline e stages; ou HANDOFF_NOTIFIER_ENABLED, tipo email, endereços e região SES. Leitura de secrets SSM requer credenciais AWS apropriadas. Não inclua tokens em comandos ou evidências compartilhadas.

Resultado e códigos de saída¶

SmokeResult contém target, status, title, duration_ms, lista de checks, sanitized_error, correlation_id, next_steps e created_ids.

{
  "target": "crm",
  "status": "success",
  "title": "CRM Comercial GoGenetic",
  "duration_ms": 420,
  "checks": [
    {"name": "health público", "status": "success", "detail": null},
    {"name": "escrita real autorizada", "status": "skipped", "detail": null}
  ],
  "sanitized_error": null,
  "correlation_id": null,
  "next_steps": [],
  "created_ids": {}
}

O exemplo é reduzido para leitura; a execução inclui outros checks. success com escrita skipped significa sucesso do preflight, não da criação de negócio. Um HTTP 401 no probe CRM retorna blocked, preservando correlation ID quando disponível. Configuração incompleta ou falha HTTP pode retornar failed.

Status	Interpretação	Exit code agregado
`success`	Checks pedidos concluídos	0 se não houver falha/bloqueio
`skipped`	Integração desligada ou efeito não autorizado	Também 0; não é homologação real
`blocked`	Impedimento externo conhecido, como CRM 401	2, se não houver `failed`
`failed`	Erro de config, rede, contrato ou operação	1, tem prioridade

Em formato table, a CLI mostra os nomes das chaves em created_ids; use --format json para obter os IDs necessários à conferência/limpeza. sanitize_error() remove dados conhecidos, mas revise a evidência antes de compartilhá-la. Não foram executados smokes nesta tarefa de documentação.

Testes e manutenção¶

tests/unit/application/test_smokes.py cobre roteamento, serialização, CRM 401, prefixo [TESTE], guards de envio/escrita/email, builder eGestor e sanitização. Ao adicionar um alvo, crie runner, enum/roteamento, guard explícito, resultado estruturado, teste de “sem permissão não escreve” e documentação do cleanup. Consulte homologação para o fluxo completo.