Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The MCB project employs a multi-layered testing strategy designed to ensure high performance, semantic accuracy, and architectural integrity. The strategy spans from low-level unit tests and architecture validation to complex end-to-end (E2E) scenarios involving real data processing and UI interactions. This comprehensive approach is central to maintaining the project's Clean Architecture and high-quality standards.
Testing is integrated into the development lifecycle via a canonical Makefile, with specific scopes including unit, doc, golden, startup, integration, e2e, and all. Quality gates, including linting and architecture validation, are mandatory for all contributions.
Sources: README.md:124-135, AGENTS.md:144-152
Testing Hierarchy and Scopes
The testing strategy is organized into distinct layers, each targeting specific aspects of the system.
| Scope | Description | Tools/Frameworks |
|---|---|---|
| Unit | Individual function and module logic validation. | cargo test, rstest |
| Integration | Crate boundaries, architecture rules, and linter execution. | mcb-validate, rust-code-analysis |
| E2E | Full system flow, Admin UI routes, and functional processing. | Playwright, HTTP/SSE |
| Architecture | Enforcement of Clean Architecture and dependency rules. | mcb-validate |
| Quality/Lint | Static analysis for code smell and safety violations. | Clippy, Ruff |
Sources: AGENTS.md:144-152, README.md:124-130, crates/mcb-validate/tests/integration/integration_linters.rs:260-310
Multi-Layer Testing Flow
The following diagram illustrates the flow from code change to final verification.
The testing flow ensures that superficial code quality is checked before proceeding to deep architectural and functional verification.
Sources: AGENTS.md:213-224, README.md:124-135
Architecture and Rule Validation
A unique component of the MCB testing strategy is the mcb-validate crate, which enforces Clean Architecture rules at compile-time and via specialized integration tests. This includes validating that dependencies flow inward only: mcb-domain must remain independent of internal mcb-* crates.
Implementation of Validation Pipeline
The full validation pipeline integrates multiple validators, configuration handling, and report generation. The GenericReporter aggregates violations into a GenericReport containing a summary and categorized lists of errors, warnings, and infos.
The relationship between validation configuration, violation detection, and reporting.
Sources: crates/mcb-validate/tests/integration/integration_full.rs:65-125, AGENTS.md:180-200
End-to-End (E2E) Testing
E2E tests verify the Admin Web UI and MCP protocol interactions. These tests use Playwright to simulate user interactions and verify HTTP accessibility of routes.
UI and Route Verification
E2E tests target critical routes such as /ui/health, /ui/config, and /ui/browse. They ensure that the server returns 200 OK responses and correctly serves HTML, CSS (e.g., theme.css), and JavaScript (e.g., shared.js) assets.
Sources: tests/e2e/admin-ui-routes.spec.ts:18-70
Functional Data Processing
E2E testing also includes "Real Data Processing" scenarios, where system metrics, job statuses, and collection grids are validated against actual system state.
Sources: tests/e2e/admin-functional.spec.ts:13-60
MCP Tool Interaction
The E2E suite verifies complex MCP tool chains, such as initializing a session, clearing an index, and triggering repository indexing via index_repo.
Sequence of MCP tool calls used during E2E setup and verification.
Sources: tests/e2e/browse-ui.spec.ts:18-65
Metrics and Complexity Analysis
MCB utilizes rust-code-analysis (RCA) to perform complexity analysis as part of the integration testing phase. This detects violations of cognitive complexity, cyclomatic complexity, and function length.
- Cognitive Complexity: Targeted at nested logic (if/for/match).
- Cyclomatic Complexity: Measures branching paths.
- Function Length: Ensures compact, maintainable source files (ideally under ~200 lines).
Sources: crates/mcb-validate/tests/integration/integration_metrics.rs:16-100, CONVENTIONS.md:20-25
Linter Integration
The testing strategy incorporates external linters (Ruff for Python, Clippy for Rust) by parsing their JSON output into a unified LintViolation format. This allows YAML-based rules to trigger linter checks and surface them as architectural violations.
Sources: crates/mcb-validate/tests/integration/integration_linters.rs:55-100, crates/mcb-validate/tests/integration/integration_linters.rs:430-480
Linter Execution Flow
How YAML rules are translated into active linter checks during validation.
Sources: crates/mcb-validate/tests/integration/integration_linters.rs:450-550
Conclusion
The MCB Testing Strategy provides a rigid framework for quality assurance, moving from static analysis and architectural enforcement to dynamic functional testing. By combining Rust's native testing capabilities with Playwright for E2E and custom validation logic for architecture, the project ensures that high-performance memory context features remain reliable and consistent with Clean Architecture principles.