Scenario schema

Top-level schema

Path	Type	Required	Notes
`$`	object	Yes	Scenario root
`$.meta`	object	Yes	Scenario metadata
`$.config`	object	Yes	Runtime defaults
`$.steps`	array	Yes	Must be a non-empty list
`$.assertions`	array	No	Defaults to empty list when omitted or null
`$.output`	object	No	Output preferences

Allowed top-level fields are exactly:

meta
config
steps
assertions
output

Any other top-level field is an error.

`meta`

Allowed fields:

Path	Type	Required	Notes
`$.meta.name`	string	Yes	Scenario name
`$.meta.version`	string	Yes	Scenario version
`$.meta.platform`	string	No	Legacy metadata field; if present, must be `ios` or `android`
`$.meta.tags`	array	No	Free-form tags

`config`

Allowed fields:

Path	Type	Required	Notes
`$.config.timeoutMs`	number	No	Per-step timeout threshold
`$.config.seed`	number	No	Missing seed triggers a warning
`$.config.artifactsDir`	string	No	Default report output directory

`steps[]`

Each step must be an object with these fields:

Path	Type	Required	Notes
`$.steps[i].id`	string	Yes	Step identifier
`$.steps[i].command`	string	Yes	One of the supported commands
`$.steps[i].args`	object	Yes	Command-specific arguments

Supported commands:

tap
navigate
act
scroll
screenshot
wait
source

Step argument rules

`tap`

Valid forms:

{ "target": "Increment" }

{ "x": 0.5, "y": 0.8, "normalized": true }

Rules:

cannot mix target with x or y
if using coordinates, both x and y are required
if present, normalized must be boolean

`navigate`

Required field inside args:

to

`act`

Validation only checks that args is present. Runtime support is narrower than schema support. The runtime currently accepts:

name=type with target and value, which types into the matching element
name=type with value only, which types into the currently focused field
name=back
name=home
name=reset
name=drag with startX, startY, endX, and endY
name=slider with target, value from 0 to 1, and optional startValue

For type, value is required and target is optional. drag also accepts normalized. reset restarts the target app and requires --app-id on Appium-backed runs.

`scroll`

Required field inside args:

direction with value up or down

Optional field inside args:

percent

Rules:

direction is required
direction must be up or down
if present, percent must be a number between 1 and 100

`screenshot`

No hard schema requirement beyond args, but missing label triggers a warning because it reduces determinism.

`wait`

Use exactly one wait mode inside args:

ms
for
stable

Optional timing controls:

timeout
pollMs
poll-ms

Valid forms:

{ "ms": 500 }

{ "for": "text=Ready", "timeout": 8000, "pollMs": 250 }

{ "stable": true, "timeout": 2000, "poll-ms": 100 }

Rules:

exactly one of ms, for, or stable is required
for must be a non-empty selector string
stable, when used, must be true
timing values must be non-negative numbers

`source`

No additional schema requirement beyond args.

`assertions[]`

Each assertion must be an object with these fields:

Path	Type	Required	Notes
`$.assertions[i].id`	string	Yes	Assertion identifier
`$.assertions[i].type`	string	Yes	Runtime only supports `visible`
`$.assertions[i].target`	string	Yes	Selector string

Important detail: unsupported assertion types pass schema validation but fail during execution.

`output`

Allowed fields:

Path	Type	Required	Notes
`$.output.report`	any	No	Accepted as a field name, but not interpreted by the current report writer

Full example

{
  "meta": {
    "name": "empty-app-counter",
    "version": "1",
    "tags": ["smoke", "counter"]
  },
  "config": {
    "timeoutMs": 15000,
    "seed": 42,
    "artifactsDir": "./artifacts"
  },
  "steps": [
    { "id": "s1", "command": "screenshot", "args": { "label": "counter-initial" } },
    { "id": "s2", "command": "wait", "args": { "ms": 2000 } },
    { "id": "s3", "command": "source", "args": { "label": "counter-initial-ui" } },
    { "id": "s4", "command": "tap", "args": { "target": "Increment" } },
    { "id": "s5", "command": "wait", "args": { "ms": 500 } },
    { "id": "s6", "command": "source", "args": { "label": "counter-after-increment-ui" } },
    { "id": "s7", "command": "screenshot", "args": { "label": "counter-after-increment" } }
  ],
  "assertions": [],
  "output": {
    "report": ["summary", "json", "junit", "html"]
  }
}

​Top-level schema

​meta

​config

​steps[]

​Step argument rules

​tap

​navigate

​act

​scroll

​screenshot

​wait

​source

​assertions[]

​output

​Full example

Top-level schema

`meta`

`config`

`steps[]`

Step argument rules

`tap`

`navigate`

`act`

`scroll`

`screenshot`

`wait`

`source`

`assertions[]`

`output`

Full example