Backend Rust Testing
Relevant source files
The following files were used as context for generating this wiki page:
Backend Rust testing ensures the reliability of domain rules, persistence logic, and transport adapters. The testing strategy prioritizes testing rules at their owner—the specific crate or module that implements them. This approach enforces durable boundaries by asserting behavior through public interfaces rather than implementation details.
Sources: AGENTS.md:154-156, AGENTS.md:16-18
Testing Principles and Scope
The project follows a tiered testing approach that separates unit and integration concerns. Unit and integration tests occur during implementation, while required gates run after changes stabilize.
- Rule Ownership: Each rule is tested once at its owner. Transport and route tests assert contracts like status codes and reasons, while domain rules remain in the owner's tests.
- Error Assertion: Tests must assert the exact error variant of a denial. They also verify that the denial resulted in no state changes.
- Delta-based Assertions: Tests assert deltas and domain properties instead of totals like byte sizes or event counts, which fluctuate with unrelated changes.
- Fault Injection: Faults are injected through the crate's API or
TestDatabase::execute_fixture_sqlto ensure compatibility across both SQLite and Postgres.
Sources: AGENTS.md:154-166, AGENTS.md:168-172
Required Validation Gates
| Change Type | Validation Command |
|---|---|
| Rust Core | make rust-checks |
| Postgres Behavior | make postgres-tests |
| Runtime/Image | make docker-test |
| Dev Scripts | ./dev test |
Sources: AGENTS.md:183-195
Persistence and Database Testing
Shared repository tests must run against both SQLite and Postgres backends. This ensures that portable schema migrations and domain queries behave consistently.
Database Test Lifecycle
The following diagram illustrates the flow of a database-backed test:
The testing harness uses TestModules to manage database lifecycle and migration application.
Sources: crates/coral-search/src/tests/storage.rs:88-94, AGENTS.md:104-105
Schema Migration Testing
Tests verify that the migration chain remains portable.
- Integrity Checks:
scripts/check-migrations.shensures that migrations onmainare never deleted or renamed. - Feature Detection: Features like FTS5 or
pg_trgmare checked at boot before the migration chain runs. - Trigger Validation: Tests verify that database triggers (e.g., SQLite FTS5 triggers) keep text indexes in sync with entity tables.
Sources: AGENTS.md:92-102, crates/coral-search/src/tests/storage.rs:11-15
MCP and Argument Validation Testing
The Model Context Protocol (MCP) layer uses automated tests to verify input constraints and output schemas.
Input Constraint Verification
Tests validate that advertised JSON schemas match domain requirements. This includes checking:
- Identifier Patterns: UUIDs and four/five-word identifiers must match
SCHEMA_PATTERN. - Text Constraints: Fields like
intent,query, andfeedbackare checked for non-emptiness and byte limits. - Source Limits: Program sources and function descriptions are tested against KiB limits.
Sources: crates/coral-mcp/tests/credential_free_tracer/input_contracts.rs:43-55, crates/coral-mcp/src/arguments.rs:256-265
Schema Snapshot Testing
The system uses snapshots to ensure that advertised output schemas remain stable. If a change occurs, the test rewrites the snapshot and fails, requiring a manual review of the diff.
OpenAPI Materialization Testing
Testing the OpenAPI catalog involves materializing documents and verifying the resulting TypeScript declarations and HTTP bindings.
- Success Selection: Tests verify that each HTTP response status selects the correct success verdict (e.g.,
Declared,Untyped, orErrorStatus). - TypeScript Compilation: Materialized declarations are passed to the
ProgramCompilerto ensure they compile strictly and represent recursion correctly. - Credential Contracts: Tests verify that operations agree on credential contracts and that unsupported configurations (like digest auth or excessive OAuth scopes) are rejected.
Sources: crates/coral-catalog/tests/openapi_materialization.rs:136-150, crates/coral-catalog/tests/openapi_materialization.rs:230-245, crates/coral-catalog/tests/openapi_materialization.rs:770-785
Credential and Security Testing
Security testing focuses on isolation and credential storage.
- Dummy Credentials: Tests using dummy credentials must explicitly select filesystem storage. Writing test credentials to the OS keychain is prohibited.
- Credential Masking: Rejection messages must not echo sensitive information, such as passwords found in server URLs.
- Authorization Decision Testing: Rust authorization tests cover CSP hashing, browser binding, and the escaping of dynamic values in templates.
Sources: AGENTS.md:177-179, crates/coral-catalog/tests/openapi_materialization.rs:1335-1345, crates/coral-app/src/auth/authorization_server/authorize/approval.md:16-19
Conclusion
Backend Rust testing in Coral combines strict unit testing with cross-backend integration checks. By asserting behavior at the module boundary and utilizing automated schema verification, the project maintains a stable domain model across different transport and persistence layers.