Record API responses in tests for client compatibility checks

[mdegat01]

Proposed change

This is step 2 of #7307: recording the responses Supervisor's API tests produce, so the aiohasupervisor compat checker (python-supervisor-client#431) can check that released client versions can still parse them.

tests/common.py adds api_record_middleware(), which is registered on the api_client, api_client_v2 and app_api_client_with_prefix fixtures. The other API client fixtures reuse those. When SUPERVISOR_API_RECORD_DIR is set, every response whose body is a Supervisor JSON envelope is appended as one line to <dir>/<PYTEST_XDIST_WORKER or "main">.jsonl:

{"method": "GET", "template": "/host/disks/{disk}/usage", "params": ["default"],
 "query": [["max_depth", "2"]], "status": 200, "body": {...},
 "test": "tests/api/test_host.py::test_disk_usage_api"}

• template is the matched route's canonical path, including /v2 for v2 routes. params holds the route values in template order.
• query holds the query string as [key, value] pairs. Query keys can change a response (e.g. core/stats?one_shot), and the checker matches on them.
• Responses that aren't Supervisor envelopes, such as the Core API proxy passthrough, are skipped.
• With the variable unset, the middleware returns right after the handler and writes nothing. When recording, the cost is about 100µs per response, which doesn't show up in suite run time.

The middleware docstring documents the record format, which is the contract the client's checker reads. tests/api/test_api_record.py covers v1 and v2 recording, and covers the variable being unset.

Step 3, the client-compat CI job that runs the checker for the client versions in use, is still to do, so this doesn't close #7307.

Expected failures when running the checker locally: if you record with this branch and run the checker from the latest client release (0.7.0), it reports two failures until the client PRs below are merged and released:

• GET /addons/{addon}/info for an app that isn't installed. Supervisor's v1 fallback returns store info, which the client can't parse as InstalledAddonComplete. This is a real client bug, fixed by Raise not found from addon_info for apps that are not installed home-assistant-libs/python-supervisor-client#439.
• GET /core/stats?one_shot. The checker didn't take the query string into account, so this was a false positive. Fixed by Match query keys in the compat checker home-assistant-libs/python-supervisor-client#438.

With both client PRs applied, a recording of tests/api from this branch checks clean: 1108 responses, 216 replayed through the client, 0 failures, 0 warnings. Supervisor's own test suite passes either way.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New feature (which adds functionality to the supervisor)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

• This PR fixes or closes issue: fixes #
• This PR is related to issue: Catch aiohasupervisor response-parsing breakage in Supervisor CI #7307
• Link to documentation pull request:
• Link to cli pull request:
• Link to client library pull request: Match query keys in the compat checker home-assistant-libs/python-supervisor-client#438, Raise not found from addon_info for apps that are not installed home-assistant-libs/python-supervisor-client#439

Checklist

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the development checklist
• The code has been formatted using Ruff (ruff format supervisor tests)
• Tests have been added to verify that the new code works.

If API endpoints or add-on configuration are added/changed:

• Documentation added/updated for developers.home-assistant.io
• CLI updated (if necessary)
• Client library updated (if necessary)

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Fresh recording directories fail, and envelope-shaped Core proxy responses are incorrectly recorded.

2 open findings

• Create the configured record directory before writing responses · New
• Explicitly exclude Core API proxy responses from recording · New

What changed in this PR

Adds test-time API response recording for future aiohasupervisor compatibility checks.

Changes:

• Adds JSONL response-recording middleware.
• Registers recording across v1, v2, and app API clients.
• Tests enabled and disabled recording behavior.

File	Description
tests/​common.py	Implements response recording.
tests/​conftest.py	Registers middleware for the primary API client.
tests/​api/​conftest.py	Registers middleware for additional API clients.
tests/​api/​test_api_record.py	Tests recorder output and opt-in behavior.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The recorder contract, fixture integration, proxy exclusions, and enabled/disabled behavior are consistently implemented and tested.

0 open findings

2 resolved since last review

• Explicitly exclude Core API proxy responses from recording
• Create the configured record directory before writing responses

🧠 Review effort: Balanced

[agners]

LGTM, thanks!