> ## Documentation Index
> Fetch the complete documentation index at: https://visorai.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Scenarios

> Understand how visor scenarios are structured, validated, executed, and turned into repeatable runs.

A scenario is the main way to describe a repeatable verification flow in visor.

## Scenario structure

A scenario is a JSON object with these top-level fields:

| Field        | Required | Purpose                                                        |
| ------------ | -------- | -------------------------------------------------------------- |
| `meta`       | Yes      | Scenario identity                                              |
| `config`     | Yes      | Runtime defaults such as timeout, seed, and artifact directory |
| `steps`      | Yes      | Ordered execution steps                                        |
| `assertions` | No       | Checks evaluated after the steps finish                        |
| `output`     | No       | Output-related preferences                                     |

Unknown top-level fields are treated as validation errors.

## Minimal valid example

```json theme={null}
{
  "meta": {
    "name": "checkout-smoke",
    "version": "1"
  },
  "config": {
    "seed": 42
  },
  "steps": [
    {
      "id": "s1",
      "command": "screenshot",
      "args": {
        "label": "app-opened"
      }
    }
  ],
  "assertions": [],
  "output": {
    "report": ["summary", "json", "junit", "html"]
  }
}
```

## Supported step commands

Each step must use one of these commands:

* `tap`
* `navigate`
* `act`
* `scroll`
* `screenshot`
* `wait`
* `source`

Any other command name fails validation.

## Validation behavior

Validation checks both structure and command-specific arguments.

Examples of validation errors:

* missing `meta`, `config`, or `steps`
* `steps` is not a non-empty list
* unsupported command name
* `tap` mixes `target` with coordinates
* `tap` provides only one coordinate
* `navigate` omits `to`
* `scroll` omits `direction`
* `scroll` uses an unsupported `direction`
* `scroll` uses an out-of-range `percent`
* `wait` omits `ms`
* `meta.platform` is present but is not `ios` or `android`
* unknown fields in validated objects such as the top level, `meta`, `config`, each step object, each assertion object, and `output`

Examples of validation warnings:

* `config.seed` is missing
* `screenshot` step is missing a label

The `output.report` field is accepted for scenario shape compatibility, but the current report writer does not change behavior based on its contents.

If validation produces any error-level issue, the scenario is rejected.

## Runtime resolution for scenarios

Before executing a scenario, visor resolves:

* device
* platform inferred from the selected device
* timeout
* output directory
* server URL
* app identifier

Scenario configuration can provide non-device defaults, but explicit runtime input takes precedence.

## Step execution model

Scenario steps run in the order listed in `steps`.

Important behavior:

* each step produces a `StepResult`
* failures are recorded per step
* a failed step does not stop later steps from running
* timeout overruns convert a step into a failure even if the action itself returned data
* screenshot and source steps add artifacts to the run record
* mapped execution is enabled by default and may perform hidden route or repair actions before a target step
* hidden map actions are reported in `run.map` and `steps[].details.map`; the requested scenario step list is not rewritten

## Assertion phase

Assertions are evaluated after all steps complete.

Current assertion support:

* `visible`

Assertion failures change the final run status to failed.

If both a step failure and an assertion failure occur, the run ends in failure and the run-level error reflects the assertion failure because assertions are evaluated last.

## Run result shape

A scenario run produces:

* a unique run id
* start and end timestamps
* platform and device metadata
* per-step results
* assertion results
* collected artifact paths
* a determinism signature
* app-map metadata when mapped execution was enabled or disabled
* an optional run-level error payload

## Benchmark relationship

A benchmark is repeated execution of the same scenario.

For each iteration, visor:

1. creates a fresh adapter
2. executes the scenario
3. writes reports
4. records the determinism signature
5. counts failures

The benchmark then computes a determinism score from the collected signatures.