Test Doubles: Mocks, Stubs, Fakes

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

// Interface for the dependency we'll mock
interface NotificationService {
    sendEmail(to: string, subject: string, body: string): void;
    sendSms(to: string, message: string): void;
    sendPush(userId: string, notification: PushNotification): void;
}
 
// Hand-coded mock for educational purposes
class MockNotificationService implements NotificationService {
    // Record all calls
    private emailCalls: { to: string; subject: string; body: string }[] = [];
    private smsCalls: { to: string; message: string }[] = [];
    private pushCalls: { userId: string; notification: PushNotification }[] = [];
    
    // Implementation records the call
    sendEmail(to: string, subject: string, body: string): void {
        this.emailCalls.push({ to, subject, body });
    }
    
    sendSms(to: string, message: string): void {
        this.smsCalls.push({ to, message });
    }
    
    sendPush(userId: string, notification: PushNotification): void {
        this.pushCalls.push({ userId, notification });
    }
    
    // Verification methods
    verifyEmailSent(to: string, subject: string): void {
        const found = this.emailCalls.some(
            call => call.to === to && call.subject === subject
        );
        if (!found) {
            throw new Error(
                `Expected email to ${to} with subject "${subject}" was not sent.\n` +
                `Actual calls: ${JSON.stringify(this.emailCalls)}`
            );
        }
    }
    
    verifyNoEmailsSent(): void {
        if (this.emailCalls.length > 0) {
            throw new Error(
                `Expected no emails but ${this.emailCalls.length} were sent`
            );
        }
    }
    
    verifyEmailCount(expected: number): void {
        if (this.emailCalls.length !== expected) {
            throw new Error(
                `Expected ${expected} emails but ${this.emailCalls.length} were sent`
            );
        }
    }
    
    // Get recorded calls for complex assertions
    getEmailCalls() { return [...this.emailCalls]; }
    getSmsCalls() { return [...this.smsCalls]; }
    getPushCalls() { return [...this.pushCalls]; }
}
 
