SCRYDOSBox-XReferenceSequencesperformAlso in MAME
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
Give the paddle back to the keyboard with M, then serve with the space bar, checking the game logged each key.
perform(
steps=[{"op": "send_keys", "keys": ["m"], "expect": "MOUSE OFF$", "seconds": 10}, "… 1 more"]){
"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
{
"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 orpath, never both. - path string, default
"" - A saved step list to replay in place of
steps: a file under.scry/perform/or oneperform_exportwrote. 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 truecuts 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
summariesand arun_forstep; left at 0, the list runs once.
What comes back
- ran
- One row per step that ran: its
opand its fullreply. Withsummariesa row adds itsstep, andran_pathandreplies_pathhold 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
opandreplyinfailed. When none failed it isavailable: falsewith awhy. - errors
- Every step refused before anything ran, each with its
step,op,codeandmessage. - verdict
- Comes once the list waited for a stop:
TARGETwith the stop instopped, orTIMEOUTwith anote. A list that waited for none saysstill_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_causeandunaccounted.
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
- A step that names no tool, an argument its tool does not take or a value it refuses. Nothing runs, and
operationslists the tools a step may name (bad_argument). - Both
stepsandpath, neither, or an empty list (bad_argument). - A step that answers INVALID: the list ends there (
step_failed). - A step whose reply differs from its
recordedvalues; the reply names thefield, therecordedvalue and what itgot(diverged). - A step that needs the program stopped while it still runs and
settle_secondsis 0 (not_stopped). until_framewithoutsummaries, without arun_forstep, or at a frame the program has already reached (bad_argument).until_frameon a build whoseRUNSTATEprints noframes=, so there is no frame to count (no_channel).- A stop that reads no frame under
until_frame, since nothing then says whether the frame came (unexpected_answer). - The emulator gone before a step could run (
session_broken).
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_stoppedrefusal names inanswers_while_runningruns on a running program. Any other waits for a stop,symbols_loadincluded even with abase. - That list also names tools that are no step:
close,drive,perform,perform_export,windowandpromote. - A list that ends with the program running after such a step, with nothing declared that could stop it, returns at once and its
notesays why. operations, the tools a step may name, comes once at the top of the reply, insideactin adrive.
Related tools
The contract your client receives
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.