Integration test: API facts endpoints (FastAPI TestClient + Redis)

[berendt]

Part of #2400. Follow-up to #2368. Requires the shared httpx prerequisite (see the meta issue).

What

Cover the inventory-facts HTTP endpoints, which read straight from Redis:

• GET /v1/inventory/hosts/{host}/facts (osism/api.py:927)
• GET /v1/inventory/hosts/{host}/facts/{fact} (osism/api.py:966)

Both call utils.redis.get("ansible_facts{host}"). Driving them through fastapi.testclient.TestClient against the live Redis exercises the API↔Redis path end-to-end.

Scope

• Seed ansible_facts<host> in Redis → GET .../facts returns 200 with the parsed facts and correct count.
• Single fact: GET .../facts/{fact} returns the value; unknown fact → 404.
• Unknown host (no key) → 404.
• Malformed JSON in Redis → 500.

Notes / Where

New file tests/integration/test_api_facts.py. Importing osism.api wires the event bridge to Redis at import time — fine in the integration env where Redis is up (and the suite is skipped without it). Add httpx to [dev-packages] in Pipfile (TestClient needs it). Clean up seeded keys per test.

[berendt]

Implementation Plan (issue #2406)

Summary

Add a new integration-test module tests/integration/test_api_facts.py that drives the two read-only inventory-facts endpoints through fastapi.testclient.TestClient against the live Redis, plus the shared httpx dev-dependency the TestClient needs. The endpoints read ansible_facts<host> straight from utils.redis, so each test seeds that exact key, exercises the API↔Redis path, and deletes the key in teardown. The change set is two production-irrelevant artifacts (a Pipfile/Pipfile.lock dev-dep bump and one test file) — the smallest set that satisfies every Scope item.

Ground-Truth Notes

• osism/api.py:927 get_host_facts (GET /v1/inventory/hosts/{host}/facts) — confirmed. Reads utils.redis.get(f"ansible_facts{host}") (line 935); not data → HTTPException(404); json.loads(data) → json.JSONDecodeError caught → HTTPException(500); builds FactsResponse(host, facts=[FactEntry...], count=len(facts), from_cache=True).
• osism/api.py:966 get_host_fact (GET /v1/inventory/hosts/{host}/facts/{fact}) — confirmed. Same Redis read (line 974); missing key → 404; fact not in facts_data → 404; malformed JSON → 500; returns FactSingleResponse(host, name=fact, value=..., from_cache=True).
• Response models FactEntry / FactsResponse / FactSingleResponse — confirmed at osism/api.py:342, :347, :354. value is typed Any, so non-string facts (ints, dicts) round-trip.
• utils.redis — confirmed. Exposed lazily via osism/utils/__init__.py:662 __getattr__("redis") → _init_redis() (line 22), a Redis(...) client without decode_responses (returns bytes). Seeding via utils.redis.set and the endpoint's utils.redis.get hit the same singleton in-process. Note: resolving utils.redis calls .ping(), which only happens when a test runs (i.e. Redis present).
• Redis key format — confirmed: f"ansible_facts{host}" has no separator (host h → key ansible_factsh). Same format used in osism/commands/get.py:194 and osism/tasks/rabbitmq paths.
• Import-time wiring — confirmed. osism/api.py:147 calls event_bridge.set_websocket_manager(websocket_manager) at module level; the event_bridge singleton (osism/services/event_bridge.py:304) connects to Redis in __init__ and starts a daemon subscriber thread on osism:events. Harmless for these tests; matches the issue's note.
• Import chain (key risk, grounded): importing osism.api transitively imports osism.tasks.conductor.utils, which does from ansible import constants / errors / parsing.vault at module level (osism/tasks/conductor/utils.py:5-7). This only works because tests/conftest.py:23 _install_ansible_stubs() registers stub ansible modules in sys.modules at conftest-import time. tests/conftest.py is loaded for tests/integration under default pytest conftest discovery (rootdir is setup.cfg; conftests load from rootdir down to the arg dir). All other transitive deps (openstacksdk, kombu, pynetbox, fastapi) are installed in the CI env. osism.tasks.netbox and osism.services.listener/websocket_manager have no ansible/openstack import-time deps.
• httpx — confirmed absent from Pipfile [dev-packages] (Pipfile:44-47), requirements.txt, and Pipfile.lock (0 hits). fastapi==0.137.2 and uvicorn[standard]==0.49.0 are in requirements.txt:13,36 (installed via pipenv run pip install .), confirming "fastapi is already a runtime dependency". Of httpx's transitive deps, only certifi/idna already exist in the lock; re-locking will add httpx, httpcore, h11, anyio, sniffio.
• CI re-lock requirement (critical): playbooks/test-integration.yml:47 runs pipenv install --dev --deploy. --deploy aborts if Pipfile.lock's _meta.hash is stale. Therefore adding httpx to Pipfile mandates regenerating Pipfile.lock, or the CI job fails before tests run.
• Test conventions — confirmed from tests/integration/{test_celery,test_locking,test_redis_streams}.py: SPDX header, module docstring, pytestmark = pytest.mark.integration, from osism import utils at top, heavy imports (osism.tasks.ansible) deferred inside fixtures/tests, unique f"itest-{uuid.uuid4()}" keys. integration marker is registered in setup.cfg (--strict-markers).

Change Set

• Pipfile — modify: add httpx = "==<latest stable, expected 0.28.x>" as the first entry under [dev-packages] (alphabetical, lowercase, exact-pin to match the existing Renovate-managed == style).
• Pipfile.lock — modify: regenerate via pipenv lock so _meta.hash matches the new Pipfile and httpx+transitives (httpcore, h11, anyio, sniffio) are pinned with hashes. Review the diff to confirm only those packages are added and no unrelated pins move.
• tests/integration/test_api_facts.py — create: new module, pytestmark = pytest.mark.integration. Two fixtures and six tests:
  • client fixture — imports from fastapi.testclient import TestClient and from osism import api inside the fixture (deferred, matching existing convention), yields with TestClient(api.app) as c: (clean transport teardown; osism.api has no @app.on_event lifespan handlers, so the context manager is safe and idiomatic).
  • seed_facts fixture — yields a seed(host, value) callable that does utils.redis.set(f"ansible_facts{host}", value), records the key, and utils.redis.delete(...)s every recorded key in teardown (satisfies "clean up seeded keys per test"; only seeded keys are tracked, so the unknown-host tests need no cleanup).
  • test_get_all_facts_returns_parsed_facts_and_count — seed a dict with mixed value types (str, int, nested dict); assert 200, body["host"] == host, body["count"] == len(facts), body["from_cache"] is True, and {e["name"]: e["value"] for e in body["facts"]} == facts.
  • test_get_single_fact_returns_value — seed facts; GET .../facts/<name>; assert 200, name, exact value, from_cache is True.
  • test_get_unknown_fact_returns_404 — seed facts; GET .../facts/does_not_exist; assert 404.
  • test_get_all_facts_unknown_host_returns_404 — no seed; assert 404.
  • test_get_single_fact_unknown_host_returns_404 — no seed; assert 404 (covers the second endpoint's missing-key path).
  • test_get_all_facts_malformed_json_returns_500 — seed_facts(host, "{ not valid json") (non-empty invalid JSON → passes the not data guard, fails json.loads); assert 500. (FastAPI converts the handler's HTTPException(500) into a response, so TestClient's default raise_server_exceptions=True does not re-raise.)

Commit Sequence

1. Add httpx to dev dependencies for FastAPI TestClient — Pipfile, Pipfile.lock; body: TestClient (fastapi.testclient) requires httpx; re-lock so pipenv install --dev --deploy stays green. (Shared Tier-2 prerequisite; sibling Integration test: WebSocket /v1/events/openstack (FastAPI TestClient) #2407 builds on it.)
2. Add integration tests for inventory facts API endpoints — tests/integration/test_api_facts.py; body: drive get_host_facts/get_host_fact through TestClient against live Redis, covering parsed-facts/count, single-fact, unknown fact/host 404s, and malformed-JSON 500.

(Both land in one PR; squashing into a single commit is acceptable. Apply the repo's standard commit trailer.)

Test Plan

• tests/integration/test_api_facts.py — the six tests above lock down every Scope item: 200 + parsed facts + correct count; single-fact value; unknown-fact 404; unknown-host 404 (both endpoints); malformed-JSON 500. Test names are behavior-describing (BDD), each is independent (UUID host), and teardown removes seeded keys. The suite is skipped locally without Redis (existing pytest_collection_modifyitems in tests/integration/conftest.py) and runs for real in CI.

Documentation Plan

• README.md "Running integration tests" (lines 25-28) — optional, minimal: the overview sentence currently enumerates only the "Celery/Redis task core". A one-clause additive edit (e.g. "… and the FastAPI inventory-facts API↔Redis read path") would keep it accurate. Caveat: this sentence is shared by all Meta: Extend Celery/Redis integration tests (Tier 1 + Tier 2) #2400 siblings; editing it per-issue invites churn/merge conflicts, so it is reasonable to defer this to the meta issue or the last sibling. The existing Warning block already covers our per-run UUID keys, so no warning change is needed.
• No CHANGELOG/API-doc update: the change adds a test and a dev dependency — no user-visible runtime behavior changes.

Verification Commands

• Re-lock (mandatory, not a test — must be run locally to produce the committed artifact):
  • pipenv lock (after editing Pipfile), or equivalently pipenv install "httpx==<version>" --dev.
  • pipenv verify — confirms Pipfile.lock is in sync (the same gate --deploy enforces). Alternatively replicate CI exactly: pipenv install --dev --deploy.
• Test run (per the user's "let CI run tests" preference, this is CI's job; commands match playbooks/test-integration.yml and README):
  • docker run -d -p 6379:6379 redis:7-alpine
  • REDIS_HOST=localhost OSISM_REQUIRE_REDIS=1 pipenv run pytest tests/integration/test_api_facts.py
• Optional one-shot import sanity check (confirms the osism.api import chain resolves with the conftest stubs): pipenv run python -c "import tests.conftest; import osism.api; print('ok')".

Risks & Open Questions

• Pipfile.lock must be regenerated — highest-priority operational item. Skipping the re-lock makes pipenv install --dev --deploy abort in CI before any test runs. Mitigation: commit the regenerated lock; verify with pipenv verify.
• import osism.api depends on tests/conftest.py ansible stubs being loaded for the integration suite. This holds under default pytest conftest discovery, and deferring the import into the client fixture keeps collection cheap and a Redis-less local run cleanly skipped. Residual risk only if a future change relocates/guards _install_ansible_stubs(). The optional import sanity check above surfaces it immediately.
• httpx version compatibility with fastapi==0.137.2/starlette — expected fine with httpx 0.28.x; let the resolver pick and pin the exact version. No version is fabricated here.
• README overview sentence is shared across all Meta: Extend Celery/Redis integration tests (Tier 1 + Tier 2) #2400 siblings — see Documentation Plan; per-issue edits risk merge churn.
• No scope/blast-radius concern: change is confined to one new test file plus a dev-dependency bump the issue explicitly requested. No new package, no production code touched.

Status

STATUS: PLAN_READY

---

Implementation plan generated by planwerk-review f1c04d7 implement with Claude

[berendt]

Implementation Report (issue #2406)

Acceptance Criteria

• Seed ansible_facts<host> in Redis → GET .../facts returns 200 with the parsed facts and correct count.
  • Status: satisfied
  • Evidence: tests/integration/test_api_facts.py:54 test_get_all_facts_returns_parsed_facts_and_count — seeds mixed value types (str/int/nested dict), asserts 200, count == len(facts), from_cache is True, and that the reconstructed {name: value} map equals the seeded facts.
• Single fact: GET .../facts/{fact} returns the value; unknown fact → 404.
  • Status: satisfied
  • Evidence: value path test_get_single_fact_returns_value (:73); error path test_get_unknown_fact_returns_404 (:89) asserts 404 for a fact absent from the cached set.
• Unknown host (no key) → 404.
  • Status: satisfied
  • Evidence: test_get_all_facts_unknown_host_returns_404 (:98) and test_get_single_fact_unknown_host_returns_404 (:107) — covers the missing-key path on both endpoints.
• Malformed JSON in Redis → 500.
  • Status: satisfied
  • Evidence: test_get_all_facts_malformed_json_returns_500 (:116) seeds "{ not valid json" (passes the not data guard, fails json.loads) and asserts 500.
• Add httpx to [dev-packages] in Pipfile (TestClient needs it).
  • Status: satisfied
  • Evidence: Pipfile:45 (httpx = "==0.28.1"); Pipfile.lock regenerated so pipenv install --dev --deploy stays green (pipenv verify passes).
• Clean up seeded keys per test.
  • Status: satisfied
  • Evidence: seed_facts fixture (:39) tracks each seeded key and deletes it in teardown.

Commits

• aaf7789 Add httpx to dev dependencies for FastAPI TestClient
• cc41349 Add integration tests for inventory facts API endpoints

Local verification

• pipenv lock then restore-greenlet round-trip — pass (only httpx+transitives added to develop; no runtime pins moved)
• pipenv verify — pass (Pipfile.lock is up-to-date, the same gate --deploy enforces)
• python -m py_compile tests/integration/test_api_facts.py — pass
• flake8 tests/integration/test_api_facts.py — pass (exit 0)
• pytest tests/integration — skipped: per your standing preference, tests run in CI (the integration job provides the live Redis these tests require)

Pull Request

• URL: Integration test: API facts endpoints (FastAPI TestClient + Redis) #2411
• Branch: implement/issue-2406-api-facts-integration-test

Deviations from the issue

• Restored greenlet in Pipfile.lock after re-locking. My local pipenv lock (macOS/arm64, pipenv 2026.6.1) dropped the SQLAlchemy transitive greenlet ==3.5.2 from the default section — an unrelated runtime change. SQLAlchemy 2.0.49 requires greenlet on all common platform_machine values (incl. CI's x86_64), so I re-inserted the exact HEAD entry. Net lock diff is now only the httpx stack added to develop. The _meta.hash is keyed off the Pipfile, so this leaves pipenv verify/--deploy green.
• README left untouched. The plan flagged the "Running integration tests" overview sentence as optional and shared across all Meta: Extend Celery/Redis integration tests (Tier 1 + Tier 2) #2400 siblings; editing it per-issue invites merge churn, and the change adds no user-visible runtime behavior. Noted in the PR body.

Status

STATUS: DONE

---

Implementation report generated by planwerk-review f1c04d7 implement with Claude