SCRYDOSBox-XReferenceSequencesdriveAlso in MAME
drive
Send an input as a list of steps, then check the program reacted by waiting for a new line in the log.
drive(act, expect="", seconds=null, pattern=".", limit=40, settle_seconds=30.0, summaries=false)
Try it
logfile.Press M and check the game handed the paddle to the mouse: wait for its MOUSE ON line.
drive(act=[{"op": "send_keys", "keys": ["m"]}], expect="MOUSE ON$", seconds=10){
"summary": "drive: reaction seen",
"status": "ok"
}The summary says a new log line matched expect after the key went in. The line itself is under verify in the whole reply, with the lines looked kept.
The whole reply
{
"summary": "drive: reaction seen",
"status": "ok",
"act": {
"ran": [
{
"op": "send_keys",
"reply": {
"summary": "send_keys (guest): sent, reaction not checked",
"status": "ok",
"keys": ["m"],
"modifiers": [],
"route": "guest",
"posted": 1,
"bytes": 2,
"frames": 2,
"verify": {
"checked": false,
"why": "no `expect` was given, so the reply says what went into the guest and NOT that the program took it; pass expect=<E9 pattern> to confirm its reaction"
},
"session": {"alive": true, "running": true, "altered": true}
}
}
],
"steps_completed": 1,
"failed_at": {"available": false, "why": "no step failed"},
"still_running": true,
"note": "the act ended with the machine running; `drive`'s wait for `expect` is the wait",
"held": 0
},
"verify": {
"checked": true,
"seen": true,
"expected": "MOUSE ON$",
"verdict": "TARGET",
"line": "Bochs port E9h: MOUSE ON",
"seen_before_waiting": "<volatile>",
"lines_before": "<volatile>",
"waited_s": "<volatile>",
"lines_total": "<volatile>"
},
"looked": {
"guest": {
"available": true,
"since_mark": "<volatile>",
"lines_written": "<volatile>",
"lines_total": "<volatile>",
"truncated": false,
"lines": ["Bochs port E9h: MOUSE ON"],
"pattern": "."
}
}
}Arguments
- act array of object, required
- The steps to run, in the shape
performtakes:{"op": <tool>, ...}. Required, and never empty. - expect string, default
"" - A regular expression: the log line that shows the program reacted, waited for after the steps. Left out, nothing is checked and
verifysayschecked: false. - seconds number (> 0, <= 600.0), optional
- How long to wait for the
expectline. Left out, 5 seconds; given withoutexpect, the call is refused. - pattern string, default
"." - A regular expression that picks which new log lines
lookedshows. It changes nothing in the check; left out, every line. - limit integer (>= 1, <= 400), default
40 - How many of those lines
lookedshows, the newest: 1 to 400. Left out, 40. - settle_seconds number (>= 0, <= 600.0), default
30.0 - As in
perform. Withexpect, the last step's stop is not waited for: waiting for the line is the wait. - summaries boolean, default
false - As in
perform:truecuts each step's reply but the last to a short row.
What comes back
- act
- What the steps did, in the fields of a
performreply:ran,steps_completed,failed_atand the rest. - verify
- The check:
checkedsays whether one ran andseenwhether the line came, with theline, theverdict(TARGETorTIMEOUT) andwaited_s. - looked
- Under
guest, the newestlinesthe program wrote since the steps began that matchpattern, withlines_totalandtruncated.
All 4 reply fields
act(object)looked(object)operations(array)verify(object)
What it refuses
secondswithoutexpect, or an emptyact(bad_argument).- A bad step or argument in
act, before anything runs;operationslists the tools a step may name (bad_argument). - A session started without a
logfile, which leaves no log to read (no_channel). - A step that answers INVALID (
step_failed). - The program stopped at the debugger without the line: a stopped program writes nothing more. The reply adds
last_stop(wait_stopped). - A refusal of the steps themselves comes back with its own code, such as
not_stopped,session_brokenordiverged.
Why it works this way
The log is marked once, before the first step, so a line written before the input is never taken for a reaction.
The log is the program's own: the lines it writes to port E9, kept in the session's logfile. Steps that end with the program stopped get one read of it, not a wait; send_keys and send_mouse with expect do wait, frame by frame.
checked says a check ran and seen that the line came; neither is verified, which elsewhere means a value read back equal to the one sent. A still of the screen needs a recording and ffmpeg, so capture_frame takes it.
More on why
verify also carries expected, seen_before_waiting, lines_before and lines_total; on a TIMEOUT, arrived_during, lines_examined and a note; after a stop, stopped_during_wait and lines_on_disk. why explains checked: false; available: false means the steps ran out their own wait. looked.guest adds lines_written, since_mark and pattern.
Related tools
The contract your client receives
A sequence that also waits for a line of the E9 log; with no line to wait for, `perform`
is the call. Marks the E9 log, runs `act` (steps in `perform`'s
vocabulary, a step `{"op": <tool>, ...arguments}`), then with `expect` waits up to
`seconds` (default 5, at most 600) for a new matching line. Needs a
`logfile`.
`pattern` and `limit` only filter the lines shown; `settle_seconds` is the call's, as in
`perform`. Refused: `seconds` without `expect`.
Reply: `act` (`ran`, `steps_completed`, `failed_at`), `verify` (`verdict` `TARGET` or
`TIMEOUT`, `seen`, `line`; `checked: false`), `looked.guest` (`lines`, `truncated`).
INVALID with the same fields on `step_failed`, `wait_stopped`, or the act's own refusal.
No screen: use `capture_frame`.
Reference: REFERENCE.md, Input and the screen.
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.