SCRYDOSBox-XReferenceSequencesperform_exportAlso in MAME
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
Save what we did in this session as a script that replays and checks it without you.
perform_export(dest="./tmp/demos/tour/files/session.json"){
"path": "./tmp/demos/tour/files/session.json",
"steps": 15,
"checks": 4,
"dropped_total": 13,
"cut": {"available": false, "why": "the recording kept every call a replay takes"},
"kept": "2 saved for `promote`"
}Fifteen calls replay, four of them as checks, and 13 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
{
"summary": "perform_export: 15 steps, 4 checks, 13 dropped to ./tmp/demos/tour/files/session.json",
"status": "ok",
"path": "./tmp/demos/tour/files/session.json",
"steps": 15,
"checks": 4,
"dropped": [
{"call": 1, "op": "status", "why": "a read the export does not check"},
{"call": 5, "op": "machine_map", "why": "it changes nothing in the emulated machine"},
{"call": 7, "op": "symbols_find", "why": "a read the export does not check"},
{"call": 8, "op": "interrupt_vectors", "why": "it changes nothing in the emulated machine"},
{"call": 9, "op": "screen_view", "why": "it changes nothing in the emulated machine"},
{"call": 10, "op": "palette", "why": "it changes nothing in the emulated machine"},
"... 7 more"
],
"dropped_total": 13,
"cut": {"available": false, "why": "the recording kept every call a replay takes"},
"replay": "uv run python -m scry_core.replay ./tmp/demos/tour/files/session.json",
"kept": "2 saved for `promote`"
}Arguments
- dest string, required
- The
.jsonfile to write: absolute, or starting with~. Refused when it exists, unlessoverwrite. - overwrite boolean, default
false truereplaces adestthat is already there. Left out, an existing file is refused.
What comes back
- steps
- How many calls the script replays;
pathis the file written. - checks
- How many of them compare a reading with its
recordedvalues, 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,opandwhy;dropped_totalcounts all. - cut
- The call the script ends before, with its
call,opandwhy. It isavailable: falsewhen 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
recordedvalues again. - kept
- Says the script was saved as a candidate for
promote: it reads "N saved forpromote", 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
- A
destthat does not end in.json, is a directory, or exists withoutoverwrite(bad_argument). - No
startthat succeeded, one that was cancelled, or no call left that a replay could run (no_recording).
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 regs 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 screen_wait that found its text becomes a run_for of as many frames as it polled, which a replay reaches. A send_keys or send_mouse to a stopped program is kept as a step: it runs frame by frame to a stop a replay reaches.
- A
debugcommand the script keeps is never checked against its answer, and astate_write(method="load")is checked against nothing either. - The file names what a replay needs:
needs.states, the saved states it loads and does not save itself. - And
needs.declarations: the breakpoints and watches saved when the recordedstartbegan, so a replay under others says so before it plays.
Related tools
The contract your client receives
Write the session's calls since `start` to `dest` as a `perform` document.
Kept: moving calls and checks (`read_memory`, `registers`, `screen_signature`,
`screen_map_find`, `guest_file`, `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.