Neo4j Memory Server

# Test Suite Documentation - Truth-First Architecture v2.2.0 This test suite validates the production Truth-First Search architecture following GDD (Graph Database Design) v2.2.0 specifications. ## Test Philosophy - Zero-Fallback Testing **The Implementor's Rule**: Test exactly what production uses - no mocks, no fallbacks. We test production architecture directly because: - MCP servers run in production environment by default - Mock systems hide integration bugs that matter in real usage - Truth-First Search requires real component interaction testing - Zero-fallback architecture needs validation of actual error paths ## Test Structure ``` tests/ ├── unit/ # Pure logic tests with real components ├── integration/ # Production component integration tests ├── e2e/ # End-to-end MCP workflow tests ├── infrastructure/ # Infrastructure component tests └── fixtures/ # Test utilities and helpers ``` ## Running Tests ```bash # Run all tests (validates production architecture) npm test # Run only unit tests (pure logic validation) npm run test:unit # Run integration tests (component interaction) npm run test:integration # Run e2e tests (complete MCP workflows) npm run test:e2e # Watch mode for development npm run test:watch # Coverage report with Truth-First metrics npm run test:coverage ``` ## Test Categories ### Unit Tests ✅ **Philosophy**: Test real components without external dependencies - `memory-entity.test.ts` - Memory domain entity validation and business rules - `observation-entity.test.ts` - Observation domain entity business logic - `id-generator.test.ts` - Compact ID generation with BASE85 encoding - `embedding-utilities.test.ts` - Vector similarity calculations - `di-container.test.ts` - **NEW**: Production DI container validation - `search-config.test.ts` - Search configuration domain rules ### Integration Tests 🔄 **Philosophy**: Test production component integration with real database connections - `truth-first-search.test.ts` - **NEW**: GDD v2.2.0 search pipeline validation - `memory-repository.test.ts` - Neo4j repository operations against real database ### E2E Tests 🎯 **Philosophy**: Test complete MCP workflows end-to-end - `mcp-handlers-production.test.ts` - **NEW**: Complete MCP handler workflow validation - `mcp-handlers.test.ts` - Legacy handler tests (maintained for compatibility) ### Infrastructure Tests ⚙️ **Philosophy**: Test infrastructure components with production validation - `clean-database-manager.test.ts` - **NEW**: Database management without mocks - `index-manager.test.ts` - Database schema and index management - `search/` - Truth-First Search component tests - `query-classifier.test.ts` - Query intent classification - `truth-scorer.test.ts` - Truth hierarchy scoring - `exact-search-channel.test.ts` - Case-insensitive exact matching - `vector-search-channel.test.ts` - Semantic similarity search - `wildcard-search-service.test.ts` - Wildcard query handling - `search-result-processor.test.ts` - Practical hybrid scoring - `truth-first-orchestrator.test.ts` - Complete search orchestration ## Test Architecture Changes (v2.2.0) ### Removed Legacy Patterns - ❌ **vi.mock()** extensive mocking that hid integration issues - ❌ **Fallback testing** that masked real error conditions - ❌ **Mock database validation** that bypassed production logic ### Added Truth-First Patterns - ✅ **Production component testing** with real dependency injection - ✅ **Zero-fallback validation** ensuring actual error paths work - ✅ **Truth hierarchy testing** validating GDD v2.2.0 search compliance - ✅ **Real validation logic testing** without mock bypasses ## Database Requirements Integration and E2E tests expect production database connectivity: - Neo4j running on configured endpoint (default: `bolt://localhost:7687`) - Valid credentials in environment variables - Write access for test data creation **Test Environment Behavior:** - Tests validate production architecture even without database - Database connection failures are expected and handled gracefully - Tests validate error handling paths when database unavailable - No fallback to mock systems - real error paths tested ## Environment Configuration ```bash # Production database configuration (tests validate against this) NEO4J_URI=bolt://localhost:7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=password NEO4J_DATABASE=neo4j LOG_LEVEL=error # Vector model configuration (tests validate model integration) VECTOR_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 VECTOR_DIMENSIONS=auto VECTOR_IDLE_TIMEOUT=600000 VECTOR_PRELOAD=true ``` ## Coverage Targets - Truth-First Metrics - **Branches**: 75% (Critical error paths must be tested) - **Functions**: 75% (All public APIs validated) - **Lines**: 75% (Core logic coverage) - **Statements**: 75% (Truth-first path coverage) ### Coverage Focus Areas 1. **Truth Hierarchy Logic** - Perfect truth detection and scoring 2. **Query Classification** - Technical identifier vs semantic query routing 3. **Zero-Fallback Paths** - Error handling without rescue mechanisms 4. **Production Integration** - Real component interaction validation 5. **MCP Handler Workflows** - Complete request/response cycles ## Performance Validation Tests validate GDD v2.2.0 performance requirements: - **Exact Search**: <100ms target validation - **Vector Search**: <500ms target validation - **Wildcard Search**: Direct query performance - **Limit Enforcement**: Strict GDD 8.1 compliance ## Migration Notes **From Legacy to Truth-First Testing:** 1. **Removed Mock Dependencies**: Tests now use real component initialization 2. **Updated Error Expectations**: Tests validate actual error paths, not mock responses 3. **Added Architecture Validation**: Tests ensure production component relationships work 4. **Enhanced Integration Coverage**: Tests validate Truth-First Search pipeline end-to-end **Breaking Changes:** - Tests expect production environment configuration - Mock-based test patterns no longer supported - Database connectivity expected for full integration validation --- *"Test the architecture you ship, ship the architecture you test."* - The Truth-First Testing Principle