testing-strategy

// Brittle: Tests HOW the code works
const cypher = calls[calls.length - 1][2];
expect(cypher).toContain("MERGE");
expect(cypher).toContain("TypeScript");

service = new SyncService(
    mockManifest as unknown as ManifestService,
    mockParser as unknown as DocumentParserService,
    mockGraph as unknown as GraphService,
    // ...
);

try {
    await command.run([], {});
} catch (e) {
    // Expected - process.exit mock throws
}

it('should detect entity type inconsistencies', () => {
    const issues: any[] = [];
    const entityTypes = new Map<string, string>();
    // Tests reimplemented logic, not the actual command
});

┌─────────────────────────────────────────────────────────┐
│                    E2E Tests (5%)                       │
│    Full CLI invocation, real/containerized services     │
├─────────────────────────────────────────────────────────┤
│               Integration Tests (25%)                   │
│    Service combinations with real file I/O, mocked DB   │
├─────────────────────────────────────────────────────────┤
│                 Unit Tests (70%)                        │
│    Pure functions, isolated logic, minimal mocking      │
└─────────────────────────────────────────────────────────┘

// BEFORE: Over-mocked
const mockEmbeddingService = {
    generateEmbedding: mock(() => [0.1, 0.2, 0.3]),
    getDimensions: mock(() => 1536),
};

// AFTER: Use real service with mock provider
const mockConfig = {
    get: (key: string) => ({
        EMBEDDING_PROVIDER: 'mock',
        EMBEDDING_DIMENSIONS: 1536,
    }[key]),
};
const embeddingService = new EmbeddingService(mockConfig);
// Now you get deterministic embeddings that are ACTUALLY normalized!

src/
├── pure/
│   ├── cypher.ts         # escapeCypher, buildCypher functions
│   ├── embedding-text.ts # composeEmbeddingText functions
│   ├── validation.ts     # validateDocuments (already exported!)
│   └── hashing.ts        # getContentHash (move from ManifestService)

// Change commands to return exit codes instead of calling process.exit
class SyncCommand {
    async run(args: string[], opts: Options): Promise<number> {
        // ... logic ...
        return 0;  // Success
    }
}

// main.ts handles the actual exit
const exitCode = await command.run(args, opts);
process.exit(exitCode);

// Tests become cleaner
it('should sync successfully', async () => {
    const exitCode = await command.run([], {});
    expect(exitCode).toBe(0);
});

// 80+ lines of manual mock setup per test file
const mockGraph = createMockGraphService();
const mockManifest = createMockManifestService();
const mockParser = createMockDocumentParserService();

service = new SyncService(
    mockManifest as unknown as ManifestService,  // Type casting!
    mockParser as unknown as DocumentParserService,
    mockGraph as unknown as GraphService,
);

import { Test, TestingModule } from '@nestjs/testing';

describe('SyncService', () => {
    let service: SyncService;
    let graphService: GraphService;

    beforeEach(async () => {
        const module: TestingModule = await Test.createTestingModule({
            imports: [SyncModule],
        })
        .overrideProvider(GraphService)
        .useValue({
            upsertNode: mock(() => Promise.resolve()),
            query: mock(() => Promise.resolve({ resultSet: [] })),
            deleteNode: mock(() => Promise.resolve()),
        })
        .overrideProvider(ConfigService)
        .useValue({
            get: (key: string) => ({
                EMBEDDING_PROVIDER: 'mock',  // Use real EmbeddingService with MockProvider!
                FALKORDB_HOST: 'localhost',
            }[key]),
        })
        .compile();

        service = module.get(SyncService);
        graphService = module.get(GraphService);
    });
});

const module = await Test.createTestingModule({
    imports: [SyncModule],
})
// Mock external database
.overrideProvider(GraphService)
.useValue(createMockGraphService())
// Use REAL EmbeddingService with mock provider (built-in!)
.overrideProvider(ConfigService)
.useValue({ get: () => 'mock' })  // Forces MockEmbeddingProvider
// ManifestService, DocumentParserService stay REAL
.compile();

// Bun-compatible pattern
.overrideProvider(GraphService)
.useValue(createMockGraphService())  // Your existing factory works!

┌──────────────────────────────────────────────────┐
│           Imperative Shell (Service)              │
│   • Handles I/O, async, side effects             │
│   • Thin orchestration layer                     │
│   • Requires mocking for unit tests              │
│                                                   │
│   ┌────────────────────────────────────────┐     │
│   │         Functional Core                 │     │
│   │   • Pure functions                      │     │
│   │   • All business logic                  │     │
│   │   • Zero mocks needed!                  │     │
│   └────────────────────────────────────────┘     │
└──────────────────────────────────────────────────┘

