conformance/README.md at 7c83b415d7cc · doomsdayone/retro-remote-debug-controller

# 7c83b415d7cc retro-remote-debug-controller / conformance / README.md

1.7 KiB · Markdown · last changed Add conformance suite; client: raw PPM screenshot + PPM parser 3 months ago rendered source blame history raw

# Conformance suite

pytest tests that assert an emulator correctly implements the control contract
(`../SPEC.md`, 0.1.x). Point them at any emulator — the reference x16emu, FAB,
the Neo6502 — and they check the same surface. Platform-agnostic: framebuffer
dimensions come from the PPM header, addresses use `$0000`, and `bank` is
exercised without requiring the platform to have banking.

## Run

Attach to an already-running emulator:

```
RRDC_PORT=8080 pytest -v
```

Or let the suite launch one (`{port}` is substituted into the command):

```
RRDC_EMU_CMD="SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy \
    /path/to/x16emu -rom rom.bin -warp -controlport {port}" \
RRDC_PORT=8391 pytest -v
```

If nothing is listening and no `RRDC_EMU_CMD` is set, the tests **skip** (a bare
`pytest` in CI without an emulator is a skip, not a failure).

## What it checks

- `/status` — required keys present, contract MAJOR matches, sane types.
- `/regs` — a non-empty JSON object of integer registers.
- `/mem` — returns exactly `len` bytes; honours `bank`.
- `/screenshot` — a well-formed PPM whose body size matches its dimensions.
- `/step` — deterministic: equal steps advance the frame counter by equal,
  positive amounts, and `/step` returns the halted counter.
- `/pause` + `/resume` — toggle the paused state.
- Errors — unknown path → 404; `GET /step` → 405.

## Environment

| Var | Default | Meaning |
|---|---|---|
| `RRDC_PORT` | `8080` | control port to attach to / launch on |
| `RRDC_EMU_CMD` | — | shell command to launch an emulator (`{port}` substituted) |
| `RRDC_BOOT_TIMEOUT` | `20` | seconds to wait for `/status` |

Requires `pytest`. Nothing else — the client is stdlib-only (Pillow is optional
and unused here).

`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet

1	# Conformance suite
2
3	pytest tests that assert an emulator correctly implements the control contract
4	(`../SPEC.md`, 0.1.x). Point them at any emulator — the reference x16emu, FAB,
5	the Neo6502 — and they check the same surface. Platform-agnostic: framebuffer
6	dimensions come from the PPM header, addresses use `$0000`, and `bank` is
7	exercised without requiring the platform to have banking.
8
9	## Run
10
11	Attach to an already-running emulator:
12
13	```
14	RRDC_PORT=8080 pytest -v
15	```
16
17	Or let the suite launch one (`{port}` is substituted into the command):
18
19	```
20	RRDC_EMU_CMD="SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy \
21	/path/to/x16emu -rom rom.bin -warp -controlport {port}" \
22	RRDC_PORT=8391 pytest -v
23	```
24
25	If nothing is listening and no `RRDC_EMU_CMD` is set, the tests skip (a bare
26	`pytest` in CI without an emulator is a skip, not a failure).
27
28	## What it checks
29
30	- `/status` — required keys present, contract MAJOR matches, sane types.
31	- `/regs` — a non-empty JSON object of integer registers.
32	- `/mem` — returns exactly `len` bytes; honours `bank`.
33	- `/screenshot` — a well-formed PPM whose body size matches its dimensions.
34	- `/step` — deterministic: equal steps advance the frame counter by equal,
35	positive amounts, and `/step` returns the halted counter.
36	- `/pause` + `/resume` — toggle the paused state.
37	- Errors — unknown path → 404; `GET /step` → 405.
38
39	## Environment
40
41	\| Var \| Default \| Meaning \|
42	\|---\|---\|---\|
43	\| `RRDC_PORT` \| `8080` \| control port to attach to / launch on \|
44	\| `RRDC_EMU_CMD` \| — \| shell command to launch an emulator (`{port}` substituted) \|
45	\| `RRDC_BOOT_TIMEOUT` \| `20` \| seconds to wait for `/status` \|
46
47	Requires `pytest`. Nothing else — the client is stdlib-only (Pillow is optional
48	and unused here).

Keyboard