Assertions personnalisées

Les assertions personnalisées transforment une exigence en commande que le harness VM peut exécuter. Utilisez-les pour un comportement que la petite suite par défaut ne couvre pas.

Structure

Chaque groupe custom-test a besoin d’une description et d’une ou plusieurs assertions structurées :

{
  "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 est requise sur le groupe et sur chaque assertion. on_vm sélectionne un ID VM dans un environnement de test multi-VM ; sans cela le runner utilise primary. expected_visual fournit l’état de capture d’écran voulu lorsque la porte de preuve visuelle est active.

Concevoir les assertions autour des résultats

• Vérifiez un service avec service_running, pas seulement que son paquet existe.
• Vérifiez un endpoint local avant de tester une route externe.
• Utilisez file_contains pour un fait de configuration stable, pas un instantané de fichier complet qui casse sur un formatage inoffensif.
• Utilisez command_succeeds seulement avec des commandes déterministes et non interactives.
• Donnez timeout_seconds aux longues commandes seulement si nécessaire. L’exécuteur borne les timeouts commande entre 1 et 1 800 secondes.
• Ne mettez jamais d’identifiants dans commandes, descriptions, sortie attendue ou URL ; ces champs peuvent apparaître dans preuves et journaux.

Sémantique d’échec

Un type inconnu est actuellement accepté par le modèle de recette mais devient error lorsque l’exécuteur ne trouve pas de handler. Les assertions connues qui omettent des paramètres requis peuvent être abandonnées lors de l’assemblage du plan de test avec un avertissement. Validez donc la recette et inspectez le plan de test matérialisé avant de lancer un build.

Si on_vm nomme une VM absente, l’assertion est skipped. Ne traitez pas skipped ou error comme une vérification réussie.

Exemple 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 résolution des noms VM dépend de la topologie de test et de ses adresses découvertes. Confirmez la topologie rendue et la commande résolue de l’assertion dans les preuves d’exécution.

Pour chaque type et paramètre supportés, voir Types d’assertion.