ADR proposal: provisioning strategy for the ACL OpenZaak integration test #53

New Issue

not · 2026-06-29T09:09:53Z

not commented

2026-06-29 09:09:53 +00:00

Decision to record

S-04a (#46) requires an integration test that exercises OpenZaakGateway against real OpenZaak (real JWT auth + the real POST /zaken/api/v1/zaken contract), which the stubbed-HttpMessageHandler unit test cannot cover.

Two decisions need an ADR before coding:

New dependency: Testcontainers (.NET). There is no OpenZaak Testcontainers module, so we use the generic container builder to bring up the graph.
- What it gives us: programmatic, hermetic, CI-portable startup of the OpenZaak graph from the test itself.
- What we'd write to replace it: bespoke docker/compose orchestration + readiness polling glue in the test host.
- Risk: requires a Docker-capable CI runner; heavier/slower than unit tests (mitigated by gating it out of the fast unit/mutation lanes).
Provisioning approach: full Testcontainers graph (PostGIS + Redis + OpenZaak + setup_configuration JWT client) over targeting the already-running make stack-up compose stack. Chosen for hermeticity and self-containment (#46's open question).
Publish-in-arrange. OpenZaak's Zaken API rejects a zaak against a concept zaaktype. The S-01 BIG seed (ADR-0002) intentionally leaves BIG-REGISTRATIE as a concept. The integration test therefore needs an opt-in path (extending seed_catalogus.py) that adds the minimal statustype/resultaattype/roltype and publishes the zaaktype. Default seed behaviour stays concept-only.

ADR file (docs/architecture/adr-0006-*.md) lands in the PR that implements #46.

Refs #46.

## Decision to record S-04a (#46) requires an integration test that exercises `OpenZaakGateway` against **real OpenZaak** (real JWT auth + the real `POST /zaken/api/v1/zaken` contract), which the stubbed-`HttpMessageHandler` unit test cannot cover. Two decisions need an ADR before coding: 1. **New dependency: Testcontainers (.NET).** There is no OpenZaak Testcontainers module, so we use the generic container builder to bring up the graph. - *What it gives us:* programmatic, hermetic, CI-portable startup of the OpenZaak graph from the test itself. - *What we'd write to replace it:* bespoke `docker`/compose orchestration + readiness polling glue in the test host. - *Risk:* requires a Docker-capable CI runner; heavier/slower than unit tests (mitigated by gating it out of the fast unit/mutation lanes). 2. **Provisioning approach: full Testcontainers graph** (PostGIS + Redis + OpenZaak + setup_configuration JWT client) over targeting the already-running `make stack-up` compose stack. Chosen for hermeticity and self-containment (#46's open question). 3. **Publish-in-arrange.** OpenZaak's Zaken API rejects a zaak against a **concept** zaaktype. The S-01 BIG seed (ADR-0002) intentionally leaves `BIG-REGISTRATIE` as a concept. The integration test therefore needs an opt-in path (extending `seed_catalogus.py`) that adds the minimal statustype/resultaattype/roltype and **publishes** the zaaktype. Default seed behaviour stays concept-only. ADR file (`docs/architecture/adr-0006-*.md`) lands in the PR that implements #46. Refs #46.

not added this to the Iteration 1 — Walking Skeleton milestone 2026-06-29 09:09:53 +00:00

not added the area:acl type:adr-proposal labels 2026-06-29 09:09:53 +00:00

not changed title from ~~ADR proposal: Testcontainers for the ACL OpenZaak integration test~~ to ADR proposal: provisioning strategy for the ACL OpenZaak integration test

2026-06-29 09:24:59 +00:00

not commented

2026-06-29 09:25:00 +00:00

Decision updated after investigation.

Originally proposed bringing the OpenZaak graph up via Testcontainers. Two findings reversed that:

Testcontainers .NET has no docker-compose support — honouring a "full graph" would mean hand-rolling the 5-service stack (PostGIS + Redis + the setup_configuration one-shot + API) in C#, duplicating infra/openzaak/docker-compose.yml and rotting with it (rubs against CLAUDE.md §13).
The test cannot be hermetic anyway: a published zaaktype forces a live dependency on selectielijst.openzaak.nl (OpenZaak fetches it to validate the resultaattype). The self-containment that motivated Testcontainers is already lost.

Revised decision: the integration test targets the running compose stack (make openzaak-up + an opt-in OZ_PUBLISH=1 seed). No new NuGet dependency. CI brings the stack up before make integration.

This is recorded in ADR-0006 (lands in the #46 PR). Refs #46.

**Decision updated after investigation.** Originally proposed bringing the OpenZaak graph up via **Testcontainers**. Two findings reversed that: 1. **Testcontainers .NET has no docker-compose support** — honouring a "full graph" would mean hand-rolling the 5-service stack (PostGIS + Redis + the `setup_configuration` one-shot + API) in C#, duplicating `infra/openzaak/docker-compose.yml` and rotting with it (rubs against CLAUDE.md §13). 2. **The test cannot be hermetic anyway**: a *published* zaaktype forces a live dependency on `selectielijst.openzaak.nl` (OpenZaak fetches it to validate the resultaattype). The self-containment that motivated Testcontainers is already lost. **Revised decision:** the integration test **targets the running compose stack** (`make openzaak-up` + an opt-in `OZ_PUBLISH=1` seed). No new NuGet dependency. CI brings the stack up before `make integration`. This is recorded in ADR-0006 (lands in the #46 PR). Refs #46.

not referenced this issue from a commit

2026-06-29 09:43:54 +00:00

arch(acl): ADR-0006 — provision the ACL integration test against the compose stack (refs #46)

not referenced a pull request that will close this issue

2026-06-29 09:44:22 +00:00

test(acl): ACL integration test against real OpenZaak (closes #46) #54

not closed this issue

2026-06-29 10:48:01 +00:00

Sign in to join this conversation.