SCRYDOSBox-XReferenceSequencesdriveAlso in MAME

DOSBox-XSequences

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

On Bricks, the game this repository builds, while it runs, in a session started with a logfile.
Ask

Press M and check the game handed the paddle to the mouse: wait for its MOUSE ON line.

Call
drive(act=[{"op": "send_keys", "keys": ["m"]}], expect="MOUSE ON$", seconds=10)
Reply 2 of 5 fields
{
  "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
JSON
{
  "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 perform takes: {"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 verify says checked: false.
seconds number (> 0, <= 600.0), optional
How long to wait for the expect line. Left out, 5 seconds; given without expect, the call is refused.
pattern string, default "."
A regular expression that picks which new log lines looked shows. It changes nothing in the check; left out, every line.
limit integer (>= 1, <= 400), default 40
How many of those lines looked shows, the newest: 1 to 400. Left out, 40.
settle_seconds number (>= 0, <= 600.0), default 30.0
As in perform. With expect, the last step's stop is not waited for: waiting for the line is the wait.
summaries boolean, default false
As in perform: true cuts each step's reply but the last to a short row.

What comes back

act
What the steps did, in the fields of a perform reply: ran, steps_completed, failed_at and the rest.
verify
The check: checked says whether one ran and seen whether the line came, with the line, the verdict (TARGET or TIMEOUT) and waited_s.
looked
Under guest, the newest lines the program wrote since the steps began that match pattern, with lines_total and truncated.
All 4 reply fields
  • act (object)
  • looked (object)
  • operations (array)
  • verify (object)

What it refuses

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.

The contract your client receives
Text
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.
Tools