SCRYDOSBox-XReferenceSequencesperformAlso in MAME

DOSBox-XSequences

perform

Run a list of this server's tools in one call, in order, stopping at the first step that fails.

perform(steps=null, path="", settle_seconds=30.0, summaries=false, until_frame=0)

Try it

On Bricks, the game this repository builds, while it runs with the mouse moving the paddle.
Ask

Give the paddle back to the keyboard with M, then serve with the space bar, checking the game logged each key.

Call
perform(
    steps=[{"op": "send_keys", "keys": ["m"], "expect": "MOUSE OFF$", "seconds": 10}, "… 1 more"])
Reply 5 of 8 fields
{
  "summary": "perform: 2 of 2 steps, still running",
  "steps_completed": 2,
  "failed_at": {"available": false, "why": "no step failed"},
  "still_running": true,
  "held": 0
}

Both steps ran and none failed. still_running says the list ended with the game running and waited for no stop; held is 0 because no step carried recorded values.

The whole reply
JSON
{
  "summary": "perform: 2 of 2 steps, still running",
  "status": "ok",
  "ran": [
    {
      "op": "send_keys",
      "reply": {
        "summary": "send_keys (guest): reaction seen",
        "status": "ok",
        "keys": ["m"],
        "modifiers": [],
        "route": "guest",
        "posted": 1,
        "bytes": 2,
        "frames": 2,
        "verify": {
          "checked": true,
          "seen": true,
          "expected": "MOUSE OFF$",
          "verdict": "TARGET",
          "line": "Bochs port E9h: MOUSE OFF",
          "seen_before_waiting": "<volatile>",
          "lines_before": "<volatile>",
          "waited_s": "<volatile>",
          "lines_total": "<volatile>"
        },
        "session": {"alive": true, "running": true, "altered": true}
      }
    },
    {
      "op": "send_keys",
      "reply": {
        "summary": "send_keys (guest): reaction seen",
        "status": "ok",
        "keys": ["space"],
        "modifiers": [],
        "route": "guest",
        "posted": 1,
        "bytes": 2,
        "frames": 2,
        "verify": {
          "checked": true,
          "seen": true,
          "expected": "SERVE$",
          "verdict": "TARGET",
          "line": "Bochs port E9h: SERVE",
          "seen_before_waiting": "<volatile>",
          "lines_before": "<volatile>",
          "waited_s": "<volatile>",
          "lines_total": "<volatile>"
        },
        "session": {"alive": true, "running": true, "altered": true}
      }
    }
  ],
  "steps_completed": 2,
  "failed_at": {"available": false, "why": "no step failed"},
  "still_running": true,
  "note": "the sequence ended with the machine running after a step that answers on a running machine, and nothing declared can stop it (no breakpoint, no interrupt breakpoint, no change watch), so no stop was waited for; declare one, or end the list  ... (301 characters)",
  "held": 0
}

Arguments

steps array of object, optional
The list to run: each step is {"op": <tool>, ...} with that tool's own arguments. Give this or path, never both.
path string, default ""
A saved step list to replay in place of steps: a file under .scry/perform/ or one perform_export wrote. Absolute, or starting with ~.
settle_seconds number (>= 0, <= 600.0), default 30.0
How long each wait for a stop may take, before a step that needs one: 0 to 600 seconds. 0 never waits; left out, 30.
summaries boolean, default false
true cuts each step's reply but the last to a short row and writes the full replies to a file. Left out, every reply comes back whole.
until_frame integer, default 0
A frame number, counted since power-on: the list repeats until a stop reads that frame. Needs summaries and a run_for step; left at 0, the list runs once.

What comes back

ran
One row per step that ran: its op and its full reply. With summaries a row adds its step, and ran_path and replies_path hold them all.
held
How many steps carried recorded, the values a replayed step must give again, and gave them. 0 when no step carried any.
failed_at
The step that failed, counted from 0, with its op and reply in failed. When none failed it is available: false with a why.
errors
Every step refused before anything ran, each with its step, op, code and message.
verdict
Comes once the list waited for a stop: TARGET with the stop in stopped, or TIMEOUT with a note. A list that waited for none says still_running.
stops
With summaries, the server's own count of the stops: stop_seq_first, stop_seq_last, surveyed (how many a reply described), by_cause and unaccounted.
All 20 reply fields
  • errors (array)
  • failed (object)
  • field (string)
  • got (any)
  • ran_path (string or object)
  • recorded (any)
  • replies_path (string or object)
  • steps_total (integer)
  • still_running (boolean)
  • stopped (object)
  • stops (object)
  • truncated (boolean)
  • verdict (string)
  • failed_at (integer or object)
  • held (integer)
  • ran (array)
  • steps_completed (integer)
  • frame_reached (integer or object)
  • operations (array)
  • until_frame (integer)

