Skip to main content
A scenario is a directory containing a scenario.json file and optional Ansible playbooks. All scenarios live under a shared root (auto-detected, or set with -p).

​
Directory Layout

scenarios/
  <category>/
    <NNN-scenario-name>/
      scenario.json       # required
      prepare.yml         # optional: Ansible setup before execution
      restore.yml         # optional: Ansible teardown after execution
      validate.yml        # optional: Ansible verification after execution
      inventory.ini       # optional: Ansible inventory
      [support files]     # config snippets, fixtures, test data, etc.
The category and numeric prefix (NNN) are conventions for organization: they have no special meaning to the runner. The runner uses the full relative path from the scenarios root as the scenario key (e.g. nginx/001-broken-config).

​
scenario.json

The only required file. At minimum, three fields are needed: 
{
  "key": "nginx/001-broken-config",
  "name": "Nginx Broken Configuration",
  "description": "@2501 the nginx service on the web server is not running. Investigate the issue and fix it so the service is running correctly."
}

​
Required Fields

FieldDescription
keyUnique identifier. Must match the relative directory path (e.g. nginx/001-broken-config).
nameHuman-readable name shown in reports.
descriptionThe instruction sent to the agent. Write it as you would a real task: describe symptoms, not solutions.

​
Optional Fields

FieldDescription
tagsString array for grouping. Pass a tag to -s to run all matching scenarios (e.g. -s nginx).
hostsTarget host definitions. See Hosts.
agentsAgent definitions. See Agents.
validationValidation rules. See Validation.

​
Writing Good Descriptions

The description is the exact instruction the agent receives. A few guidelines:
  • Describe symptoms, not solutions. “The nginx service is not running after a configuration change” is better than “Fix the nginx config file.”
  • Be concrete. Reference the host name, service name, or observable behavior when you know it.
  • Keep it realistic. Write it as you would a real support ticket or runbook task.

​
Scenario Keys and Tags

The key must exactly match the directory path relative to the scenarios root: 
scenarios/nginx/001-broken-config/scenario.json
                                   └─ key: "nginx/001-broken-config"
Tags are free-form strings for grouping. A scenario can have multiple tags: 
{
  "key": "nginx/001-broken-config",
  "name": "Nginx Broken Configuration",
  "description": "...",
  "tags": ["nginx", "web", "config"]
}
Run all scenarios with a given tag: 
2501-runner run -s nginx
2501-runner run -s web
Tags and explicit keys can be mixed: 
2501-runner run -s nginx,disk/001-cleanup