Command reference

This page documents the current command surface exactly as implemented. If you run visor --help or invoke the CLI with no command, visor prints a usage summary instead of a JSON response envelope.

​

Global runtime inputs

These inputs are accepted globally and, where relevant, by individual commands. Important notes:

• format is currently informational only for normal commands; the implementation still returns JSON envelopes
• visor --help and no-command invocation print plain-text usage instead of JSON

​

Direct action commands

​

tap

Purpose: click an element or coordinate. Inputs:

• target mode: target
• coordinate mode: x, y
• optional: normalized

Returns action payload fields:

• action
• platform
• args

args contains either:

• target, or
• x, y, and normalized

​

navigate

Purpose: move to a destination. Required input:

• to

Returns action payload fields:

• action
• platform
• args.to

Current behavior:

• in the real Appium adapter, the destination is passed to WebdriverIO through url(to)
• in mock mode, the destination is echoed back in the action payload

​

act

Purpose: perform a helper action. Supported variants:

• name=type with target and value
• name=back

Returns action payload fields:

• action
• platform
• args

​

scroll

Purpose: perform a page-style vertical scroll. Required input:

• direction with value up or down

Optional input:

• percent, default 70

Returns action payload fields:

• action
• platform
• args.direction
• args.percent

Current behavior:

• Android uses Appium scroll gestures within the current viewport
• iOS attempts the same gesture path and falls back to a touch swipe when needed

​

screenshot

Purpose: capture a PNG image. Optional input:

• label

Returns action payload fields:

• action
• platform
• args.label
• args.file
• args.path
• args.width
• args.height

If label is omitted, the runtime defaults it to capture.

​

wait

Purpose: pause execution. Required input:

• ms

Returns action payload fields:

• action
• platform
• args.ms

​

source

Purpose: capture current UI source as XML. Optional inputs:

• label
• path

Returns action payload fields:

• action
• platform
• args.label
• args.file
• args.path
• args.format
• args.bytes

For direct action commands, if Appium is auto-started for the command, visor stops that managed Appium process before returning.

​

Scenario commands

​

validate

Purpose: parse a scenario and return validation issues. Required input:

• scenario

Response data fields:

• valid
• issues

Exit behavior:

• returns success when the scenario is valid
• returns a non-zero exit code with status: ok when the scenario is syntactically valid JSON but fails schema validation
• returns a failure envelope when parsing fails or the file cannot be read

​

run

Purpose: execute one scenario, evaluate assertions, and write reports. Required input:

• scenario

Optional runtime inputs:

• platform
• device
• timeout
• output
• server-url
• app-id
• appium-cmd
• startup-timeout
• no-auto-start-appium
• attach
• mock

Response data fields:

• run
• warnings

The run object contains the full run result, including step results, assertion results, artifacts, determinism signature, and run-level error data. If Appium is auto-started for this command, visor stops that managed Appium process before returning.

​

benchmark

Purpose: run one scenario repeatedly and compute a determinism score. Required input:

• scenario

Optional inputs:

• runs with default 20
• threshold with default 95.0
• the same runtime inputs accepted by run

Response data fields:

• runs
• threshold
• determinismScore
• pass
• failures
• runIds
• warnings

If Appium is auto-started for this command, visor stops that managed Appium process before returning.

​

report

Purpose: return guidance about where run reports are stored. Optional input:

• path, which defaults to artifacts

Response data fields:

• message
• path
• format

​

Appium lifecycle commands

​

start

Purpose: start Appium when unreachable or return current reachable status. Optional inputs:

• server-url
• appium-cmd
• startup-timeout

Response data fields:

• serverUrl
• reachable
• managed
• pid
• command
• metadataPath
• logPath
• started
• alreadyRunning

​

status

Purpose: report whether Appium is reachable and whether it is managed by visor. Optional inputs:

• server-url

Response data fields:

• serverUrl
• reachable
• managed
• pid
• command
• metadataPath
• logPath

​

stop

Purpose: stop a visor-managed Appium process for the given server URL. Optional inputs:

• server-url
• force

Response data fields:

• serverUrl
• stopped
• managed
• reason
• pid
• reachable
• metadataPath
• logPath

​

Response envelope behavior

Every command returns the same top-level envelope fields:

• status
• command_id
• started_at
• ended_at
• artifacts
• next_action
• error
• data

next_action is a hint, not an execution chain. Examples include run, report, and none. Help output is the exception: visor --help and no-command invocation print usage text instead of an envelope.