| name | aquilia-testing-debug-toolkit |
| description | Use Aquilia testing and debugging utilities. Use for TestServer, TestClient, WebSocketTestClient, AquiliaTestCase, fixtures, mocks, aq test, debug pages, diagnostics, health, and framework regression tests. |
Aquilia Testing Debug Toolkit
Purpose
Test Aquilia apps in-process and debug framework behavior with real testing utilities.
Trigger Conditions
Use for writing tests, running aq test, in-process HTTP/WebSocket tests, fixtures, mock DI/cache/effects/fault/mail, debug pages, health checks, and regression coverage.
Inputs
- Manifests, config overrides, enabled subsystems, request paths, expected responses.
- Pytest/unittest preference.
- Optional live server requirement.
Execution Flow
- For in-process API tests, use
TestServer and TestClient; no network socket is needed.
- For unittest-style tests, subclass
AquiliaTestCase; set manifests, settings, and subsystem enable flags.
- For pytest, import fixtures from
aquilia.testing.fixtures.
- Use
TestResponse helpers for JSON, headers, status, redirects, and cookies.
- Run
aq test or python -m pytest tests/ depending on scope.
Constraints
- Prefer in-process tests unless real TCP behavior is required.
- Enable subsystems explicitly in test cases to avoid hidden dependencies.
- Keep workspace mutation out of tests unless testing generators/discovery.
Implementation Anchors
aquilia/testing/, aquilia/debug/pages.py, aquilia/cli/commands/test.py, tests/, examples/*/tests/.
Examples
async with TestServer(manifests=[manifest]) as srv: resp = await TestClient(srv).get("/").- Subclass
AquiliaTestCase with enable_sessions=True.
- Use
mail_outbox, di_container, or effect_registry fixtures.
Failure Handling
If server exceptions should be captured rather than raised, configure TestClient(raise_server_exceptions=False). If async fixtures fail, confirm pytest-asyncio is installed and asyncio_mode=auto from pyproject is active.
