register-referentie/docs/architecture/adr-0006-integration-test-provisioning.md

ADR-0006: Provision the ACL integration test against the compose stack

• Status: Accepted
• Date: 2026-06-29
• Deciders: Respellion engineering
• Relates to: S-04a (#46); proposed in #53; builds on ADR-0001 (loose coupling), ADR-0002 (catalogus design), ADR-0003 (default-fill); supports CLAUDE.md §11 (integration tests via real containers)

Context

S-04 delivered the ACL's one operation — OpenZaakGateway.OpenZaakAsync — with unit tests against a stubbed HttpMessageHandler and a Reqnroll scenario over an in-memory stand-in. The deferred S-04 acceptance criterion (S-04a) is the one a stub cannot meet:

Integration test using Testcontainers against real OpenZaak passes.

The test must drive the gateway against a real OpenZaak — real ZGW JWT auth, the real POST /zaken/api/v1/zaken contract, real CRS handling — and assert a zaak comes back.

Two ways to stand OpenZaak up were considered (the issue's open question): (a) a full Testcontainers graph started by the test, or (b) target the running compose stack the repo already defines (infra/openzaak/docker-compose.yml, make openzaak-up).

Investigation reversed the initially-favoured Testcontainers option:

1. Testcontainers .NET has no docker-compose support. OpenZaak needs PostGIS + Redis + a setup_configuration one-shot (the JWT client) + the API. Honouring "full graph" would mean re-implementing that five-service stack — init ordering, the config volume, health gating — by hand in C#, duplicating the maintained compose file and rotting with it. That rubs against CLAUDE.md §13 ("if a test is hard to write, the design is wrong").
2. The test cannot be hermetic anyway. OpenZaak's Zaken API rejects a zaak against a concept zaaktype (not-published), and a published zaaktype requires ≥1 resultaattype, which OpenZaak validates by fetching the external Selectielijst reference API (selectielijst.openzaak.nl). So a real zaak POST already depends on outbound internet from the OpenZaak container — the self-containment that motivated Testcontainers is lost regardless of how the containers are started.

Decision

The ACL integration test targets the running compose stack; it does not start containers itself. No new test dependency is added.

• A gated test project Acl.IntegrationTests ([Trait("Category","Integration")]) talks to OpenZaak with a plain HttpClient, reusing the same endpoint + JWT-client config the seed uses (OZ_BASE / OZ_CLIENT_ID / OZ_SECRET, defaulting to the local stack). It locates the published BIG-REGISTRATIE zaaktype via the Catalogi API and exercises the real OpenZaakGateway against it.
• The lane is kept out of the fast checks. make unit runs with --filter "Category!=Integration"; Stryker is pinned to Acl.Tests (test-projects), so neither the unit nor the mutation lane needs a live stack. A new make integration target (infra/run-integration.sh) brings the stack up, seeds, runs the lane, and always tears down — mirrored by a Gitea Actions integration job. This matches make being the single source of truth (ADR-0005).
• Publishing is opt-in in the seed. infra/openzaak/seed_catalogus.py gains an OZ_PUBLISH=1 path that adds the relations OpenZaak's publish requires — two statustypen (begin/eind), a roltype, and a resultaattype whose Selectielijst procestype is matched onto the zaaktype — then publishes. The default seed (S-01 / ADR-0002) still leaves the zaaktype a concept; only make integration flips the switch.

Consequences

• Positive: a small, honest test over the real ZGW contract with no bespoke orchestration to maintain; the compose stack is exercised exactly as operators run it; no new dependency.
• It caught a real bug. The gateway sent the zaak body via JsonContent without a Content-Length, so .NET framed it as Transfer-Encoding: chunked, which OpenZaak's uwsgi rejects with 400. A stubbed handler accepts either framing, so only a real OpenZaak surfaced it. Fixed by buffering the body (LoadIntoBufferAsync); guarded in the fast lane by a unit test asserting a Content-Length is set. This is the concrete justification for §11's integration tier.
• External dependency: the integration job needs the OpenZaak container to reach selectielijst.openzaak.nl. It is a stable public reference API (the same one OpenZaak uses in production) but it is a network touchpoint, and a CI environment without egress would need a local Selectielijst service or a recorded fixture. OZ_SELECTIELIJST overrides the base URL.
• Cost: the lane needs the stack up first, so it is separate from the fast lanes.
• Runs on the hosted runner. A process on the runner can't reach the stack's published ports (Compose starts sibling containers via the host daemon — gitea-actions-gotchas.md §5, same split as §1), so infra/run-integration.sh runs both the seed and the test as containers joined to the OpenZaak network, reaching it by container IP (a single-label host like openzaak isn't URL-valid for OpenZaak's own URLValidator; an IPv4 literal is). Code is delivered by image build / docker cp, never bind mounts. The CI job therefore needs only Docker — no setup-dotnet. (This closed the follow-up that was originally split out as #55.)

Alternatives considered

• Full Testcontainers graph — rejected: re-implements the compose stack in C# (brittle, duplicative) for no hermeticity gain, since the Selectielijst dependency remains.
• Single OpenZaak container (sqlite/locmem) — rejected: diverges from the real PostGIS-backed, Redis-cached deployment; the Zaken API is a geo API and the divergence would undermine the contract the test exists to verify.
• Mock OpenZaak / record-replay — rejected: that is what the existing stubbed-handler unit tests already do; it cannot exercise the real contract, and would not have caught the chunked body bug.