Типи assertions

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

Stable guest assertions

Type	Required `params`	Optional behavior
`user_exists`	`username`	Runs `id`
`user_password`	`username`	Verifies unlocked password hash exists; does not attempt interactive login
`user_in_group`	`username`, `group`	Accepts Vyatta administrative equivalents when checking `sudo`/`admin`
`file_exists`	`path`	Accepts file or directory
`file_contains`	`path`, `pattern` or `content`	Uses `grep`; value is grep pattern, not literal-only comparison
`file_permissions`	`path`, `mode`	Compares octal mode reported by `stat`
`service_running`	`service`	Checks systemd active state; knows small cross-distro alias set
`service_enabled`	`service`	Checks systemd enablement
`package_installed`	`package`	Checks guest 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` clamped to 1–1,800 seconds
`command_output`	`command` plus regex in `expected_pattern`, `pattern`, `expected`, or 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]+$"
  }
}

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

GUI assertions

GUI checks depend on working display session and runner screenshot or input helpers. 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 application and looks for window
`gui_window_visible`	window-title or matching parameters used by handler	Looks for existing window
`gui_execute_command`	`command`	Executes desktop command; can capture screenshot
`gui_application_process`	`process_name`	Looks for process as headless fallback
`gui_screenshot_matches`	`reference_id`; optional `threshold`, crop/mask regions	Compares current screenshot with stored reference
`gui_wallpaper_matches`	`wallpaper_path`; optional thresholds and regions	Checks configured wallpaper path and visual result
`desktop_wallpaper_matches`	`wallpaper_path`	Runs 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 screen or selected region

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

Benchmark checks are separate format

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

Result interpretation

Missing required data yields error, or planner may drop assertion with warning before execution.
Unavailable on_vm target yields skipped.
Non-matching result yields failed.
Only passed is affirmative evidence for that assertion.

See Custom assertions for authoring guidance.