Aserciones personalizadas

Las aserciones personalizadas convierten un requisito en un comando que el harness VM puede ejecutar. Úsalas para comportamiento que la suite pequeña por defecto no cubre.

Estructura

Cada grupo custom-test necesita una descripción y una o más aserciones estructuradas:

{
  "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 es requerida tanto en el grupo como en cada aserción. on_vm selecciona un ID de VM en un entorno de prueba multi-VM; sin él el runner usa primary. expected_visual aporta el estado de captura previsto cuando la puerta de evidencia visual está activa.

Diseña aserciones en torno a resultados

• Comprueba un servicio con service_running, no solo que exista su paquete.
• Comprueba un endpoint local antes de probar una ruta externa.
• Usa file_contains para un hecho de configuración estable, no una instantánea de archivo completo que rompa por formato inofensivo.
• Usa command_succeeds solo con comandos deterministas y no interactivos.
• Da a comandos largos timeout_seconds solo cuando haga falta. El ejecutor limita timeouts de comando a 1–1,800 segundos.
• Nunca coloques credenciales en comandos, descripciones, salida esperada o URL; estos campos pueden aparecer en evidencia y logs.

Semántica de fallo

Un tipo desconocido es aceptado actualmente por el modelo de receta pero pasa a error cuando el ejecutor no encuentra handler. Las aserciones conocidas que omiten parámetros requeridos pueden descartarse durante el ensamblado del plan de prueba con advertencia. Por tanto, valida la receta e inspecciona el plan de prueba materializado antes de iniciar una compilación.

Si on_vm nombra una VM que no está presente, la aserción es skipped. No trates skipped o error como verificación exitosa.

Ejemplo 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 }
    ]
  }
}

La resolución de nombres VM depende de la topología de prueba y sus direcciones descubiertas. Confirma la topología renderizada y el comando resuelto de la aserción en la evidencia de ejecución.

Para cada tipo y parámetro admitidos, consulta Tipos de aserción.