testaferro 0.1.0.dev0__tar.gz

testaferro-0.1.0.dev0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Paul Galbraith
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

testaferro-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: testaferro
+Version: 0.1.0.dev0
+Summary: pytest facade for DOS-based CppUTest unit testing, run via QEMU
+Author-email: Paul Galbraith <paul@galbraiths.ca>
+License-Expression: BSD-3-Clause
+Keywords: pytest,cpputest,qemu,dos,testing,guest
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pytest
+Requires-Dist: reliquary==0.1.0.dev2
+Dynamic: license-file
+
+# testaferro
+
+testaferro is a pytest facade for DOS-based CppUTest unit testing: a CppUTest suite built for DOS runs inside a QEMU
+guest via reliquary, and its tests surface as pytest tests on the host — running, selecting, and
+reporting them feels like an ordinary local pytest run.
+
+DOS and CppUTest are what it supports today. Reliquary owns the guest-machine side; testaferro owns the pytest facade and
+its test-framework adapters. Other platforms and frameworks are not built; what has been argued for them, and what the
+project has decided so far, is in [planning/](planning/).
+
+## Status: alpha
+
+The architecture is built and works for its first target pair: a DOS-built CppUTest suite run inside a QEMU guest,
+surfacing as ordinary pytest items on the host. It was verified end to end before the move onto reliquary's blueprint
+model; since that move the unit suite passes but no guest has actually run, so treat a first run here as unproven
+ground and expect to report what you find. testaferro is pre-1.0 and makes no compatibility promise: interfaces change
+coherently and completely, without a bridge for the old shape.
+
+## Usage
+
+Hand the facade a reference to the suite executable in a normal pytest test module:
+
+```python
+from pathlib import Path
+
+import testaferro
+
+test_guest_case = testaferro.guest_suite(Path(__file__).parent / "TESTS.EXE")
+```
+
+testaferro interrogates the referenced file and selects the matching guest backend: a DOS executable runs inside a
+QEMU guest through reliquary (a dependency of testaferro), while a provably non-DOS binary — say, the host
+build of the suite passed by mistake — is rejected with a clear error before any guest boots, naming the format and
+architecture it found (Windows PE, Linux/BSD ELF, macOS Mach-O, 16-bit NE/LX/LE; x86 through ARM64). Headerless
+images (`.com`-style raw code) carry nothing to prove, so they pass through for the guest itself to judge. The framework adapter
+defaults to `testaferro.cpputest`; pass `framework=` to use a different one.
+
+The guest machine's working state is testaferro's business, not the consumer's: each run happens in a fresh, disposable
+reliquary home under testaferro's cache (`%LOCALAPPDATA%\testaferro` on Windows, `$XDG_CACHE_HOME/testaferro`
+elsewhere), and the machine is created there fresh for the session and swept away with it. Zero configuration boots a
+FreeDOS image that is downloaded once and cached; pass `boot_image=` to boot a caller-supplied DOS floppy image
+instead.
+
+The suite executable reaches the guest on a work drive testaferro adds to the machine: a host directory served into the
+guest as a FAT volume, with the executable staged into it before boot. The guest sees it as its first hard disk —
+normally `C:` — and testaferro runs it there by name. Nothing is written into your boot image.
+
+### Named test machines
+
+Declare a named machine once when several suites share it. A declaration is a reliquary **blueprint** — the machine's
+own description, in reliquary's vocabulary. `config()` accepts blueprint machine fields directly (`memory`, `drives`,
+`boot`, `backend_settings`, …), or a complete `machine_config=` template: a `MachineSpec`, a mapping, a whole blueprint
+document, or a path to a `.rlqb` file. The template supplies its platform when it declares one; `platform=` is optional
+and verifies an explicit choice.
+
+```python
+import testaferro
+
+testaferro.config("msdos", boot_image="images/msdos.img", memory=32)
+
+test_guest_case = testaferro.guest_suite(
+    "build/TESTS.EXE", machine="msdos")
+```
+
+The same declarations can live in an optional per-project `testaferro.ini` — one section per machine, the
+declarative twin of `config()`. `guest_suite()` searches upward from the calling test module and loads the file
+automatically, so the suite can name only the executable when a unique machine matches:
+
+```ini
+[msdos]
+boot_image = images/msdos.img
+memory = 32
+
+[custom]
+machine_config = machines/custom.rlqb
+```
+
+```python
+test_guest_case = testaferro.guest_suite("build/TESTS.EXE")
+```
+
+Relative `boot_image` / `machine_config` / `template` paths resolve from the ini file's directory. Structured blueprint
+fields (`drives`, `boot`, `scripts`, `backend_settings`, `control_planes`, `parameters`) accept JSON values; a bare
+integer stays an integer, so `memory = 32` and `memory = 32M` are both accepted. Call `testaferro.load_config(path)` to
+load an explicit file, or `load_config()` to search upward from the current directory.
+
+A declaration is a template, never a running machine: every backend session creates a fresh machine from it, so runs do
+not share guest state. What that costs per session is the blueprint's own business — reliquary's `materialize` mode on
+each drive decides whether media is attached in place, copied, or layered. Use `platform="dos"` or `machine="msdos"`
+when more than one configured DOS machine would otherwise match. With no declarations, DOS executables retain the
+implicit downloaded-FreeDOS machine.
+
+With several guest suites — or parallel pytest processes — open a *session*, so the image choice is made once and
+every run's state is swept together. From the consuming project's `conftest.py`:
+
+```python
+import testaferro
+
+testaferro.start()                  # or testaferro.start(boot_image=...)
+
+def pytest_unconfigure(config):
+    testaferro.stop()
+```
+
+`start()` costs nothing until a guest actually runs; `stop()` sweeps the session's staged image and every run home,
+keeping the once-downloaded FreeDOS image cached for the next session (`stop(clear_downloads=True)` scrubs that too).
+Forgetting `stop()` is not fatal — `start()` registers an `atexit` failsafe that sweeps the session at interpreter
+exit — but the explicit call is still preferred: it cleans up at a deterministic point and is where
+`clear_downloads=True` can be said.
+
+Because every run gets a private home and a private image copy, suites in separate pytest processes never share
+mutable guest state — safe to parallelize. With [pytest-xdist](https://pypi.org/project/pytest-xdist/), run
+`pytest -n auto --dist loadfile`: `loadfile` keeps each test file's items on one worker, so a whole guest suite stays
+together (preserving the one-boot `run_all()` batching) while *different* suites boot their guests concurrently on
+other workers. Plain `--dist load` would scatter a suite's items across workers and degrade it to one boot per test.
+
+Backend lifecycle hooks are automatic. Enumeration runs in a short collection session; selected tests then share one
+execution session, which is cleaned up by pytest even when a test fails.
+
+Every test in the guest suite becomes its own pytest item, so pytest's selection drives what actually runs remotely:
+
+- run everything (`pytest`) and the facade batches the whole suite into a single guest run — one execution boot for the
+  session;
+- narrow the selection (`pytest -k Wraps`, an explicit node id) and only the selected tests run in the guest,
+  individually.
+
+A failing guest test fails its pytest item with the guest side's original file, line, and assertion message — not a
+traceback into the facade. IDE test integrations work per item too: the generated test function reports the
+`guest_suite()` call site as its source, so run-this-test and jump-to-source in PyCharm-style test trees resolve to
+your module.
+
+Under the hood, reliquary owns the guest machine and a framework adapter knows the suite's argv and output grammar.
+`testaferro.suite.SuiteBackend` composes reliquary execution with the selected adapter; `guest_suite()` also accepts a
+prebuilt backend as the custom escape hatch.
+
+Enumeration can be delegated to a host-built twin of a guest suite through `enumerator=`, and for a suite of any size
+it should be. Guest output is captured by reading the guest's screen, so a command whose output scrolls past one
+screenful leaves only its tail there — which bites enumeration hardest, since `-ln` lists every test at once. A host
+twin built from the same sources both avoids that and keeps the two builds honest against each other: a test the guest
+build dropped shows up as one that did not run.
+
+The framework adapter remains usable directly where the facade is more than you need — it is just argv and grammar,
+independent of how you obtained the output:
+
+```python
+from testaferro import cpputest
+
+results = cpputest.parse(log)  # {"ran", "failed", "summary"}
+```
+
+## Tests
+
+```powershell
+python -m unittest discover -s tests -v
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the required checks, and contribution licensing terms.
+
+## License
+
+BSD 3-Clause; see [LICENSE](LICENSE). The project follows REUSE conventions (SPDX headers
+plus [REUSE.toml](REUSE.toml)).

testaferro-0.1.0.dev0/README.md

@@ -0,0 +1,164 @@
+# testaferro
+
+testaferro is a pytest facade for DOS-based CppUTest unit testing: a CppUTest suite built for DOS runs inside a QEMU
+guest via reliquary, and its tests surface as pytest tests on the host — running, selecting, and
+reporting them feels like an ordinary local pytest run.
+
+DOS and CppUTest are what it supports today. Reliquary owns the guest-machine side; testaferro owns the pytest facade and
+its test-framework adapters. Other platforms and frameworks are not built; what has been argued for them, and what the
+project has decided so far, is in [planning/](planning/).
+
+## Status: alpha
+
+The architecture is built and works for its first target pair: a DOS-built CppUTest suite run inside a QEMU guest,
+surfacing as ordinary pytest items on the host. It was verified end to end before the move onto reliquary's blueprint
+model; since that move the unit suite passes but no guest has actually run, so treat a first run here as unproven
+ground and expect to report what you find. testaferro is pre-1.0 and makes no compatibility promise: interfaces change
+coherently and completely, without a bridge for the old shape.
+
+## Usage
+
+Hand the facade a reference to the suite executable in a normal pytest test module:
+
+```python
+from pathlib import Path
+
+import testaferro
+
+test_guest_case = testaferro.guest_suite(Path(__file__).parent / "TESTS.EXE")
+```
+
+testaferro interrogates the referenced file and selects the matching guest backend: a DOS executable runs inside a
+QEMU guest through reliquary (a dependency of testaferro), while a provably non-DOS binary — say, the host
+build of the suite passed by mistake — is rejected with a clear error before any guest boots, naming the format and
+architecture it found (Windows PE, Linux/BSD ELF, macOS Mach-O, 16-bit NE/LX/LE; x86 through ARM64). Headerless
+images (`.com`-style raw code) carry nothing to prove, so they pass through for the guest itself to judge. The framework adapter
+defaults to `testaferro.cpputest`; pass `framework=` to use a different one.
+
+The guest machine's working state is testaferro's business, not the consumer's: each run happens in a fresh, disposable
+reliquary home under testaferro's cache (`%LOCALAPPDATA%\testaferro` on Windows, `$XDG_CACHE_HOME/testaferro`
+elsewhere), and the machine is created there fresh for the session and swept away with it. Zero configuration boots a
+FreeDOS image that is downloaded once and cached; pass `boot_image=` to boot a caller-supplied DOS floppy image
+instead.
+
+The suite executable reaches the guest on a work drive testaferro adds to the machine: a host directory served into the
+guest as a FAT volume, with the executable staged into it before boot. The guest sees it as its first hard disk —
+normally `C:` — and testaferro runs it there by name. Nothing is written into your boot image.
+
+### Named test machines
+
+Declare a named machine once when several suites share it. A declaration is a reliquary **blueprint** — the machine's
+own description, in reliquary's vocabulary. `config()` accepts blueprint machine fields directly (`memory`, `drives`,
+`boot`, `backend_settings`, …), or a complete `machine_config=` template: a `MachineSpec`, a mapping, a whole blueprint
+document, or a path to a `.rlqb` file. The template supplies its platform when it declares one; `platform=` is optional
+and verifies an explicit choice.
+
+```python
+import testaferro
+
+testaferro.config("msdos", boot_image="images/msdos.img", memory=32)
+
+test_guest_case = testaferro.guest_suite(
+    "build/TESTS.EXE", machine="msdos")
+```
+
+The same declarations can live in an optional per-project `testaferro.ini` — one section per machine, the
+declarative twin of `config()`. `guest_suite()` searches upward from the calling test module and loads the file
+automatically, so the suite can name only the executable when a unique machine matches:
+
+```ini
+[msdos]
+boot_image = images/msdos.img
+memory = 32
+
+[custom]
+machine_config = machines/custom.rlqb
+```
+
+```python
+test_guest_case = testaferro.guest_suite("build/TESTS.EXE")
+```
+
+Relative `boot_image` / `machine_config` / `template` paths resolve from the ini file's directory. Structured blueprint
+fields (`drives`, `boot`, `scripts`, `backend_settings`, `control_planes`, `parameters`) accept JSON values; a bare
+integer stays an integer, so `memory = 32` and `memory = 32M` are both accepted. Call `testaferro.load_config(path)` to
+load an explicit file, or `load_config()` to search upward from the current directory.
+
+A declaration is a template, never a running machine: every backend session creates a fresh machine from it, so runs do
+not share guest state. What that costs per session is the blueprint's own business — reliquary's `materialize` mode on
+each drive decides whether media is attached in place, copied, or layered. Use `platform="dos"` or `machine="msdos"`
+when more than one configured DOS machine would otherwise match. With no declarations, DOS executables retain the
+implicit downloaded-FreeDOS machine.
+
+With several guest suites — or parallel pytest processes — open a *session*, so the image choice is made once and
+every run's state is swept together. From the consuming project's `conftest.py`:
+
+```python
+import testaferro
+
+testaferro.start()                  # or testaferro.start(boot_image=...)
+
+def pytest_unconfigure(config):
+    testaferro.stop()
+```
+
+`start()` costs nothing until a guest actually runs; `stop()` sweeps the session's staged image and every run home,
+keeping the once-downloaded FreeDOS image cached for the next session (`stop(clear_downloads=True)` scrubs that too).
+Forgetting `stop()` is not fatal — `start()` registers an `atexit` failsafe that sweeps the session at interpreter
+exit — but the explicit call is still preferred: it cleans up at a deterministic point and is where
+`clear_downloads=True` can be said.
+
+Because every run gets a private home and a private image copy, suites in separate pytest processes never share
+mutable guest state — safe to parallelize. With [pytest-xdist](https://pypi.org/project/pytest-xdist/), run
+`pytest -n auto --dist loadfile`: `loadfile` keeps each test file's items on one worker, so a whole guest suite stays
+together (preserving the one-boot `run_all()` batching) while *different* suites boot their guests concurrently on
+other workers. Plain `--dist load` would scatter a suite's items across workers and degrade it to one boot per test.
+
+Backend lifecycle hooks are automatic. Enumeration runs in a short collection session; selected tests then share one
+execution session, which is cleaned up by pytest even when a test fails.
+
+Every test in the guest suite becomes its own pytest item, so pytest's selection drives what actually runs remotely:
+
+- run everything (`pytest`) and the facade batches the whole suite into a single guest run — one execution boot for the
+  session;
+- narrow the selection (`pytest -k Wraps`, an explicit node id) and only the selected tests run in the guest,
+  individually.
+
+A failing guest test fails its pytest item with the guest side's original file, line, and assertion message — not a
+traceback into the facade. IDE test integrations work per item too: the generated test function reports the
+`guest_suite()` call site as its source, so run-this-test and jump-to-source in PyCharm-style test trees resolve to
+your module.
+
+Under the hood, reliquary owns the guest machine and a framework adapter knows the suite's argv and output grammar.
+`testaferro.suite.SuiteBackend` composes reliquary execution with the selected adapter; `guest_suite()` also accepts a
+prebuilt backend as the custom escape hatch.
+
+Enumeration can be delegated to a host-built twin of a guest suite through `enumerator=`, and for a suite of any size
+it should be. Guest output is captured by reading the guest's screen, so a command whose output scrolls past one
+screenful leaves only its tail there — which bites enumeration hardest, since `-ln` lists every test at once. A host
+twin built from the same sources both avoids that and keeps the two builds honest against each other: a test the guest
+build dropped shows up as one that did not run.
+
+The framework adapter remains usable directly where the facade is more than you need — it is just argv and grammar,
+independent of how you obtained the output:
+
+```python
+from testaferro import cpputest
+
+results = cpputest.parse(log)  # {"ran", "failed", "summary"}
+```
+
+## Tests
+
+```powershell
+python -m unittest discover -s tests -v
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the required checks, and contribution licensing terms.
+
+## License
+
+BSD 3-Clause; see [LICENSE](LICENSE). The project follows REUSE conventions (SPDX headers
+plus [REUSE.toml](REUSE.toml)).

testaferro-0.1.0.dev0/pyproject.toml

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: 2026 Paul Galbraith
+# SPDX-License-Identifier: BSD-3-Clause
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "testaferro"
+version = "0.1.0.dev0"
+description = "pytest facade for DOS-based CppUTest unit testing, run via QEMU"
+readme = "README.md"
+authors = [{ name = "Paul Galbraith", email = "paul@galbraiths.ca" }]
+requires-python = ">=3.9"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+keywords = ["pytest", "cpputest", "qemu", "dos", "testing", "guest"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Testing",
+]
+# pytest is the facade's host surface (testaferro.facade). QemuSuiteBackend
+# requires reliquary, which is included as a dependency.
+dependencies = ["pytest", "reliquary==0.1.0.dev2"]
+
+[tool.setuptools]
+packages = ["testaferro"]

testaferro-0.1.0.dev0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

testaferro-0.1.0.dev0/testaferro/__init__.py

@@ -0,0 +1,83 @@
+# SPDX-FileCopyrightText: 2026 Paul Galbraith
+# SPDX-License-Identifier: BSD-3-Clause
+"""testaferro: a pytest facade for remote (e.g. QEMU-guest) unit
+tests.
+
+A suite compiled for and running on a remote target surfaces as
+ordinary pytest tests on the host. Hand guest_suite() a reference to
+the suite executable:
+
+    from pathlib import Path
+
+    import testaferro
+
+    test_guest_case = testaferro.guest_suite(
+        Path(__file__).parent / "SUITE.EXE")
+
+The executable is interrogated to select its platform (DOS programs
+run in a QEMU guest; anything else is rejected), the
+framework adapter defaults to testaferro.cpputest (`framework=`
+overrides), and the runner's working state lives in
+testaferro-managed disposable directories. Named test machines are
+declared with config() or an optional per-project testaferro.ini; a
+prebuilt Backend remains the custom escape hatch for callers that
+need a different execution mechanism.
+
+For many suites (and future parallel runs), open a session so the
+boot image is specified once and all per-run state is swept together
+— in pytest, from the consumer's conftest.py:
+
+    import testaferro
+
+    testaferro.start()              # or start(boot_image=...)
+
+    def pytest_unconfigure(config):
+        testaferro.stop()
+"""
+
+# eager: the facade's own imports are stdlib-only (pytest is loaded
+# lazily inside it). start/stop delegate lazily instead, because
+# importing testaferro.qemu pulls in reliquary.
+from .facade import guest_suite  # noqa: F401
+
+
+def config(machine, platform=None, **options):
+    """Declare a named reliquary test machine.
+
+    ``platform`` is optional when the supplied ``machine_config`` or
+    ``template`` declares it. Without a template, remaining options are
+    the blueprint's own machine fields. The declaration is reused
+    as a template; each guest session receives a fresh materialization.
+    The same declarations may be written in ``testaferro.ini`` (see
+    ``load_config``).
+    """
+    from .machines import configure
+    return configure(machine, platform=platform, **options)
+
+
+def load_config(path=None):
+    """Load named machines from a ``testaferro.ini``.
+
+    With ``path``, read that file. With ``path`` omitted, search
+    upward from the current directory. ``guest_suite()`` performs the
+    same search from its call site automatically.
+    """
+    from .machines import load_config as load
+    return load(path)
+
+
+def start(boot_image=None):
+    """Open a guest-test session: one boot-image choice (or the
+    downloaded default) serving every suite until stop(). Costs
+    nothing until a guest actually runs; an atexit failsafe sweeps
+    the session if stop() is never called."""
+    from . import qemu
+    qemu.start(boot_image=boot_image)
+
+
+def stop(clear_downloads=False):
+    """Close the session, sweeping its staged image and all per-run
+    state; safe without an active session. `clear_downloads=True`
+    also drops the cached default boot image."""
+    from . import qemu
+    qemu.stop(clear_downloads=clear_downloads)

testaferro-0.1.0.dev0/testaferro/backend.py

@@ -0,0 +1,65 @@
+# SPDX-FileCopyrightText: 2026 Paul Galbraith
+# SPDX-License-Identifier: BSD-3-Clause
+"""The Backend seam: what the pytest facade needs from any remote
+test target.
+
+Any target that can list its tests and run one or all of them plugs
+into the same facade, however it carries those operations out
+underneath. Session hooks default to no-ops because one-shot backends
+(e.g. a SuiteBackend whose runner boots per operation)
+have no session to manage.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TestId:
+    __test__ = False        # not a test case, despite the name
+
+    group: str
+    name: str
+
+    def __str__(self):
+        return f"{self.group}.{self.name}"
+
+
+@dataclass
+class TestOutcome:
+    __test__ = False        # not a test case, despite the name
+
+    group: str
+    name: str
+    passed: bool
+    file: str = ""
+    line: int = 0
+    message: str = ""
+
+
+class Backend(ABC):
+    def start_session(self):
+        """Boot or attach to the remote target. Ready to accept
+        list/run calls immediately after this returns."""
+
+    @abstractmethod
+    def list_tests(self) -> "list[TestId]":
+        ...
+
+    @abstractmethod
+    def run_test(self, group, name) -> TestOutcome:
+        """Run one test. Raises LookupError if the target did not
+        run it (e.g. host and target test lists diverged)."""
+
+    @abstractmethod
+    def run_all(self) -> "list[TestOutcome]":
+        """Used by the facade's batching logic when no host-side
+        filter is active - a single bulk operation is expected to be
+        cheaper than many individual run_test() calls, however the
+        backend chooses to implement that."""
+
+    def stop_session(self):
+        """Tear down cleanly. Must be safe to call after a failed or
+        partial start_session()."""

testaferro-0.1.0.dev0/testaferro/binfmt.py

@@ -0,0 +1,109 @@
+# SPDX-FileCopyrightText: 2026 Paul Galbraith
+# SPDX-License-Identifier: BSD-3-Clause
+"""Executable-format classification for platform dispatch.
+
+`classify()` reads an executable's header and reports which platform
+could run it, without importing any runner:
+
+- ``Format("dos", ...)`` — a plain MZ program, or a headerless image
+  (`.com`-style raw code carries nothing to prove, so it passes
+  through for the guest itself to judge);
+- ``Format(None, ...)`` — a provably unsupported binary: PE,
+  NE/LX/LE, ELF, Mach-O (including universal).
+
+`kind` always carries the human-readable format-and-architecture
+name ('a Windows x64 (PE)', 'an ELF x86-64 (Linux/BSD)', ...) for
+error messages, and a future platform extends the classification by
+claiming formats currently mapped to None. Stdlib-only: the facade's
+dispatch and each platform binding's own guard share it without
+pulling in a runner.
+"""
+
+from __future__ import annotations
+
+import collections
+
+Format = collections.namedtuple("Format", ["platform", "kind"])
+
+_DOS_MZ = Format("dos", "a DOS MZ")
+_HEADERLESS = Format("dos", "a headerless (.com-style)")
+
+# architecture names per format, keyed by each format's machine field
+_ELF_MACHINES = {0x03: "x86", 0x28: "ARM", 0x3E: "x86-64",
+                 0xB7: "ARM64", 0xF3: "RISC-V"}
+_PE_MACHINES = {0x014C: "x86", 0x01C0: "ARM", 0x01C4: "ARM",
+                0x8664: "x64", 0xAA64: "ARM64"}
+_MACHO_CPUTYPES = {7: "x86", 0x01000007: "x86-64",
+                   12: "ARM", 0x0100000C: "ARM64"}
+
+
+def _elf_format(header):
+    """Kind string for an ELF image (Linux and the BSDs; most carry
+    the generic System V OS/ABI byte, so no OS is claimed)."""
+    arch = None
+    if len(header) >= 0x14:
+        order = "little" if header[5] == 1 else "big"
+        arch = _ELF_MACHINES.get(
+            int.from_bytes(header[0x12:0x14], order))
+    return (f"an ELF {arch} (Linux/BSD)" if arch
+            else "an ELF (Linux/BSD)")
+
+
+def _macho_format(header):
+    """Kind string for a Mach-O image, or None when the magic is
+    really something else's."""
+    magic = header[:4]
+    if magic in (b"\xca\xfe\xba\xbe", b"\xca\xfe\xba\xbf"):
+        # a universal binary's big-endian arch count is tiny; a Java
+        # class file shares the magic but puts its version there
+        if (len(header) >= 8
+                and int.from_bytes(header[4:8], "big") < 0x40):
+            return "a macOS universal (Mach-O)"
+        return None
+    order = "big" if magic[:2] == b"\xfe\xed" else "little"
+    arch = (_MACHO_CPUTYPES.get(int.from_bytes(header[4:8], order))
+            if len(header) >= 8 else None)
+    return (f"a macOS {arch} (Mach-O)" if arch
+            else "a macOS (Mach-O)")
+
+
+def _mz_extension_format(found):
+    """The Format of the newer-format header an extended MZ file
+    points at through e_lfanew, or None when none is recognized
+    there. DOS runs none of these."""
+    if found.startswith(b"PE\0\0"):
+        arch = (_PE_MACHINES.get(int.from_bytes(found[4:6], "little"))
+                if len(found) >= 6 else None)
+        return Format(None, f"a Windows {arch} (PE)" if arch
+                      else "a Windows (PE)")
+    for signature, kind in ((b"NE", "a 16-bit Windows or OS/2 (NE)"),
+                            (b"LX", "an OS/2 (LX)"),
+                            (b"LE", "a linear (LE)")):
+        if found.startswith(signature):
+            return Format(None, kind)
+    return None
+
+
+def classify(exe_path):
+    """The Format of the referenced executable: which platform could
+    run it (`platform`) and its human-readable kind. Raises
+    FileNotFoundError for a missing file; attaches no meaning beyond
+    the header — a "dos" verdict means "nothing proves otherwise"."""
+    with open(exe_path, "rb") as f:
+        header = f.read(0x40)
+        if header[:4] == b"\x7fELF":
+            return Format(None, _elf_format(header))
+        if header[:4] in (b"\xfe\xed\xfa\xce", b"\xfe\xed\xfa\xcf",
+                          b"\xce\xfa\xed\xfe", b"\xcf\xfa\xed\xfe",
+                          b"\xca\xfe\xba\xbe", b"\xca\xfe\xba\xbf"):
+            kind = _macho_format(header)
+            return _HEADERLESS if kind is None else Format(None, kind)
+        if header[:2] != b"MZ":
+            return _HEADERLESS
+        if len(header) < 0x40:
+            return _DOS_MZ
+        if int.from_bytes(header[0x18:0x1A], "little") < 0x40:
+            return _DOS_MZ
+        f.seek(int.from_bytes(header[0x3C:0x40], "little"))
+        found = f.read(8)
+    return _mz_extension_format(found) or _DOS_MZ