@quarry-systems/drift-testing

Mock services and testing utilities for MCG (Managed Cyclic Graph) workflows.

Overview

drift-testing provides a comprehensive mock service framework for testing MCG workflows. It includes:

- Mock Service Base Classes - Extensible base for creating custom mocks
- Pre-built Mock Services - Secrets, HTTP, and more
- Call Tracking - Automatic recording of all method calls
- Fluent API - Chainable methods for easy test setup
- Behavior Configuration - Control return values, errors, and delays

Installation

``bash
npm install @quarry-systems/drift-testing --save-dev
`

Quick Start

`typescript
import { mockSecrets, mockHttp } from '@quarry-systems/drift-testing';
import { createManager } from '@quarry-systems/drift-core';

describe('My Workflow', () => {
it('should fetch data with secrets', async () => {
// Create mocks
const secrets = mockSecrets({
'API_KEY': 'test-key-123'
});

const http = mockHttp()
.getReturns('/api/data', { items: [] });

// Use in manager
const manager = createManager(myGraph, {
services: {
secrets: secrets.build(),
http: http.build()
}
});

await manager.start();

// Assert calls
expect(secrets.wasResolveCalledWith('API_KEY')).toBe(true);
expect(http.wasGetCalledWith('/api/data')).toBe(true);
});
});
`

Mock Services

$3

`typescript
import { mockSecrets } from '@quarry-systems/drift-testing';

const secrets = mockSecrets({
'DB_PASSWORD': 'test-password',
'API_KEY': 'test-key'
})
.resolveThrows('INVALID_KEY', new Error('Not found'))
.resolveDelays(100);

const service = secrets.build();

// Use in tests
await service.resolve('DB_PASSWORD'); // Returns 'test-password'
await service.resolve('INVALID_KEY'); // Throws error

// Assert calls
expect(secrets.getResolveCallCount()).toBe(2);
expect(secrets.wasResolveCalledWith('DB_PASSWORD')).toBe(true);
`

$3

`typescript
import { mockHttp } from '@quarry-systems/drift-testing';

const http = mockHttp()
.getReturns('/api/users', { users: [] })
.postReturns('/api/users', { id: 1, name: 'Test' }, 201)
.postThrows('/api/invalid', new Error('Validation failed'))
.withDelay(50);

const service = http.build();

// Use in tests
const response = await service.get('/api/users');
expect(response.status).toBe(200);

// Assert calls
expect(http.getGetCallCount()).toBe(1);
expect(http.wasPostCalledWith('/api/users')).toBe(false);
`

$3

`typescript
import { mockStore } from '@quarry-systems/drift-testing';

const store = mockStore({
'user:123': { name: 'Alice', email: 'alice@example.com' },
'config:theme': 'dark'
})
.getThrows('INVALID_KEY', new Error('Key not found'))
.withDelay(10);

const service = store.build();

// Use in tests
const user = await service.get('user:123');
expect(user).toEqual({ name: 'Alice', email: 'alice@example.com' });

await service.set('session:abc', { userId: '123' });
await service.delete('user:123');

// Assert calls
expect(store.wasGetCalledWith('user:123')).toBe(true);
expect(store.getSetCallCount()).toBe(1);
`

$3

`typescript
import { mockVectors } from '@quarry-systems/drift-testing';

const vectors = mockVectors()
.queryReturns([0.1, 0.2, 0.3], [
{ id: '1', document: 'Relevant document', score: 0.95 },
{ id: '2', document: 'Another match', score: 0.87 }
])
.insertReturns('doc-1', true)
.withDelay(50);

const service = vectors.build();

// Use in tests
const results = await service.query([0.1, 0.2, 0.3], { topK: 5 });
expect(results).toHaveLength(2);
expect(results[0].score).toBe(0.95);

await service.insert('doc-1', [0.1, 0.2, 0.3], 'New document');

// Assert calls
expect(vectors.wasQueryCalledWith([0.1, 0.2, 0.3])).toBe(true);
expect(vectors.getInsertCallCount()).toBe(1);
`

API Reference

$3

All mock services extend MockService which provides:

- getCalls() - Get all recorded calls
- getCallsFor(method) - Get calls for specific method
- getCallCount(method) - Get call count for method
- wasCalled(method) - Check if method was called
- wasCalledWith(method, ...args) - Check if called with args
- clearCalls() - Clear call history
- reset() - Reset calls and behaviors

$3

All mock builders extend MockBuilder which provides:

- build() - Get the mock service instance
- getCalls() - Get all recorded calls
- getCallsFor(method) - Get calls for specific method
- wasCalled(method) - Check if method was called
- wasCalledWith(method, ...args) - Check if called with args
- reset() - Reset mock state

$3

`typescript
import { MockService, MockBuilder } from '@quarry-systems/drift-testing';

