SCRYMAMEReferenceSequencesperform_exportAlso in DOSBox-X

MAMESequences

perform_export

Write the session's calls since start as a script that replays them and checks their answers, with no model.

perform_export(dest, overwrite=false)

Try it

On Gridlee, a free ROM from mamedev.org, in a session that dropped two coins and read the credits.
Ask

Save what we did in this session as a script that replays and checks it without you.

Call
perform_export(dest="./tmp/demos/tour/two-coins.json")
Reply 6 of 10 fields
{
  "path": "./tmp/demos/tour/two-coins.json",
  "steps": 9,
  "checks": 3,
  "dropped_total": 14,
  "cut": {"available": false, "why": "the recording kept every call a replay takes"},
  "kept": "2 saved for `promote`; perform/two-coins, start/gridlee: not ... (185 characters)"
}

Nine calls replay, three of them as checks, and 14 calls were left out. cut is unavailable because nothing ended the script early; kept says the script is now a candidate for promote.

The whole reply
JSON
{
  "summary": "perform_export: 9 steps, 3 checks, 14 dropped to ./tmp/demos/tour/two-coins.json",
  "status": "ok",
  "path": "./tmp/demos/tour/two-coins.json",
  "steps": 9,
  "checks": 3,
  "dropped": [
    {"call": 1, "op": "status", "why": "a read the export does not check"},
    {"call": 2, "op": "machine_map", "why": "it changes nothing in the emulated machine"},
    {"call": 3, "op": "cpu_info", "why": "a read the export does not check"},
    {"call": 4, "op": "symbols_find", "why": "a read the export does not check"},
    {"call": 6, "op": "disassemble", "why": "a read the export does not check"},
    {"call": 7, "op": "find", "why": "a read the export does not check"},
    "... 8 more"
  ],
  "dropped_total": 14,
  "cut": {"available": false, "why": "the recording kept every call a replay takes"},
  "replay": "uv run python -m scry_core.replay ./tmp/demos/tour/two-coins.json",
  "kept": "2 saved for `promote`; perform/two-coins, start/gridlee: nothing this session read names its repository: promote(dry_run=true, root=<the repository>) lists what an approval would create"
}

Arguments

dest string, required
The .json file to write, required: absolute, or starting with ~. Refused when it exists, unless overwrite.
overwrite boolean, default false
true replaces a dest that is already there. Left out, an existing file is refused.

What comes back

steps
How many calls the script replays; path is the file written.
checks
How many of them compare a reading with its recorded values, the answer the session got.
dropped
The last 40 calls left out (reads the script does not check, refused calls, calls that change nothing), each with its call, op and why; dropped_total counts all.
cut
The call the script ends before, with its call, op and why. It is available: false when every call a replay can run was kept.
replay
The command that replays the script, run from this server's repository. It exits 0 when every step gave its recorded values again.
kept
Says the script was saved as a candidate for promote: it reads "N saved for promote", and names a repository that has no .scry/ folder yet.
All 8 reply fields
  • checks (integer)
  • cut (object)
  • dropped (array)
  • dropped_total (integer)
  • path (string)
  • replay (string)
  • steps (integer)
  • kept (string)

What it refuses

Why it works this way

The script keeps the calls that move the program and a few readings as checks, each with the answer it got as recorded. A call that left the program at a new stop is checked on that stop's pc and frame.

The script ends at the first call no replay can reach. A resume, or a run that the clock or a stop ended, stops the cpu at a point inside its frame that no replayed run reaches. Every later stop would inherit the shift.

So move with run_for, run_to and step, which stop at the same point on every run, and keep resume for the end. Leave the dest of a step that writes a file empty: a file the session named is still there on replay, and the step is refused.

More on why

When the frames are known, cut says how many the run took, and a run_for of that many replays it up to that frame's start. The script also ends at a call with no reply, a refusal after the program moved, and a program found elsewhere than the call before left it.

A debug line is replayed and its printed answer never checked; one that moved the program is checked on its stop. An image_compare(method="golden") over files that dropped calls wrote is dropped too.

A reader that steps the program to read is kept as a step. How far a Lua reader steps follows the host's clock, so on a rare run it lands elsewhere and the replay says so at that step.

The script carries start's arguments as given, host paths included; the replay's --binary and --rompath replace them. needs.states lists the saved states it loads and does not save, checked before anything plays. needs.declarations lists the breakpoints, watches and registerpoints saved when the recorded start began, which a replay must find again.

The contract your client receives
Text
Write the session's calls since `start` to `dest` as a `perform` document.

Kept: moving calls and checks (`read_memory`, `read_block`, `registers`,
`screen_signature`, `screen_map_find`, `image_compare(method="golden")`), each held to its
`recorded` reply. Other calls drop; the first no replay can place, or past 5000, cuts
the rest.

`dest` (`.json`) is refused if present unless `overwrite`. Reply: `path`, `steps`,
`checks`, `dropped`, `dropped_total`, `cut`, `replay`, and `kept` when the document is kept
for `promote`; `no_recording` if empty.

Reference: REFERENCE.md, From a session to a test that replays itself.
Tools