// FUNCTIONAL CORE - pure, testable without mocks
export function buildSyncPlan(
    diskDocs: string[],
    manifestDocs: string[]
): { toAdd: string[], toDelete: string[], toUpdate: string[] } {
    // Pure logic - easy to test!
}

// IMPERATIVE SHELL - thin orchestration
class SyncService {
    async sync() {
        const diskDocs = await this.parser.discoverDocuments();  // I/O
        const manifestDocs = this.manifest.getTrackedPaths();    // I/O
        const plan = buildSyncPlan(diskDocs, manifestDocs);      // PURE!
        for (const path of plan.toAdd) {
            await this.syncDocument(path);                        // I/O
        }
    }
}

// Port (interface)
interface EmbeddingProvider {
    generateEmbedding(text: string): Promise<number[]>;
}

// Adapters (swappable implementations)
class VoyageProvider implements EmbeddingProvider { ... }   // Production
class OpenAIProvider implements EmbeddingProvider { ... }   // Alternative
class MockProvider implements EmbeddingProvider { ... }     // Testing!

// GOOD - Separated
async sync(): Promise<void> { }           // Command: changes state
async getStats(): Promise<Stats> { }      // Query: returns data

// BAD - Mixed
async syncAndReturnStats(): Promise<Stats> { }  // Does both

Red    → Write test for pure function (no mocks needed!)
Green  → Implement the function
Refactor → Clean up

// Before you write ANY test, you need 50+ lines of setup:
const mockManifest = createMockManifestService();
const mockParser = createMockDocumentParserService();
const mockGraph = createMockGraphService();
// ... This kills TDD momentum!

// 1. RED - Write failing test (no mocks!)
describe('escapeCypher', () => {
    it('should escape newlines', () => {
        expect(escapeCypher('line1\nline2')).toBe('line1\\nline2');
    });
});

// 2. GREEN - Implement
export function escapeCypher(value: string): string {
    return value
        .replace(/\\/g, '\\\\')
        .replace(/'/g, "\\'")
        .replace(/\n/g, '\\n');  // Added!
}

// 3. REFACTOR - Clean up if needed

// ERROR: Type '{ upsertNode: Mock<Promise<void>>; }' is missing properties
.overrideProvider(GraphService)
.useValue({
    upsertNode: mock(() => Promise.resolve()),
    // Missing: query, deleteNode, connect, disconnect... 20+ methods
})

import { mockDeep, DeepMockProxy } from '@tkoehlerlg/bun-mock-extended';
import { Test, TestingModule } from '@nestjs/testing';

describe('SyncService', () => {
    let service: SyncService;
    let graphService: DeepMockProxy<GraphService>;

    beforeEach(async () => {
        graphService = mockDeep<GraphService>();

        const module: TestingModule = await Test.createTestingModule({
            imports: [SyncModule],
        })
        .overrideProvider(GraphService)
        .useValue(graphService)  // Type-safe! No cast needed
        .compile();

        service = module.get(SyncService);
    });

    it('should sync document', async () => {
        // Type-safe: calledWith validates argument types
        graphService.upsertNode
            .calledWith('Document', expect.objectContaining({ title: 'Test' }))
            .mockResolvedValue(undefined);

        await service.syncDocument(testDoc);

        expect(graphService.upsertNode).toHaveBeenCalled();
    });
});

import { mock, mockDeep, DeepMockProxy } from 'jest-mock-extended';

// Shallow mock - only top-level methods
const userService = mock<UserService>();

// Deep mock - nested objects also mocked
const graphService = mockDeep<GraphService>();
graphService.deepProp.getNumber.calledWith(1).mockReturnValue(4);

// test file
import { createTypedMock } from './types/testing';

const mockGraphService = createTypedMock<GraphService>({
    upsertNode: mock(() => Promise.resolve()),
    query: mock(() => Promise.resolve({ resultSet: [] })),
    // Only mock what you need - other methods are undefined
});

interface GraphServicePort {
    upsertNode(label: string, props: object): Promise<void>;
    query(cypher: string): Promise<QueryResult>;
}

// Create mock that satisfies the interface
const createMockGraphService = (): GraphServicePort => ({
    upsertNode: mock(() => Promise.resolve()),
    query: mock(() => Promise.resolve({ resultSet: [] })),
});

// Use in NestJS
.overrideProvider(GRAPH_SERVICE_TOKEN)  // Use token-based injection
.useValue(createMockGraphService())

// The golden pattern for Lattice
import { mockDeep } from '@tkoehlerlg/bun-mock-extended';

beforeEach(async () => {
    const module = await Test.createTestingModule({
        imports: [SyncModule],
    })
    .overrideProvider(GraphService)
    .useValue(mockDeep<GraphService>())
    .overrideProvider(ConfigService)
    .useValue({
        get: (key: string) => ({ EMBEDDING_PROVIDER: 'mock' }[key]),
    })
    .compile();
});