gps-denied-onboard/e2e

Blackbox Test Harness (e2e/)

This directory is the public-boundary test harness for gps-denied-onboard. It is owned by the blackbox_tests cross-cutting entry in _docs/02_document/module-layout.md and implements task AZ-406 (Test Infrastructure Bootstrap) plus its downstream test-task siblings (AZ-407..AZ-446).

The harness runs in two execution tiers (environment.md § Two-tier execution profile):

• Tier-1 — workstation Docker. cd e2e/docker && docker compose -f docker-compose.test.yml up --build --abort-on-container-exit e2e-runner
• Tier-2 — Jetson Orin Nano Super hardware loop. ./e2e/jetson/run-tier2.sh --fc-adapter <ardupilot|inav> --vio-strategy <okvis2|klt_ransac>

Both tiers emit the same CSV report format (one row per test) per environment.md § Reporting.

Layout

e2e/
├── docker/        Tier-1 entrypoint (docker-compose.test.yml + Tier-2 bridge override + secrets mount)
├── jetson/        Tier-2 entrypoint (run-tier2.sh + systemd unit + tegrastats/jtop parsers)
├── runner/        e2e-runner image (Dockerfile, conftest, pytest plugins, helpers, requirements)
├── fixtures/      Fixture builders (tile-cache, age-injector, injectors/, mock-suite-sat, secrets, security)
├── tests/         Pytest target — `positive/`, `negative/`, `performance/`, `resilience/`, `security/`, `resource_limit/`
└── _unit_tests/   Out-of-container unit tests for the harness internals (run as part of the project test suite)

Public-Boundary Discipline (hard rule)

The e2e-runner image MUST NOT import any module from the SUT source tree (src/gps_denied_onboard/**). The only legal interaction surfaces are:

• MAVLink (ArduPilot SITL — UDP 14550)
• MSP2 (iNav SITL — TCP 5760)
• HTTP/JSON (mock-suite-sat-service — port 8080)
• Filesystem read of the FDR archive after a run (fdr-output volume)

This rule is enforced by:

1. The runner Dockerfile building from a base image that does NOT install the SUT package.
2. Layout discipline: no import gps_denied_onboard.* in any file under e2e/.
3. Compose e2e-net.internal: true — no external network egress (RESTRICT-SAT-1, NFT-SEC-02).

See _docs/02_document/tests/environment.md for the full per-service spec.

RUN_ID and report paths

Each invocation must set RUN_ID (defaults to local-${USER}-${EPOCH} in development; CI sets it from the workflow run id). Reports land at:

• e2e-results/run-${RUN_ID}/report.csv
• e2e-results/run-${RUN_ID}/evidence/ (per-run .tlog, FDR archives, screenshots, profiler traces, tegrastats CSV, jtop CSV)

The e2e-results/ directory is gitignored.

How to add a new blackbox scenario

1. Decompose the scenario into a task spec under _docs/02_tasks/todo/.
2. Implement the test under the appropriate e2e/tests/<category>/ folder.
3. The conftest's session-scoped (fc_adapter, vio_strategy) parameterization automatically applies — opt out with @pytest.mark.parametrize overrides.
4. Trace the scenario to the AC/RESTRICT IDs it exercises via the traces_to pytest marker — the CSV reporter emits this verbatim.

How to add a new fixture builder

Fixture builders live under e2e/fixtures/ and may be standalone Python modules (for runtime injectors) or Dockerized helpers (for tile-cache / mock-suite-sat). Each builder must:

• Be reproducible — given the same input, produce bit-identical output.
• Document its output volume / path in _docs/02_document/tests/test-data.md.
• Have a corresponding unit test under e2e/_unit_tests/fixtures/.

Out-of-container unit tests

The harness's internal Python — CSV reporter, helpers, parsers, mock app, conftest skip rules — is unit-tested under e2e/_unit_tests/. These tests do NOT require Docker, SITL, or any external service and run as part of the project's main pytest invocation (testpaths extension in pyproject.toml).