What it refuses

Why it works this way

The whole list is checked before its first step runs, so a refusal never arrives after earlier steps changed the machine. What only a running step can know refuses at that step: a symbol against the table loaded by then, a file an earlier step writes, the cpu's mode.

A step that needs the program stopped waits up to settle_seconds for the stop. A wait that runs out ends the list TIMEOUT: the steps after it were built on what it waited for. So does a step whose own wait missed: a log_wait or screen_wait that timed out, a send_keys or send_mouse whose expect never came.

A step may carry recorded, a {field: value} object of its own reply, and a reply with other values ends the list. That turns a list into a test, and perform_export writes such lists from a session.

More on why

until_frame counts what happens before a frame when nobody can know how many steps that takes. Every stop a watch makes takes a step without moving the frame, so a list sized by guessing ends short, with a smaller count that looks right.

The call ends right after the first step whose stop reads the frame, even mid-list, and frame_reached says which. It needs a run_for step because run_for carries on past a watch's stop, where run_to and step end at the first.

On a running program the first stop starts the count. Running out of steps or seconds is a TIMEOUT that names the last frame read. An exported script keeps the steps the repetitions ran, never the until_frame.

With summaries, steps_total counts the rows and truncated says the reply shows fewer. Read stops for a count and ran_path for the whole table: a count made by hand from cut rows comes out wrong and looks right.

After a resume step the server asks the debugger's RUNSTATE whether the program stopped again, so a stop is never guessed from a step's name. A step that comes back with the program running counts as a resume, and a stop step ends the run.

A screen_view step returns its text in the reply and writes its picture to its path, answering not_inlined: nested.

Steps on a running program

  • A step from the list a not_stopped refusal names in answers_while_running runs on a running program. Any other waits for a stop, symbols_load included even with a base.
  • That list also names tools that are no step: close, drive, perform, perform_export, window and promote.
  • A list that ends with the program running after such a step, with nothing declared that could stop it, returns at once and its note says why.
  • operations, the tools a step may name, comes once at the top of the reply, inside act in a drive.
The contract your client receives
Text
A sequence of this server's operations in one call, in order on the open session,
stopping at the first failure; `drive` is this plus a wait for a line of the E9 log.

`steps`: `{"op": <tool>, ...arguments}`, any tool but `build_check`, `start`, `close`,
`perform`, `drive`, `perform_export`, `window`, `promote`. `path`: a `perform` document (absolute or `~`-led:
`.scry/perform/<name>.json`, or a file `perform_export` wrote) whose steps are replayed; give
`steps` or `path`, never both.
A `send_keys` or `send_mouse` whose `expect`
misses ends the list `TIMEOUT`. A step's `recorded`, `{field: value}` of its
own reply, must hold, else INVALID `diverged`.
The whole list is checked first: INVALID `errors` (`step`, `op`, `code`, `message`),
nothing run. `settle_seconds` bounds each wait for a stop before a step that needs one (0:
never wait). `until_frame=F` needs `summaries=True` (a window is hundreds of steps) and a `run_for` step, and repeats the list until a stop reads frame F, within 5000 steps and 600 s; `no_channel` if there is no frame counter. Frames count since power-on. A `screen_view` step inlines its
text; its picture is written to its `path` and answers `not_inlined: nested`.

Reply: `ran`, `steps_completed`, `held`, `failed_at`, `failed` (INVALID `step_failed`),
`verdict` (once the list waited; `TARGET` adds `stopped`, `TIMEOUT` `note`), else
`still_running`; `frame_reached` (with `until_frame`).

Reference: REFERENCE.md, Several calls as one.

summaries: True (of the call, never of a step) makes each step but the last a compact row; `ran` shows the first 24 (`truncated`), `ran_path` and `replies_path` hold all; `stops` counts the stops.
Tools