docs: add integration testing with Testcontainers guide

[minitriga]

Summary

• Adds docs/docs/testing-framework/testcontainers.mdx — a how-to guide for the infrahub-testcontainers package covering installation, the TestInfrahubDocker pytest base class and its fixtures, SDK connection setup, environment variable reference, cluster deployment, and a GitHub Actions CI example
• Converts the Testing Framework sidebar entry from a flat doc to a collapsible category with the new page as a spoke (hub link → overview, spoke → new testcontainers page)
• Adds Gunicorn, Testcontainers, and testcontainers to .vale/styles/spelling-exceptions.txt

Closes #9362

Reviewer attention

• Quick-start code example uses infrahubctl schema load (confirmed in tasks/infra_ops.py) and InfrahubClient(config=Config(...)) (confirmed in backend/tests/integration/git/test_git_repository.py). Please verify the Config constructor parameter names match the current SDK version.
• Token values (INFRAHUB_TESTING_INITIAL_ADMIN_TOKEN) are sourced from python_testcontainers/infrahub_testcontainers/container.py — correct at time of writing but worth a quick check if the package has been updated recently.

Test plan

• uv run invoke docs.lint — 0 errors (20 pre-existing warnings, none in new file)
• cd docs && npm run build — build passes
• Manual: confirm sidebar renders the Testing Framework as a collapsible category with both pages accessible

🤖 Generated with Claude Code

---

Summary by cubic

Adds a Testcontainers integration testing guide for infrahub-testcontainers, with real-world examples and a debugging workflow. Moves the guide to Development Resources, links it from the Developer Guide, and updates spelling exceptions.

• New Features
  • Added docs/docs/development-resources/testcontainers.mdx — install, TestInfrahubDockerClient async/sync clients, schema load + wait_until_converged, GitRepo, conftest.py, env vars, cluster mode, CI, debugging with breakpoint() + pytest -s, and real-world examples
  • Linked the page from the Developer Guide and added it to the Development Resources sidebar
  • Updated .vale spelling exceptions (e.g., conftest, Testcontainers, breakpoint, pdb, stdin)

^{Written for commit 71873b2. Summary will update on new commits. Review in cubic}

[cubic-dev-ai]

No issues found across 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would auto-approve. This PR adds a new documentation page for Testcontainers integration testing, updates spelling exceptions, and restructures the sidebar into a collapsible category—all documentation and configuration changes with no source code impact, so the risk of breaking any functionality is extremely low.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 3 files (changes from recent commits).

<sub>Shadow auto-approve: would auto-approve. The changes are limited to documentation (new testcontainers guide, developer guide update, sidebar restructuring) and adding spelling exceptions, with no modifications to source code, tests, or critical configuration, making the risk of breakage extremely low.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/docs/testing-framework/testcontainers.mdx">

<violation number="1" location="docs/docs/testing-framework/testcontainers.mdx:224">
P2: Wrap `infrahub_compose.start()` with the same try/except error handling as the real fixture, so startup failures during debugging capture and display container logs.</violation>
</file>

<sub>Shadow auto-approve: would not auto-approve because issues were found.
Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Wrap infrahub_compose.start() with the same try/except error handling as the real fixture, so startup failures during debugging capture and display container logs.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/testing-framework/testcontainers.mdx, line 224:

<comment>Wrap `infrahub_compose.start()` with the same try/except error handling as the real fixture, so startup failures during debugging capture and display container logs.</comment>

<file context>
@@ -176,6 +176,60 @@ pytest tests/ --deployment-type cluster
+```python
+@pytest.fixture(scope="class")
+def infrahub_app(self, request, infrahub_compose):
+    infrahub_compose.start()
+    yield infrahub_compose.get_services_port()
+    # containers are NOT stopped — remember to clean up manually
</file context>

Suggested change

	infrahub_compose.start()
	try:
	infrahub_compose.start()
	except Exception as exc:
	stdout, stderr = infrahub_compose.get_logs()
	raise Exception(f"Failed to start docker compose:\nStdout:\n{stdout}\nStderr:\n{stderr}") from exc

[cubic-dev-ai]

0 issues found across 3 files (changes from recent commits).

<sub>Shadow auto-approve: would not auto-approve. Auto-approval blocked by 1 unresolved issue from previous reviews.

Re-trigger cubic</sub>