README

Research and recommendations for testing the Lattice CLI tool - a knowledge graph for markdown documentation.

Documents

Key Takeaways

Testing Architecture

1. Testing Layers approach: Unit (70%), Integration (25%), E2E (5%)
2. Extract pure functions from services for mock-free unit testing
3. Use NestJS Test.createTestingModule() with overrideProvider() instead of manual construction

Design Patterns for Testability

1. Functional Core, Imperative Shell - Separate pure logic from I/O
2. Ports and Adapters - Swappable dependencies (already used for embeddings)
3. Command Query Separation - Methods do one thing

TDD Workflow

1. TDD works best at unit level with pure functions (zero mock setup)
2. Use NestJS testing module for service-level TDD
3. Avoid the “mock setup tax” that kills TDD momentum

Quick Reference

What to Mock

• External APIs (Voyage AI, OpenAI)
• FalkorDB (unless using Testcontainers)
• Non-deterministic values (time, random)

What NOT to Mock

• Pure functions (extract and test directly)
• File I/O (use temp directories)
• Built-in mock providers (use MockEmbeddingProvider)
• Data structures and value objects

NestJS Testing Pattern

const module = await Test.createTestingModule({
    imports: [SyncModule],
})
.overrideProvider(GraphService)
.useValue(mockGraphService)
.compile();

Related Topics

• NestJS testing patterns with dependency injection
• Testcontainers for Docker-based integration testing
• Functional Core / Imperative Shell pattern
• Test-Driven Development workflow