// Test using the mock
describe('OrderProcessor', () => {
    it('should send confirmation email when order completes', () => {
        // ARRANGE: Create mock and set up the system
        const notificationMock = new MockNotificationService();
        const processor = new OrderProcessor(notificationMock);
        
        const order: Order = {
            id: 'order-123',
            customerEmail: 'customer@example.com',
            items: [{ product: 'Widget', quantity: 2 }],
        };
        
        // ACT: Execute the behavior
        processor.completeOrder(order);
        
        // ASSERT: Verify the mock received expected calls
        notificationMock.verifyEmailSent(
            'customer@example.com',
            'Order Confirmation: order-123'
        );
    });
    
    it('should not send email for cancelled orders', () => {
        const notificationMock = new MockNotificationService();
        const processor = new OrderProcessor(notificationMock);
        
        const order: Order = { id: 'order-456', status: 'CANCELLED', ... };
        
        processor.handleOrder(order);
        
        // Verify NO interaction occurred
        notificationMock.verifyNoEmailsSent();
    });
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

// USE CASE 1: Verifying side effects (notification sent)
describe('PasswordResetService', () => {
    it('should send reset email with token', () => {
        const emailMock = new MockEmailService();
        const tokenService = new StubTokenService().willGenerate('token-abc-123');
        
        const service = new PasswordResetService(emailMock, tokenService);
        
        service.initiateReset('user@example.com');
        
        // Verify the side effect occurred correctly
        emailMock.verifySentTo('user@example.com');
        emailMock.verifyBodyContains('token-abc-123');
    });
});
 
// USE CASE 2: Verifying correct arguments are passed
describe('AuditLogger', () => {
    it('should log user actions with correct details', () => {
        const auditMock = new MockAuditStore();
        const logger = new AuditLogger(auditMock);
        
        logger.logAction({
            userId: 'user-1',
            action: 'DELETE_ACCOUNT',
            resourceId: 'account-789',
            timestamp: new Date('2024-01-15T10:30:00Z'),
        });
        
        // Verify correct data was passed to audit store
        auditMock.verifyRecordedWith({
            userId: 'user-1',
            action: 'DELETE_ACCOUNT',
            resourceId: 'account-789',
        });
    });
});
 
// USE CASE 3: Verifying calls are NOT made (conditional behavior)
describe('EmailThrottler', () => {
    it('should not send email when rate limit exceeded', () => {
        const emailMock = new MockEmailService();
        const rateLimiter = new StubRateLimiter().willReturnLimitExceeded();
        
        const throttler = new EmailThrottler(emailMock, rateLimiter);
        
        throttler.trySendEmail('user@example.com', 'Subject', 'Body');
        
        // Verify email was NOT sent
        emailMock.verifyNeverCalled();
    });
});
 
// USE CASE 4: Verifying call order
describe('TransactionProcessor', () => {
    it('should validate before committing', () => {
        const dbMock = new MockDatabase();
        const processor = new TransactionProcessor(dbMock);
        
        processor.execute(transaction);
        
        // Verify correct sequence
        dbMock.verifyCallOrder([
            'beginTransaction',
            'validate',
            'persist',
            'commit',
        ]);
    });
    
    it('should rollback on validation failure', () => {
        const dbMock = new MockDatabase();
        const validator = new StubValidator().willFail();
        const processor = new TransactionProcessor(dbMock, validator);
        
        processor.execute(invalidTransaction);
        
        // Verify rollback was called, NOT commit
        dbMock.verifyCallOrder([
            'beginTransaction',
            'validate',
            'rollback',
        ]);
        dbMock.verifyNeverCalled('commit');
    });
});
 
// USE CASE 5: Verifying event publishing
describe('OrderService', () => {
    it('should publish OrderCompleted event', () => {
        const eventBusMock = new MockEventBus();
        const orderService = new OrderService(eventBusMock);
        
        orderService.completeOrder(order);
        
        // Verify correct event was published
        eventBusMock.verifyPublished(
            OrderCompletedEvent,
            event => event.orderId === order.id && 
                     event.customerId === order.customerId
        );
    });
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

// Pattern 1: Recording Mock
// Records all calls and provides verification methods
 
interface EventPublisher {
    publish<T>(event: T): void;
    publishAll<T>(events: T[]): void;
}
 
class RecordingMockEventPublisher implements EventPublisher {
    private calls: Array<{ method: string; args: unknown[] }> = [];
    
    publish<T>(event: T): void {
        this.calls.push({ method: 'publish', args: [event] });
    }
    
    publishAll<T>(events: T[]): void {
        this.calls.push({ method: 'publishAll', args: [events] });
    }
    
    // Verification: Was this event type published?
    verifyPublished<T>(eventType: new (...args: any[]) => T): void {
        const found = this.calls.some(call =>
            call.method === 'publish' && call.args[0] instanceof eventType
        );
        if (!found) {
            throw new Error(`Expected event of type ${eventType.name} was not published`);
        }
    }
    
    // Verification: Was this specific event published?
    verifyPublishedMatching<T>(predicate: (event: T) => boolean): void {
        const found = this.calls.some(call =>
            call.method === 'publish' && predicate(call.args[0] as T)
        );
        if (!found) {
            throw new Error('No published event matched the predicate');
        }
    }
    
    // Verification: Exact call count
    verifyPublishCalledTimes(expected: number): void {
        const actual = this.calls.filter(c => c.method === 'publish').length;
        if (actual !== expected) {
            throw new Error(`Expected ${expected} publish calls, got ${actual}`);
        }
    }
    
    // Get all calls for complex custom verification
    getCalls() {
        return [...this.calls];
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

// Pattern 2: Expectation Mock
// Set up expectations before execution, verify they were met
 
class ExpectationMockLogger implements Logger {
    private expectations: Array<{
        method: string;
        argMatcher: (args: unknown[]) => boolean;
        satisfied: boolean;
    }> = [];
    
    private calls: Array<{ method: string; args: unknown[] }> = [];
    
    // Set up expectations
    expectLogInfo(messageMatcher: (msg: string) => boolean): this {
        this.expectations.push({
            method: 'info',
            argMatcher: (args) => messageMatcher(args[0] as string),
            satisfied: false,
        });
        return this;
    }
    
    expectLogError(messageMatcher: (msg: string) => boolean): this {
        this.expectations.push({
            method: 'error',
            argMatcher: (args) => messageMatcher(args[0] as string),
            satisfied: false,
        });
        return this;
    }
    
    // Implementation marks expectations as satisfied
    info(message: string): void {
        this.calls.push({ method: 'info', args: [message] });
        this.satisfyMatchingExpectations('info', [message]);
    }
    
    error(message: string): void {
        this.calls.push({ method: 'error', args: [message] });
        this.satisfyMatchingExpectations('error', [message]);
    }
    
    private satisfyMatchingExpectations(method: string, args: unknown[]): void {
        for (const exp of this.expectations) {
            if (exp.method === method && exp.argMatcher(args)) {
                exp.satisfied = true;
            }
        }
    }
    
    // Verify all expectations were met
    verifyAllExpectations(): void {
        const unsatisfied = this.expectations.filter(e => !e.satisfied);
        if (unsatisfied.length > 0) {
            throw new Error(
                `Unsatisfied expectations: ${unsatisfied.length}\n` +
                `Actual calls: ${JSON.stringify(this.calls)}`
            );
        }
    }
}
 
// Usage
describe('PaymentProcessor', () => {
    it('should log payment attempts', () => {
        const loggerMock = new ExpectationMockLogger()
            .expectLogInfo(msg => msg.includes('Processing payment'))
            .expectLogInfo(msg => msg.includes('Payment successful'));
        
        const processor = new PaymentProcessor(loggerMock);
        
        processor.processPayment(100, 'USD');
        
        loggerMock.verifyAllExpectations();  // Fails if any expectation not met
    });
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

// Pattern 3: Strict Mock
// Fails immediately on unexpected calls
 
class StrictMockPaymentGateway implements PaymentGateway {
    private allowedMethods: Set<string> = new Set();
    
    // Configure which methods are allowed
    allowProcessPayment(): this {
        this.allowedMethods.add('processPayment');
        return this;
    }
    
    allowRefund(): this {
        this.allowedMethods.add('refund');
        return this;
    }
    
    processPayment(amount: number, currency: string): PaymentResult {
        if (!this.allowedMethods.has('processPayment')) {
            throw new Error(
                'Unexpected call to processPayment. ' +
                'Did you forget to set up this expectation?'
            );
        }
        return { success: true, transactionId: 'txn-mock' };
    }
    
    refund(transactionId: string): RefundResult {
        if (!this.allowedMethods.has('refund')) {
            throw new Error(
                'Unexpected call to refund. ' +
                'Did you forget to set up this expectation?'
            );
        }
        return { success: true, refundId: 'ref-mock' };
    }
}
 
// Usage - test will FAIL if unauthorized method is called
describe('OrderService', () => {
    it('should only process payment, never refund, for new orders', () => {
        const paymentMock = new StrictMockPaymentGateway()
            .allowProcessPayment();  // Only this method is allowed
        
        const service = new OrderService(paymentMock);
        
        // If OrderService accidentally calls refund(), test fails immediately
        service.createOrder(order);
    });
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

import { describe, it, expect, vi, beforeEach } from 'vitest';
 
describe('OrderProcessor with Vitest mocks', () => {
    // Create typed mock from interface
    const emailService: EmailService = {
        sendConfirmation: vi.fn(),
        sendShippingNotification: vi.fn(),
        sendCancellation: vi.fn(),
    };
    
    beforeEach(() => {
        // Reset mock between tests
        vi.clearAllMocks();
    });
    
    it('should send confirmation email with order details', () => {
        const processor = new OrderProcessor(emailService);
        const order: Order = {
            id: 'order-123',
            customerEmail: 'alice@example.com',
            total: 149.99,
        };
        
        processor.completeOrder(order);
        
        // Verify the mock was called correctly
        expect(emailService.sendConfirmation).toHaveBeenCalledTimes(1);
        expect(emailService.sendConfirmation).toHaveBeenCalledWith(
            'alice@example.com',
            expect.objectContaining({
                orderId: 'order-123',
                total: 149.99,
            })
        );
    });
    
    it('should send shipping notification when order ships', () => {
        const processor = new OrderProcessor(emailService);
        const order = { id: 'order-456', customerEmail: 'bob@example.com' };
        const trackingNumber = 'TRACK-789';
        
        processor.shipOrder(order, trackingNumber);
        
        expect(emailService.sendShippingNotification).toHaveBeenCalledWith(
            'bob@example.com',
            expect.objectContaining({
                trackingNumber: 'TRACK-789',
            })
        );
    });
    
    it('should not send any email for draft orders', () => {
        const processor = new OrderProcessor(emailService);
        const draftOrder = { id: 'order-789', status: 'DRAFT' };
        
        processor.handleOrder(draftOrder);
        
        // Verify NO emails sent
        expect(emailService.sendConfirmation).not.toHaveBeenCalled();
        expect(emailService.sendShippingNotification).not.toHaveBeenCalled();
        expect(emailService.sendCancellation).not.toHaveBeenCalled();
    });
});
 
// Advanced: Verifying call arguments in detail
describe('AuditService with detailed verification', () => {
    it('should log audit event with timestamp and user context', () => {
        const auditStore = {
            record: vi.fn(),
        };
        const service = new AuditService(auditStore);
        
        service.logUserAction('user-1', 'LOGIN', { ip: '192.168.1.1' });
        
        // Detailed argument verification
        expect(auditStore.record).toHaveBeenCalledWith(
            expect.objectContaining({
                userId: 'user-1',
                action: 'LOGIN',
                metadata: expect.objectContaining({ ip: '192.168.1.1' }),
                timestamp: expect.any(Date),
            })
        );
    });
});
 
// Verifying call order
describe('TransactionManager', () => {
    it('should begin before commit', () => {
        const db = {
            beginTransaction: vi.fn(),
            commit: vi.fn(),
            rollback: vi.fn(),
        };
        
        const manager = new TransactionManager(db);
        manager.executeInTransaction(() => { /* work */ });
        
        // Get call order
        const beginOrder = db.beginTransaction.mock.invocationCallOrder[0];
        const commitOrder = db.commit.mock.invocationCallOrder[0];
        
        expect(beginOrder).toBeLessThan(commitOrder);
    });
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

// VERIFICATION STRATEGY 1: Exact Verification
// Use when the exact interaction is part of the contract
 
it('should call API with exact payload structure', () => {
    const apiMock = vi.fn();
    const client = new ApiClient(apiMock);
    
    client.createUser({ name: 'Alice', email: 'alice@test.com' });
    
    // Exact verification - any difference fails
    expect(apiMock).toHaveBeenCalledWith({
        method: 'POST',
        endpoint: '/users',
        body: {
            name: 'Alice',
            email: 'alice@test.com',
        },
        headers: {
            'Content-Type': 'application/json',
        },
    });
});
 
// VERIFICATION STRATEGY 2: Partial Verification
// Use when some fields are essential, others are implementation details
 
it('should include userId in audit log', () => {
    const auditMock = vi.fn();
    const service = new AuditService(auditMock);
    
    service.logAction('user-123', 'DELETE_FILE', '/path/to/file');
    
    // Only verify what matters - timestamp is an implementation detail
    expect(auditMock).toHaveBeenCalledWith(
        expect.objectContaining({
            userId: 'user-123',
            action: 'DELETE_FILE',
        })
    );
});
 
// VERIFICATION STRATEGY 3: Argument Matchers
// Use for dynamic or unpredictable values
 
it('should publish event with generated ID', () => {
    const eventBusMock = vi.fn();
    const publisher = new EventPublisher(eventBusMock);
    
    publisher.publishOrderCreated(order);
    
    expect(eventBusMock).toHaveBeenCalledWith(
        expect.objectContaining({
            type: 'ORDER_CREATED',
            orderId: order.id,
            eventId: expect.stringMatching(/^evt-[a-z0-9]+$/),  // Pattern match
            timestamp: expect.any(Date),
        })
    );
});
 
// VERIFICATION STRATEGY 4: Call Count Verification
// Verify exact, minimum, or maximum call counts
 
it('should only process each item once', () => {
    const processorMock = vi.fn();
    const batch = new BatchProcessor(processorMock);
    
    batch.process(['a', 'b', 'c']);
    
    expect(processorMock).toHaveBeenCalledTimes(3);  // Exactly 3
});
 
it('should retry failed items', () => {
    const processorMock = vi.fn()
        .mockRejectedValueOnce(new Error('Fail'))
        .mockResolvedValue('ok');
    
    const batch = new RetryingProcessor(processorMock, { maxRetries: 3 });
    
    await batch.process(['item']);
    
    // At least 2 calls (original + 1 retry)
    expect(processorMock.mock.calls.length).toBeGreaterThanOrEqual(2);
});
 
// VERIFICATION STRATEGY 5: Never Called Verification
// Critical for testing conditional logic
 
it('should not notify when user has opted out', () => {
    const notifierMock = vi.fn();
    const preferences = new StubPreferences().userOptedOut();
    
    const service = new NotificationService(notifierMock, preferences);
    service.notifyUser('user-123', 'Hello');
    
    expect(notifierMock).not.toHaveBeenCalled();
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

// ❌ PITFALL 1: Over-specification
// This test is too strict - any small change breaks it
 
it('BAD: verifies too many details', () => {
    const repo = vi.fn();
    const logger = vi.fn();
    const service = new UserService(repo, logger);
    
    service.createUser({ name: 'Alice' });
    
    // Verifying EVERYTHING - way too specific
    expect(repo).toHaveBeenCalledTimes(1);
    expect(repo).toHaveBeenCalledWith('INSERT', 'users', { name: 'Alice' });
    expect(logger).toHaveBeenCalledTimes(2);
    expect(logger).toHaveBeenNthCalledWith(1, 'debug', 'Creating user');
    expect(logger).toHaveBeenNthCalledWith(2, 'info', 'User created');
});
 
// ✅ BETTER: Verify what matters
it('GOOD: verifies essential behavior', () => {
    const repo = vi.fn();
    const service = new UserService(repo, new NoOpLogger());
    
    service.createUser({ name: 'Alice' });
    
    // Only verify the important interaction
    expect(repo).toHaveBeenCalledWith(
        expect.anything(),  // Don't care about internal SQL
        'users',
        expect.objectContaining({ name: 'Alice' })
    );
});
 
// ❌ PITFALL 2: Implementation coupling
// Test breaks when implementation changes, even if behavior is correct
 
it('BAD: tests implementation not behavior', () => {
    const cache = vi.fn();
    const db = vi.fn().mockReturnValue({ id: 1, name: 'Alice' });
    const service = new CachedUserService(cache, db);
    
    service.getUser(1);
    
    // This tests the caching strategy - implementation detail
    expect(cache).toHaveBeenCalledWith('get', 'user:1');
    expect(db).toHaveBeenCalledTimes(1);
    expect(cache).toHaveBeenCalledWith('set', 'user:1', expect.anything());
});
 
// ✅ BETTER: Test observable behavior
it('GOOD: tests that correct user is returned', () => {
    // Use a fake cache + stub DB, don't mock the interactions
    const fakeCache = new InMemoryCache();
    const stubDb = { getUser: () => ({ id: 1, name: 'Alice' }) };
    const service = new CachedUserService(fakeCache, stubDb);
    
    const user = service.getUser(1);
    
    expect(user.name).toBe('Alice');  // Test BEHAVIOR
});
 
// ❌ PITFALL 3: Mocking what you don't own
// axios internals might change between versions
 
import axios from 'axios';
vi.mock('axios');
 
it('BAD: mocks third-party library internals', () => {
    (axios.get as any).mockResolvedValue({ data: { name: 'Alice' } });
    
    const client = new ApiClient();
    const user = await client.getUser(1);
    
    expect(axios.get).toHaveBeenCalledWith('/users/1');  // Coupled to axios API
});
 
// ✅ BETTER: Create your own interface and mock THAT
interface HttpClient {
    get<T>(url: string): Promise<T>;
}
 
it('GOOD: mocks your own abstraction', () => {
    const httpMock: HttpClient = {
        get: vi.fn().mockResolvedValue({ name: 'Alice' }),
    };
    
    const client = new ApiClient(httpMock);
    const user = await client.getUser(1);
    
    expect(httpMock.get).toHaveBeenCalledWith('/users/1');
});