Asserções personalizadas

Asserções personalizadas transformam requisito em comando que harness de VM pode executar. Use para comportamento que suíte default pequena não cobre.

Estrutura

Cada grupo custom-test precisa descrição e uma ou mais asserções estruturadas:

{
  "description": "Verify the web service",
  "category": "application",
  "assertions": [
    {
      "type": "service_running",
      "description": "Nginx is active",
      "params": { "service": "nginx" },
      "expected_visual": "The evidence panel shows nginx active"
    },
    {
      "type": "http_responds",
      "description": "Local health endpoint responds",
      "params": { "url": "http://localhost/health", "status": 200 }
    }
  ]
}

description é obrigatório no grupo e em cada asserção. on_vm seleciona ID de VM em ambiente multi-VM; sem ele runner usa primary. expected_visual fornece estado de screenshot pretendido quando gate de evidência visual está ativo.

Projete asserções em torno de resultados

• Cheque serviço com service_running, não só que pacote existe.
• Cheque endpoint local antes de rota externa.
• Use file_contains para um fato estável de configuração, não snapshot de arquivo completo que quebra com formatação inofensiva.
• Use command_succeeds só com comandos determinísticos não interativos.
• Dê timeout_seconds a comandos longos só quando necessário. Executor limita timeouts de comando a 1–1.800 segundos.
• Nunca coloque credenciais em comandos, descrições, saída esperada ou URLs; esses campos podem aparecer em evidência e logs.

Semântica de falha

Tipo desconhecido é aceito pelo modelo de receita hoje mas vira error quando executor não encontra handler. Asserções conhecidas que omitem parâmetros obrigatórios podem ser descartadas na montagem do plano de teste com aviso. Valide receita e inspecione plano de teste materializado antes de iniciar build.

Se on_vm nomeia VM ausente, asserção é skipped. Não trate skipped ou error como verificação bem-sucedida.

Exemplo multi-VM

{
  "description": "Client reaches the API node",
  "assertions": [
    {
      "type": "http_responds",
      "description": "API health is reachable from the client",
      "on_vm": "client",
      "params": { "url": "http://api:8080/health", "status": 200 }
    }
  ],
  "environment": {
    "vms": [
      { "vm_id": "client", "role": "client", "networks": ["lan"] },
      { "vm_id": "api", "role": "server", "networks": ["lan"] }
    ],
    "networks": [
      { "network_id": "lan", "type": "isolated", "dhcp": true }
    ]
  }
}

Resolução de nome de VM depende de topologia de teste e endereços descobertos. Confirme topologia renderizada e comando resolvido da asserção na evidência do run.

Para todo tipo e parâmetro suportados, veja Tipos de asserção.