Assertion Types

Canonical reference for assertions executed inside a provisioned test VM. Unless noted, the target is primary. Each assertion also requires a human readable description.

Stable guest assertions

Type	Required `params`	Optional behavior
`user_exists`	`username`	Runs `id`
`user_password`	`username`	Verifies an unlocked password hash exists; it does not attempt an interactive login
`user_in_group`	`username`, `group`	Accepts Vyatta administrative equivalents when checking `sudo`/`admin`
`file_exists`	`path`	Accepts a file or directory
`file_contains`	`path`, `pattern` or `content`	Uses `grep`; the value is a grep pattern, not a literal-only comparison
`file_permissions`	`path`, `mode`	Compares the octal mode reported by `stat`
`service_running`	`service`	Checks systemd active state; knows a small cross-distro alias set
`service_enabled`	`service`	Checks systemd enablement
`package_installed`	`package`	Checks the guest’s supported package-manager database
`port_listening`	`port`	`protocol` may be `tcp` or `udp`; default is TCP
`command_succeeds`	`command`	Exit code must be zero; `timeout_seconds`/`timeout` is clamped to 1–1,800 seconds
`command_output`	`command` plus a regex in `expected_pattern`, `pattern`, `expected`, or the assertion-level `expected`	Matches stdout with Python regular-expression semantics
`network_reachable`	`host`	`count` defaults to 3; uses ICMP ping
`http_responds`	`url`	`status` defaults to 200

Example:


{
  "type": "command_output",
  "description": "Application reports the expected release",
  "params": {
    "command": "/opt/acme/bin/acme --version",
    "expected_pattern": "^acme 2\\.4\\.[0-9]+$"
  }
}

The command and captured output can become test evidence. Do not embed secrets.

GUI assertions

GUI checks depend on a working display session and the runner’s screenshot or input helpers. They are more environment-sensitive than guest command checks.

Type	Principal parameters	What it checks
`gui_application_opens`	`application` (canonical); handler also accepts launch-specific options	Starts an application and looks for a window
`gui_window_visible`	window-title or matching parameters used by the handler	Looks for an existing window
`gui_execute_command`	`command`	Executes a desktop command; can capture a screenshot
`gui_application_process`	`process_name`	Looks for the process as a headless fallback
`gui_screenshot_matches`	`reference_id`; optional `threshold`, crop/mask regions	Compares the current screenshot with a stored reference
`gui_wallpaper_matches`	`wallpaper_path`; optional thresholds and regions	Checks the configured wallpaper path and visual result
`desktop_wallpaper_matches`	`wallpaper_path`	Runs the stricter desktop-wallpaper provenance/configuration/visual check
`gui_click_element`	`x`, `y`	Sends coordinate-based pointer input
`gui_form_fill`	`fields`	Fills coordinate-described form inputs
`gui_text_visible`	`text`, `contains`, or `ocr_contains`	Uses OCR on the screen or a selected region

The executor also accepts compatibility aliases for some OCR and wallpaper types. Prefer the canonical names above in new recipes. Coordinate tests are resolution-sensitive; use OCR or outcome checks where possible.

Benchmark checks are a separate format

cis_benchmark appears in the recipe’s historical assertion vocabulary, but the ordinary assertion dispatcher has no cis_benchmark handler. CIS and other benchmark checks are supplied as benchmark records with an audit_script and execute through the benchmark runner. Use the CIS benchmark workflow, not a custom assertion with type: "cis_benchmark".

Result interpretation

Missing required data yields error, or the planner may drop the assertion with a warning before execution.
An unavailable on_vm target yields skipped.
A non-matching result yields failed.
Only passed is affirmative evidence for that assertion.

See Custom assertions for authoring guidance.