Scenarios - Visor

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

{
  "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:

creates a fresh adapter
executes the scenario
writes reports
records the determinism signature
counts failures

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

​Scenario structure

​Minimal valid example

​Supported step commands

​Validation behavior

​Runtime resolution for scenarios

​Step execution model

​Assertion phase

​Run result shape

​Benchmark relationship