interface MyService {
doSomething(arg: string): Promise;
}

class MockMyService extends MockService implements MyService {
async doSomething(arg: string): Promise {
return this.executeMock('doSomething', [arg], result-${arg});
}
}

class MockMyServiceBuilder extends MockBuilder {
constructor() {
const mockService = new MockMyService();
super(mockService, mockService);
}

doSomethingReturns(value: string): this {
this.setBehavior('doSomething', { returns: value });
return this;
}

doSomethingThrows(error: Error): this {
this.setBehavior('doSomething', { throws: error });
return this;
}
}

export function mockMyService(): MockMyServiceBuilder {
return new MockMyServiceBuilder();
}
`

Recording & Replay

$3

Record real service calls during execution for later replay:

`typescript
import { createRecorder } from '@quarry-systems/drift-testing';

const recorder = createRecorder();

const manager = createManager(graph, {
services: recorder.wrapServices({
secrets: mySecretsService,
http: myHttpService
})
});

await manager.start();

// Get the recording
const recording = recorder.getRecording('run-123', 'graph-456');

// Save to file
fs.writeFileSync('recording.json', recorder.toJSON());
`

$3

Replay recorded calls for deterministic testing:

`typescript
import { createReplayer, loadRecording } from '@quarry-systems/drift-testing';

// Load recording
const recording = loadRecording(fs.readFileSync('recording.json', 'utf-8'));
const replayer = createReplayer(recording);

const manager = createManager(graph, {
services: replayer.wrapServices({
secrets: mySecretsService,
http: myHttpService
})
});

await manager.start(); // Uses recorded responses

// Validate replay
const validation = replayer.getValidation();
expect(validation.valid).toBe(true);
expect(validation.callsReplayed).toBe(validation.callsExpected);
`

$3

`typescript
const recorder = createRecorder({
services: ['http'], // Only record specific services
excludeMethods: ['ping'], // Exclude certain methods
maxCalls: 1000, // Limit number of calls
recordErrors: true, // Record errors (default: true)
recordDuration: true // Record call duration (default: true)
});
`

$3

`typescript
const replayer = createReplayer(recording, {
validateSequence: true, // Validate call order (default: true)
validateArgs: true, // Validate arguments (default: true)
throwOnMismatch: false, // Throw on validation errors (default: false)
services: ['http'] // Only replay specific services
});
`

$3

Recordings are saved as JSON:

`json
{
"metadata": {
"version": "1.0.0",
"timestamp": "2025-12-27T10:00:00Z",
"runId": "run-123",
"graphId": "graph-456",
"totalCalls": 5,
"totalDuration": 1234,
"services": ["secrets", "http"]
},
"calls": [
{
"service": "secrets",
"method": "resolve",
"args": ["API_KEY"],
"result": "test-key-123",
"timestamp": 1735300800000,
"duration": 10,
"sequence": 0
}
]
}
`

Testing Patterns

$3

`typescript
const secrets = mockSecrets()
.resolveThrows('MISSING_KEY', new Error('Secret not found'));

await expect(service.resolve('MISSING_KEY')).rejects.toThrow('Secret not found');
`

$3

`typescript
const http = mockHttp()
.withDelay(1000);

const start = Date.now();
await service.get('/api/slow');
const duration = Date.now() - start;

expect(duration).toBeGreaterThan(900);
`

$3

`typescript
const secrets = mockSecrets({ 'KEY': 'value' });
const service = secrets.build();

await service.resolve('KEY');
await service.resolve('KEY');

expect(secrets.getResolveCallCount()).toBe(2);
expect(secrets.wasResolveCalledWith('KEY')).toBe(true);

const calls = secrets.getCallsFor('resolve');
expect(calls[0].args[0]).toBe('KEY');
`

$3

`typescript
// 1. Record a real execution
const recorder = createRecorder();
const manager = createManager(graph, {
services: recorder.wrapServices({ secrets, http })
});

await manager.start({ query: 'test' });
fs.writeFileSync('test-run.json', recorder.toJSON());

// 2. Replay in tests (fast and deterministic)
const recording = loadRecording(fs.readFileSync('test-run.json', 'utf-8'));
const replayer = createReplayer(recording);

const testManager = createManager(graph, {
services: replayer.wrapServices({ secrets, http })
});

await testManager.start({ query: 'test' }); // Instant, uses recorded data

const validation = replayer.getValidation();
expect(validation.valid).toBe(true);
`

Building

Run nx build drift-testing to build the library.

Running Tests

Run nx test drift-testing or npm test` to execute the unit tests via Vitest.

Documentation

For more examples and detailed documentation, see the examples directory.

License

Dual-licensed under AGPL-3.0 and Commercial License. See LICENSE files for details.