Contract tests

These tests defend the three machine-facing surfaces of fbb — the interfaces that skills and automation consume, where silent drift causes wrong-branch bugs that only surface on hardware:

File	Surface under test	Source of truth
test_exit_codes.py	the exit-code enum (0/1/2/3/4)	cli.py epilog
test_json_summary.py	every verb's --json-summary envelope	each verb's _summary builder + module docstring
test_sdk_detection.py	SDK resolution order (--sdk-dir > $FBB_SDK_DIR > cwd)	sdk.find_sdk_dir
test_cli_smoke.py	--help for every verb (L1) + no-hardware behaviour of the otherwise-uncovered commands (L2)	the verb table in cli.py / verbs.py

They are hermetic: no provisioned build env, no real SDK checkout, no serial hardware. Subprocess tests scrub inherited FBB_* env vars and put the source tree on PYTHONPATH, so results don't depend on the developer's machine. Pure functions (summary builders, find_sdk_dir) are imported and called directly.

Run

# with uv (no install needed)
uv run --extra test pytest -n 8

# or, if the package + pytest are already importable
pytest -n 8

Scope (and what's deliberately out)

Covered: exit codes, JSON schema key-sets, the stdout/stderr split, SDK detection precedence, fbb help <verb> delegation, --help for every verb (L1), and the no-hardware behaviour of the otherwise-uncovered commands — doctor on a clean env, env dump, sdk list on an empty root, list-targets / list-examples on a minimal SDK (L2).

Not covered here (they need a provisioned venv, toolchain, or a real board): build forwarding, real flash burns, monitor serial reads, and set-target validation against a live target probe. Those belong to the on-hardware HIL matrix, not this unit layer.