# Testing And Evidence

This page documents current checks, emulator tests, probe modes, acceptance
targets, and result paths. Source of truth: `Makefile`, `tools/run_*.py`,
`tools/inspect_mutineer_atr.py`, and `tools/mms_abi_check.py`.

## Fast Static Checks

```sh
make mutineer-basic
make mms-com-hatabs
make mms-abi-check
make mutineer-atr-inspect-current
make docs-audit
```

`make mms-abi-check` assembles MMS variants and verifies:

- jump table offsets used by BASIC;
- public block and handoff offsets;
- HATABS labels needed by the handler manager;
- resident end address against the BASIC-safe ceiling;
- source-level semantic checks for guarded HATABS behavior.

`make mutineer-atr-inspect-current` checks the current versioned ATR contents
and writes `build/mutineer-atr-manifest.json`.

## MMS HATABS Probes

Core probe targets:

- `make mms-hatabs-probe-api`
- `make mms-hatabs-probe-mixed`
- `make mms-hatabs-probe-input`
- `make mms-hatabs-probe-sysop`
- `make mms-hatabs-probe`

Experimental D: probe targets:

- `make mms-hatabs-probe-donly`
- `make mms-hatabs-probe-dmodem`
- `make mms-hatabs-probe-dstep`
- `make mms-hatabs-probe-full`
- `make mms-hatabs-probe-d`
- `make mms-hatabs-probe-all`

The core probe set is the production HATABS acceptance surface. D: wrapping is
guarded and should be treated as experimental unless its dedicated probes pass.

Probe result directories:

```text
results/mms-hatabs-probe/<mode>/<timestamp>/
```

Common files:

- `result.json`: status, markers, paths, mode, port.
- `transcript.bin` and `transcript.txt`: captured host output.
- `emulator.log`: launcher/test log.
- `altirra-debug.log`: present when debug logging is enabled.
- `Altirra-850-hatabs-probe.ini`: generated profile.

## Telnet Acceptance

Targets:

- `make mutineer-telnet-test`
- `make mutineer-telnet-test-hatabs`
- `make mutineer-disconnect-test`

The telnet test launches Altirra, waits for the BBS, connects to the configured
modem port, registers/logs in, navigates menus, exercises core commands,
reconnects where required, and writes coverage evidence.

Important env vars:

- `MUTINEER_ATR`
- `MUTINEER_MODEM_PORT`
- `MUTINEER_TEST_TIMEOUT`
- `MUTINEER_CONNECT_DELAY`
- `MUTINEER_SEND_DELAY`
- `MUTINEER_TEST_SCENARIO`
- `MUTINEER_LINE_ENDING`
- `MUTINEER_CLIENT`
- `MUTINEER_EXTRA_DISK`
- `MUTINEER_ALTIRRA_DEBUG`

Result directory:

```text
results/mutineer-telnet/<timestamp>/
```

## XMODEM Acceptance

Targets:

- `make mutineer-xmodem-test`
- `make mutineer-xmodem-test-hatabs`

The XMODEM test launches the BBS through Altirra, logs in, enters file transfer
flows, and verifies scripted upload/download behavior.

Important env vars:

- `MUTINEER_ATR`
- `MUTINEER_MODEM_PORT`
- `MUTINEER_XMODEM_TIMEOUT`
- `MUTINEER_CONNECT_DELAY`
- `MUTINEER_ALTIRRA_DEBUG`

Result directory:

```text
results/mutineer-xmodem/<timestamp>/
```

## Regression And Evidence

`make mutineer-regression-test` checks normalized transcript markers from the
latest telnet run unless `--run-dir` is supplied directly to
`tools/run_mutineer_regression_test.py`.

`make mutineer-evidence` runs ABI check, ATR build, ATR inspection, telnet,
XMODEM, regression, and evidence collection. Combined evidence is written to:

```text
results/mutineer-evidence.json
```

## Acceptance Targets

`make acceptance` runs:

```text
mms-hatabs-probe
mutineer-evidence
```

`make acceptance-hatabs` runs:

```text
mms-abi-check
mms-hatabs-probe
mutineer-atr
mutineer-atr-inspect-hatabs
mutineer-telnet-test-hatabs
mutineer-xmodem-test-hatabs
```

Full emulator acceptance is slow because it boots Altirra and waits for modem
connect windows. For docs-only edits, `make docs-audit` and static checks are
sufficient unless examples or scripts were changed.

## Debugging Test Runs

Use these before rerunning if Wine or Altirra is stale:

```sh
pkill -f Altirra || true
pkill -f wineserver || true
wineserver -k || true
ss -ltnp | grep 6507 || true
```

Enable Altirra debug output with:

```sh
MUTINEER_ALTIRRA_DEBUG=1 make mutineer-telnet-test
```