Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
Ethos employs a multi-layered testing strategy designed to ensure the reliability of its neuromorphic memory engine. The strategy spans unit testing of core logic, integration testing of database interactions, and end-to-end verification of IPC (Inter-Process Communication) and REST API layers. The primary goal is to maintain high test coverage—targeting 90% or greater—across all Rust crates and TypeScript hooks.
The strategy encompasses three main pillars:
- Backend Integration: Validating the Rust server's ability to handle requests, manage database transactions via PostgreSQL/pgvector, and execute memory subsystems (Consolidation, Decay, Retrieval).
- API & Protocol Verification: Ensuring the REST API (Axum) and Unix Socket IPC (MessagePack) conform to expected contracts.
- Hook & Client Validation: Testing the TypeScript-based ingest and context hooks to ensure passive conversation recording and memory injection function correctly in production-like environments.
Sources: README.md:188-202, ethos-server/src/http.rs:10-15
Backend Rust Testing Architecture
The backend testing infrastructure relies heavily on tokio for asynchronous execution and sqlx for managing real-world database states during integration tests.
Integration Testing with PostgreSQL
Tests in ethos-server/tests utilize a live PostgreSQL connection to verify that data ingested through the router or HTTP handlers correctly populates tables such as session_events, memory_vectors, and semantic_facts.
The diagram shows the flow of an integration test verifying the end-to-end path from a request to database persistence.
Sources: ethos-server/tests/ingest_integration.rs:7-35, ethos-server/tests/http_integration.rs:18-25
Subsystem Logic Isolation
To improve testability and coverage accuracy, the HTTP layer is structured to delegate logic to "inner" functions. This allows developers to test business logic directly without invoking the Axum dispatch machinery.
| Test Category | Target Component | Purpose |
|---|---|---|
| Inner Logic | search_inner, ingest_inner | Directly test JSON processing and router delegation. |
| HTTP Handlers | search_handler, health_handler | Verify status codes and Axum extraction. |
| Oneshot Tests | tower::ServiceExt | Full end-to-end HTTP request/response cycle testing. |
Sources: ethos-server/src/http.rs:11-17, ethos-server/tests/http_integration.rs:163-195
IPC and Socket Testing
Ethos uses a Unix domain socket for IPC, utilizing a little-endian length-prefixed MessagePack payload. Testing this layer involves mocking the socket server and client to verify protocol compliance.
TypeScript Client Testing
The EthosClient tests verify the lifecycle of the socket connection, including connection retries, sequential request handling, and timeout mechanisms.
This sequence illustrates how TypeScript tests simulate the IPC protocol to ensure the client correctly encodes and decodes memory operations.
Sources: ethos-ingest-ts/tests/client-request.test.ts:31-75, README.md:112-119
Protocol Verification Cases
- Malformed Payloads: Verifying that empty or structured JSON lacking required fields (e.g.,
content) returns an error status rather than panicking. - Role Mapping: Ensuring that the "source" field in ingest requests correctly maps to the internal
rolecolumn in the database (e.g., mappingassistanttoassistant). - Sequential Requests: Validating that the client and server can handle multiple back-to-back requests over the same persistent connection.
Sources: ethos-server/tests/ingest_integration.rs:82-108, ethos-ingest-ts/tests/client-request.test.ts:107-142
REST API Integration
The REST API is tested using two primary methods: direct calls to inner logic functions and oneshot requests using the tower crate.
API Endpoint Coverage
Tests verify the following standard HTTP behaviors:
- Search Roundtrip: Sending a
SearchRequestand receiving a JSON body containingresults,count, andtook_ms. - Health Checks: Verifying the presence of
postgresql,pgvector, andversionfields in the health response. - Graceful Degradation: Ensuring the server returns a
503 Service Unavailableif the database is unreachable, rather than crashing.
Sources: ethos-server/tests/http_integration.rs:104-125, ethos-server/src/http.rs:105-132
CLI Compatibility
The ethos-cli acts as a search client and includes its own suite of tests to ensure output compatibility with the QMD wire protocol used by OpenClaw.
| CLI Test | Logic Verified |
|---|---|
test_qmd_docid_format | UUID truncation and hex formatting (e.g., #7b5c24). |
test_qmd_file_format | URI generation (e.g., ethos://memory/{uuid}). |
test_qmd_snippet_format | Formatting of diff-headers in search snippets. |
Sources: ethos-cli/src/main.rs:205-255
Automated Verification Tools
Ethos mandates specific tools and targets to maintain code quality:
- Cargo Tarpaulin: Used for measuring code coverage, with a target of 90%+.
- Clippy & Fmt: Strictly enforced lints (
-D warnings) and formatting checks in CI/CD. - Jest (TypeScript): Used for testing the hooks and clients with
--forceExitto handle lingering socket connections.
Sources: README.md:164-180
Ethos's testing strategy ensures that every component—from low-level Rust database migrations to high-level TypeScript event hooks—is verified through automated suites that simulate production loads and potential failure modes. This rigorous approach is critical for a memory engine that serves as the "hippocampus" for AI agents.
Sources: README.md:230-235