DIP & Testability - Learning Module

Loading content...

0/246

Isolating Units for Testing

The Isolation Imperative

Unit testing is perhaps the most misunderstood practice in software development. Many teams believe they're writing unit tests when they're actually writing integration tests disguised as unit tests—tests that exercise multiple components, hit databases, make network calls, and take seconds to run. True unit tests are something different entirely: they test one unit of behavior in complete isolation.

The Dependency Inversion Principle is what makes this isolation possible. Without DIP, components are welded together—testing one necessarily tests all its dependencies. With DIP, components are connected through abstractions that can be severed at will, allowing each piece to be tested independently. This page explores the art and science of unit isolation through DIP-compliant design.

What You Will Learn

By the end of this page, you will understand what true unit isolation means, how DIP enables hermetic testing boundaries, patterns for isolating complex dependency graphs, the distinction between unit and integration testing, and strategies for managing test boundaries as systems evolve.

Defining Unit Isolation

Before we can achieve unit isolation, we must first understand what it means. Unit isolation refers to testing a single unit of code—typically a class or function—without involving any of its real collaborators. The unit under test operates in a controlled environment where every external interaction is mediated by test doubles.

What constitutes a 'unit'?

This is a subject of ongoing debate in the testing community, but a practical definition emerges from DIP thinking: a unit is a cohesive piece of behavior that depends on abstractions rather than concretions. By this definition:

Characteristics of a Testable Unit

•Single responsibility — The unit does one thing well. If testing requires verifying multiple unrelated behaviors, the unit may be too large.
•Clear boundaries — The unit has explicit dependencies received through its public interface (constructor, method parameters).
•Abstract dependencies — The unit depends on interfaces, not concrete implementations. This is DIP compliance.
•Deterministic behavior — Given the same inputs and mock behaviors, the unit produces the same outputs every time.
•No hidden state — The unit doesn't secretly access global state, singletons, or static mutable data that would affect behavior.

The isolation test:

A simple heuristic for evaluating unit isolation: Can you test this unit on an airplane? With no network connection, no database, no file system access—just the code and its test doubles. If the answer is yes, you have true unit isolation. If the answer is no, you have dependencies that need to be inverted.

Isolation Is Not Optional

Unit isolation isn't a nice-to-have—it's the difference between tests that provide reliable, fast feedback and tests that become a maintenance burden. Isolated tests run in milliseconds, never flake due to network issues, and pinpoint exactly where failures occur. Non-isolated tests run slowly, fail randomly, and obscure the source of problems.

The Hermetic Testing Model

Hermetic testing is a model where tests are completely sealed off from the external world. The term comes from 'hermetically sealed'—nothing gets in or out. In a hermetic test:

No network calls leave the test process
No disk I/O occurs (except in controlled, temporary locations)
No shared state exists between tests
No external services are contacted
Time, random numbers, and other sources of non-determinism are controlled

DIP is the architectural foundation of hermetic testing. By ensuring all dependencies are abstract and injected, you create seams—points where real behavior can be replaced with controlled behavior.

HermeticTestingExample
TypeScript
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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
// ✅ Hermetic test design through DIP
 
// Abstractions for all external interactions
interface Clock {
    now(): Date;
}
 
interface RandomGenerator {
    nextInt(max: number): number;
    nextUuid(): string;
}
 
interface HttpClient {
    get(url: string): Promise<HttpResponse>;
    post(url: string, body: object): Promise<HttpResponse>;
}
 
interface FileSystem {
    readFile(path: string): Promise<string>;
    writeFile(path: string, content: string): Promise<void>;
}
 
// Class with all non-determinism abstracted away
class SessionManager {
    constructor(
        private readonly clock: Clock,
        private readonly random: RandomGenerator,
        private readonly httpClient: HttpClient,
        private readonly fileSystem: FileSystem
    ) {}
    
    async createSession(userId: string): Promise<Session> {
        const sessionId = this.random.nextUuid();
        const createdAt = this.clock.now();
        const expiresAt = new Date(createdAt.getTime() + 3600000); // 1 hour
        
        const session: Session = {
            id: sessionId,
            userId,
            createdAt,
            expiresAt,
            token: this.generateToken()
        };
        
        // Validate user with external service
        await this.validateUser(userId);
        
        // Persist session
        await this.fileSystem.writeFile(
            `/sessions/${sessionId}.json`,
            JSON.stringify(session)
        );
        
        return session;
    }
    
    private generateToken(): string {
        const bytes = Array.from({ length: 32 }, () => 
            this.random.nextInt(256)
        );
        return bytes.map(b => b.toString(16).padStart(2, '0')).join('');
    }
    
    private async validateUser(userId: string): Promise<void> {
        const response = await this.httpClient.get(
            `https://auth.example.com/users/${userId}/validate`
        );
        if (response.status !== 200) {
            throw new Error('User validation failed');
        }
    }
}
 
// Hermetic test mocks - complete control over all external factors
class FixedClock implements Clock {
    constructor(private readonly fixedTime: Date) {}
    
    now(): Date {
        return new Date(this.fixedTime.getTime());
    }
}
 
class PredictableRandom implements RandomGenerator {
    private intSequence: number[];
    private uuidSequence: string[];
    private intIndex = 0;
    private uuidIndex = 0;
    
    constructor(ints: number[], uuids: string[]) {
        this.intSequence = ints;
        this.uuidSequence = uuids;
    }
    
    nextInt(max: number): number {
        return this.intSequence[this.intIndex++ % this.intSequence.length] % max;
    }
    
    nextUuid(): string {
        return this.uuidSequence[this.uuidIndex++ % this.uuidSequence.length];
    }
}
 
class InMemoryFileSystem implements FileSystem {
    private files = new Map<string, string>();
    
    async readFile(path: string): Promise<string> {
        const content = this.files.get(path);
        if (!content) throw new Error(`File not found: ${path}`);
        return content;
    }
    
    async writeFile(path: string, content: string): Promise<void> {
        this.files.set(path, content);
    }
    
    // Test helper
    getStoredFiles(): Map<string, string> {
        return new Map(this.files);
    }
}
 
class MockHttpClient implements HttpClient {
    private responses = new Map<string, HttpResponse>();
    private recordedRequests: { method: string; url: string; body?: object }[] = [];
    
    setResponse(url: string, response: HttpResponse): void {
        this.responses.set(url, response);
    }
    
    async get(url: string): Promise<HttpResponse> {
        this.recordedRequests.push({ method: 'GET', url });
        return this.responses.get(url) || { status: 500, body: 'No mock response' };
    }
    
    async post(url: string, body: object): Promise<HttpResponse> {
        this.recordedRequests.push({ method: 'POST', url, body });
        return this.responses.get(url) || { status: 500, body: 'No mock response' };
    }
    
    getRecordedRequests() {
        return [...this.recordedRequests];
    }
}
 
// Hermetic test - completely isolated and deterministic
describe('SessionManager (hermetic)', () => {
    it('creates session with predictable values', async () => {
        // Arrange: Complete control over all external factors
        const fixedTime = new Date('2024-01-15T10:00:00Z');
        const mockClock = new FixedClock(fixedTime);
        const mockRandom = new PredictableRandom(
            [0, 1, 2, 3],                          // Predictable ints
            ['session-abc-123']                     // Predictable UUID
        );
        const mockFs = new InMemoryFileSystem();
        const mockHttp = new MockHttpClient();
        mockHttp.setResponse(
            'https://auth.example.com/users/user-456/validate',
            { status: 200, body: '{"valid": true}' }
        );
        
        const manager = new SessionManager(
            mockClock,
            mockRandom,
            mockHttp,
            mockFs
        );
        
        // Act
        const session = await manager.createSession('user-456');
        
        // Assert: Deterministic, predictable results
        expect(session.id).toBe('session-abc-123');
        expect(session.userId).toBe('user-456');
        expect(session.createdAt).toEqual(fixedTime);
        expect(session.expiresAt).toEqual(new Date('2024-01-15T11:00:00Z'));
        
        // Verify file was written
        const storedFiles = mockFs.getStoredFiles();
        expect(storedFiles.has('/sessions/session-abc-123.json')).toBe(true);
        
        // Verify HTTP call was made
        const requests = mockHttp.getRecordedRequests();
        expect(requests).toHaveLength(1);
        expect(requests[0].url).toContain('user-456');
    });
});

Critical hermetic testing principles demonstrated:

•Time is abstracted — The Clock interface allows freezing time at any point, making time-dependent tests deterministic.
•Randomness is abstracted — The RandomGenerator interface allows specifying exact sequences of 'random' values for predictable testing.
•Network is abstracted — The HttpClient interface captures all HTTP interactions. Tests never make real network calls.
•File system is abstracted — The FileSystem interface allows in-memory file operations. Tests never touch the real disk.
•All behavior is controllable — Every aspect of the test is specified in the test itself. No external factors can cause failure.

Boundary Identification

Effective unit isolation requires identifying boundaries—the points where your code interacts with the outside world or with other significant modules. These boundaries are where abstractions should live, and where test doubles will be injected.

Types of boundaries:

Common Boundary Types and Abstraction Strategies
Boundary Type	Examples	Abstraction Strategy	Test Double
Infrastructure	Databases, file systems, message queues	Repository pattern, Storage interfaces	In-memory implementations, fakes
External Services	REST APIs, SOAP services, third-party SDKs	Gateway interfaces, Client wrappers	Mock clients with canned responses
Time & Randomness	System clock, UUID generators, crypto	Clock interface, Generator interface	Fixed-value implementations
Environment	Config files, environment variables	Configuration interface	In-memory configuration
User Input/Output	Console I/O, UI interactions	I/O abstractions	Captured/recorded I/O
Concurrency	Thread pools, schedulers, timers	Executor interface	Synchronous test executors

Identifying boundaries in existing code:

When working with existing code that may not follow DIP, look for these telltale signs of boundary violations:

BoundaryViolationPatterns
TypeScript
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
// ❌ Boundary violations - direct infrastructure access
 
class OrderProcessor {
    async processOrder(order: Order): Promise<void> {
        // 🚨 Direct database access - where's the abstraction?
        const db = new PostgresClient(process.env.DATABASE_URL!);
        await db.insert('orders', order);
        
        // 🚨 Direct HTTP call - can't test without network
        const stripe = new Stripe(process.env.STRIPE_KEY!);
        await stripe.charges.create({...});
        
        // 🚨 Direct time access - non-deterministic
        const now = new Date();
        order.processedAt = now;
        
        // 🚨 Direct file write - requires file system
        const fs = require('fs');
        fs.writeFileSync('/var/log/orders.log', JSON.stringify(order));
        
        // 🚨 Direct random generation - unpredictable
        order.confirmationCode = Math.random().toString(36).slice(2);
    }
}
 
// ✅ Proper boundary abstraction
 
interface OrderRepository {
    save(order: Order): Promise<Order>;
    findById(id: string): Promise<Order | null>;
}
 
interface PaymentProcessor {
    charge(amount: number, paymentMethod: PaymentMethod): Promise<ChargeResult>;
}
 
interface Clock {
    now(): Date;
}
 
interface Logger {
    log(entry: LogEntry): Promise<void>;
}
 
interface IdGenerator {
    generateConfirmationCode(): string;
}
 
class OrderProcessor {
    constructor(
        private readonly repository: OrderRepository,
        private readonly payment: PaymentProcessor,
        private readonly clock: Clock,
        private readonly logger: Logger,
        private readonly idGenerator: IdGenerator
    ) {}
    
    async processOrder(order: Order): Promise<Order> {
        // All boundaries are now abstract - fully testable
        order.processedAt = this.clock.now();
        order.confirmationCode = this.idGenerator.generateConfirmationCode();
        
        await this.payment.charge(order.total, order.paymentMethod);
        const savedOrder = await this.repository.save(order);
        await this.logger.log({ event: 'order_processed', orderId: order.id });
        
        return savedOrder;
    }
}

Hidden Boundaries

Some boundaries are subtle: static method calls, global singletons, ambient state (like ThreadLocal or AsyncLocal storage), and implicit dependencies through inheritance. These are just as problematic as obvious boundaries like database connections. Every path to the outside world must be abstracted.

Isolation Strategies

Different testing scenarios call for different isolation strategies. Understanding when to use each approach helps you build a balanced, effective test suite.

Solitary unit tests isolate a single unit from ALL its collaborators. Every dependency is replaced with a test double. This is the purest form of unit testing.

TypeScript
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
// Solitary unit test - complete isolation
describe('ShoppingCart (solitary)', () => {
    let mockInventory: MockInventoryService;
    let mockPricing: MockPricingService;
    let mockTax: MockTaxCalculator;
    let cart: ShoppingCart;
    
    beforeEach(() => {
        // Replace ALL dependencies with mocks
        mockInventory = new MockInventoryService();
        mockPricing = new MockPricingService();
        mockTax = new MockTaxCalculator();
        
        cart = new ShoppingCart(mockInventory, mockPricing, mockTax);
    });
    
    it('calculates total using pricing and tax services', async () => {
        mockInventory.setAvailability('SKU-123', true);
        mockPricing.setPrice('SKU-123', 10.00);
        mockTax.setTaxRate(0.10); // 10% tax
        
        await cart.addItem('SKU-123', 2);
        const total = await cart.calculateTotal();
        
        // Total = (10.00 * 2) * 1.10 = 22.00
        expect(total).toBe(22.00);
        
        // Verify all collaborators were called correctly
        expect(mockInventory.checkAvailabilityCalls).toContain('SKU-123');
        expect(mockPricing.getPriceCalls).toContain('SKU-123');
        expect(mockTax.calculateCalls).toHaveLength(1);
    });
});

•✅ Complete control — Every aspect of the test is specified
•✅ Fast execution — No I/O, no waiting
•✅ Precise failure location — If it fails, the problem is in the unit
•✅ No flakiness — Deterministic by design
•⚠️ Integration gaps — Doesn't verify units work together

The Testing Pyramid

A healthy test suite follows the pyramid model: many solitary unit tests (fast, isolated), some sociable unit tests and narrow integration tests (verify local integration), and few end-to-end tests (verify full system behavior). DIP makes the base of this pyramid—numerous, fast, isolated unit tests—actually achievable.

Managing Complex Dependency Graphs

Real-world systems have complex dependency graphs—classes depend on classes that depend on other classes. Testing such systems requires strategies for managing this complexity without sacrificing isolation.

ComplexDependencyGraph
TypeScript
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
// Complex dependency graph example
 
// Level 1: Low-level infrastructure
interface DatabaseConnection { /* ... */ }
interface HttpClient { /* ... */ }
interface Cache { /* ... */ }
 
// Level 2: Data access and external services
interface UserRepository {
    constructor(db: DatabaseConnection, cache: Cache);
}
 
interface AuthenticationService {
    constructor(http: HttpClient, cache: Cache);
}
 
interface NotificationService {
    constructor(http: HttpClient);
}
 
// Level 3: Business services
interface UserService {
    constructor(
        userRepo: UserRepository,
        authService: AuthenticationService,
        notificationService: NotificationService
    );
}
 
// Level 4: Application layer
class UserRegistrationUseCase {
    constructor(
        private readonly userService: UserService,
        private readonly emailValidator: EmailValidator,
        private readonly passwordPolicy: PasswordPolicy
    ) {}
    
    async registerUser(email: string, password: string): Promise<User> {
        // Business logic using multiple services
        this.emailValidator.validate(email);
        this.passwordPolicy.validate(password);
        return await this.userService.createUser(email, password);
    }
}
 
// ❌ Problem: Testing UserRegistrationUseCase requires mocking
// UserService, but if UserService is concrete, you need to
// provide its dependencies too (UserRepository, AuthService, etc.)
// The graph is entangled.

Solution: Mock at the immediate boundary

With DIP compliance at every level, testing becomes straightforward. Each unit only needs to mock its direct dependencies—not the entire tree.

IsolatedTestingComplexGraph
TypeScript
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
// ✅ Testing complex graph with DIP - mock only direct dependencies
 
// Testing UserRegistrationUseCase - only need to mock its 3 dependencies
describe('UserRegistrationUseCase', () => {
    let mockUserService: jest.Mocked<UserService>;
    let mockEmailValidator: jest.Mocked<EmailValidator>;
    let mockPasswordPolicy: jest.Mocked<PasswordPolicy>;
    let useCase: UserRegistrationUseCase;
    
    beforeEach(() => {
        // Only mock what UserRegistrationUseCase directly uses
        // We don't care about UserService's dependencies
        mockUserService = {
            createUser: jest.fn(),
            findByEmail: jest.fn(),
            // ... other methods
        } as jest.Mocked<UserService>;
        
        mockEmailValidator = {
            validate: jest.fn(),
        } as jest.Mocked<EmailValidator>;
        
        mockPasswordPolicy = {
            validate: jest.fn(),
        } as jest.Mocked<PasswordPolicy>;
        
        useCase = new UserRegistrationUseCase(
            mockUserService,
            mockEmailValidator,
            mockPasswordPolicy
        );
    });
    
    it('creates user when validation passes', async () => {
        // Arrange
        const expectedUser: User = { id: 'user-1', email: 'test@example.com' };
        mockEmailValidator.validate.mockImplementation(() => {}); // No throw = valid
        mockPasswordPolicy.validate.mockImplementation(() => {});  // No throw = valid
        mockUserService.createUser.mockResolvedValue(expectedUser);
        
        // Act
        const result = await useCase.registerUser('test@example.com', 'SecurePass123!');
        
        // Assert
        expect(result).toEqual(expectedUser);
        expect(mockEmailValidator.validate).toHaveBeenCalledWith('test@example.com');
        expect(mockPasswordPolicy.validate).toHaveBeenCalledWith('SecurePass123!');
        expect(mockUserService.createUser).toHaveBeenCalledWith('test@example.com', 'SecurePass123!');
    });
    
    it('rejects invalid email before calling user service', async () => {
        mockEmailValidator.validate.mockImplementation(() => {
            throw new ValidationError('Invalid email format');
        });
        
        await expect(
            useCase.registerUser('invalid-email', 'password')
        ).rejects.toThrow('Invalid email format');
        
        // UserService should never be called
        expect(mockUserService.createUser).not.toHaveBeenCalled();
    });
});
 
// Separately test UserService with its own mocks
describe('UserService', () => {
    let mockUserRepo: jest.Mocked<UserRepository>;
    let mockAuthService: jest.Mocked<AuthenticationService>;
    let mockNotificationService: jest.Mocked<NotificationService>;
    let service: UserService;
    
    beforeEach(() => {
        mockUserRepo = { save: jest.fn(), findByEmail: jest.fn() };
        mockAuthService = { createCredentials: jest.fn() };
        mockNotificationService = { sendWelcome: jest.fn() };
        
        service = new UserServiceImpl(mockUserRepo, mockAuthService, mockNotificationService);
    });
    
    // Test UserService in isolation from its dependencies
    it('coordinates user creation across services', async () => {
        // Test the orchestration logic of UserService
    });
});
 
// Pattern: Each layer tested independently, mocking only immediate dependencies

Complex Graph Testing Principles

•Mock at boundaries, not recursively — Each unit mocks only its direct dependencies. Don't try to mock the whole tree.
•Test each layer independently — UserRegistrationUseCase tests focus on its logic; UserService tests focus on service orchestration; Repository tests focus on data access.
•DIP at every level — If any level violates DIP (creates its own dependencies), the graph becomes entangled and hard to test.
•Interface segregation helps — Smaller, focused interfaces mean simpler mocks at each level.
•Test builders/factories — For complex object creation in tests, build test utilities that construct properly-configured mocks.

Test Isolation Anti-Patterns

Understanding what NOT to do is as important as knowing best practices. Here are common anti-patterns that undermine test isolation:

Test Isolation Anti-Patterns

•Shared mutable state — Mocks or test fixtures shared between tests without proper reset. One test's modifications affect subsequent tests, causing order-dependent failures.
•Real singletons — Using actual singleton instances in tests. These persist state across tests and can't be reset or mocked.
•Static dependencies — Code that calls static methods on concrete classes. These can't be mocked through normal means.
•Hidden time dependencies — Using new Date() or Date.now() directly. Tests become time-sensitive and may fail at midnight or during DST transitions.
•Test databases with residue — Integration tests that don't clean up properly. Leftover data causes cascading failures in subsequent tests.
•Mock overreach — Mocking internal implementation details rather than public contracts. Tests become brittle and break when implementation changes.
•Insufficient interface abstraction — Interfaces that are too close to concrete implementations, making mocks complex and fragile.
•Global environment coupling — Tests that depend on specific environment variables, file system paths, or network availability.

IsolationAntiPatterns
TypeScript
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
// ❌ ANTI-PATTERN: Shared mutable state in mocks
class GlobalMock {
    static sharedData: any[] = []; // 🚨 Shared between tests!
}
 
describe('Test A', () => {
    it('adds data', () => {
        GlobalMock.sharedData.push({ id: 1 });
        expect(GlobalMock.sharedData).toHaveLength(1);
    });
});
 
describe('Test B', () => {
    it('expects empty - but fails!', () => {
        // 🚨 This fails because Test A's data persists
        expect(GlobalMock.sharedData).toHaveLength(0); // FAILS!
    });
});
 
// ✅ FIX: Create fresh mocks for each test
describe('Test A (fixed)', () => {
    let mockData: any[];
    
    beforeEach(() => {
        mockData = []; // Fresh for each test
    });
    
    it('adds data', () => {
        mockData.push({ id: 1 });
        expect(mockData).toHaveLength(1);
    });
});
 
// ❌ ANTI-PATTERN: Real singleton
class ConfigurationSingleton {
    private static instance: ConfigurationSingleton;
    private settings = new Map<string, string>();
    
    static getInstance(): ConfigurationSingleton {
        if (!this.instance) {
            this.instance = new ConfigurationSingleton();
        }
        return this.instance;
    }
    
    set(key: string, value: string) { this.settings.set(key, value); }
    get(key: string): string | undefined { return this.settings.get(key); }
}
 
// Tests using singleton can't control configuration
class ServiceUsingSingleton {
    doWork(): string {
        // 🚨 Can't mock this singleton
        const config = ConfigurationSingleton.getInstance();
        return config.get('api-url') || 'default';
    }
}
 
// ✅ FIX: Inject configuration
interface Configuration {
    get(key: string): string | undefined;
}
 
class ServiceWithInjectedConfig {
    constructor(private readonly config: Configuration) {}
    
    doWork(): string {
        return this.config.get('api-url') || 'default';
    }
}
 
// Now tests can inject mock configuration
const mockConfig: Configuration = { get: () => 'test-url' };
const service = new ServiceWithInjectedConfig(mockConfig);

The Root Cause

Nearly all test isolation anti-patterns trace back to DIP violations. When you find yourself struggling with test isolation, the solution is rarely a better mocking technique—it's refactoring the production code to properly depend on abstractions.

Summary: Isolating Units for Testing

We've explored the principles and practices of unit isolation—the foundation of effective unit testing. Let's consolidate the key insights:

Key Takeaways

•True unit isolation requires DIP compliance — Without depending on abstractions, units cannot be tested in isolation. The dependencies are welded in place.
•Hermetic testing controls all external factors — Time, randomness, network, file system—everything that could introduce non-determinism must be abstracted and controlled.
•Identify all boundaries — Every point where code touches the outside world (infrastructure, services, environment) must have an abstraction that can be mocked.
•Choose isolation strategies deliberately — Solitary tests for pure logic, sociable tests for orchestration, narrow integration for boundary adapters.
•Mock at immediate boundaries only — Don't try to mock the entire dependency tree. Each layer mocks only what it directly uses.
•Avoid anti-patterns — Shared state, singletons, static dependencies, and hidden inputs all undermine isolation. The fix is usually better DIP compliance.

What's next:

With a solid understanding of unit isolation, we'll now explore designing for testability—how to structure code from the outset so that it naturally supports testing. We'll examine architectural patterns, API design considerations, and organizational strategies that make testability a first-class concern rather than an afterthought.

Page Complete

You now understand how DIP enables true unit isolation—testing components in complete hermetic isolation from the outside world. This is the foundation of a fast, reliable, and informative test suite. Next, we'll explore proactive design strategies that build testability into your architecture from the start.

Isolating Units for Testing

The Isolation Imperative

What You Will Learn

Defining Unit Isolation

What constitutes a 'unit'?

Characteristics of a Testable Unit

•Single responsibility — The unit does one thing well. If testing requires verifying multiple unrelated behaviors, the unit may be too large.
•Clear boundaries — The unit has explicit dependencies received through its public interface (constructor, method parameters).
•Abstract dependencies — The unit depends on interfaces, not concrete implementations. This is DIP compliance.
•Deterministic behavior — Given the same inputs and mock behaviors, the unit produces the same outputs every time.
•No hidden state — The unit doesn't secretly access global state, singletons, or static mutable data that would affect behavior.

The isolation test:

Isolation Is Not Optional

The Hermetic Testing Model

Hermetic testing is a model where tests are completely sealed off from the external world. The term comes from 'hermetically sealed'—nothing gets in or out. In a hermetic test:

No network calls leave the test process
No disk I/O occurs (except in controlled, temporary locations)
No shared state exists between tests
No external services are contacted
Time, random numbers, and other sources of non-determinism are controlled

HermeticTestingExample
TypeScript
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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
// ✅ Hermetic test design through DIP
 
// Abstractions for all external interactions
interface Clock {
    now(): Date;
}
 
interface RandomGenerator {
    nextInt(max: number): number;
    nextUuid(): string;
}
 
interface HttpClient {
    get(url: string): Promise<HttpResponse>;
    post(url: string, body: object): Promise<HttpResponse>;
}
 
interface FileSystem {
    readFile(path: string): Promise<string>;
    writeFile(path: string, content: string): Promise<void>;
}
 
// Class with all non-determinism abstracted away
class SessionManager {
    constructor(
        private readonly clock: Clock,
        private readonly random: RandomGenerator,
        private readonly httpClient: HttpClient,
        private readonly fileSystem: FileSystem
    ) {}
    
    async createSession(userId: string): Promise<Session> {
        const sessionId = this.random.nextUuid();
        const createdAt = this.clock.now();
        const expiresAt = new Date(createdAt.getTime() + 3600000); // 1 hour
        
        const session: Session = {
            id: sessionId,
            userId,
            createdAt,
            expiresAt,
            token: this.generateToken()
        };
        
        // Validate user with external service
        await this.validateUser(userId);
        
        // Persist session
        await this.fileSystem.writeFile(
            `/sessions/${sessionId}.json`,
            JSON.stringify(session)
        );
        
        return session;
    }
    
    private generateToken(): string {
        const bytes = Array.from({ length: 32 }, () => 
            this.random.nextInt(256)
        );
        return bytes.map(b => b.toString(16).padStart(2, '0')).join('');
    }
    
    private async validateUser(userId: string): Promise<void> {
        const response = await this.httpClient.get(
            `https://auth.example.com/users/${userId}/validate`
        );
        if (response.status !== 200) {
            throw new Error('User validation failed');
        }
    }
}
 
// Hermetic test mocks - complete control over all external factors
class FixedClock implements Clock {
    constructor(private readonly fixedTime: Date) {}
    
    now(): Date {
        return new Date(this.fixedTime.getTime());
    }
}
 
class PredictableRandom implements RandomGenerator {
    private intSequence: number[];
    private uuidSequence: string[];
    private intIndex = 0;
    private uuidIndex = 0;
    
    constructor(ints: number[], uuids: string[]) {
        this.intSequence = ints;
        this.uuidSequence = uuids;
    }
    
    nextInt(max: number): number {
        return this.intSequence[this.intIndex++ % this.intSequence.length] % max;
    }
    
    nextUuid(): string {
        return this.uuidSequence[this.uuidIndex++ % this.uuidSequence.length];
    }
}
 
class InMemoryFileSystem implements FileSystem {
    private files = new Map<string, string>();
    
    async readFile(path: string): Promise<string> {
        const content = this.files.get(path);
        if (!content) throw new Error(`File not found: ${path}`);
        return content;
    }
    
    async writeFile(path: string, content: string): Promise<void> {
        this.files.set(path, content);
    }
    
    // Test helper
    getStoredFiles(): Map<string, string> {
        return new Map(this.files);
    }
}
 
class MockHttpClient implements HttpClient {
    private responses = new Map<string, HttpResponse>();
    private recordedRequests: { method: string; url: string; body?: object }[] = [];
    
    setResponse(url: string, response: HttpResponse): void {
        this.responses.set(url, response);
    }
    
    async get(url: string): Promise<HttpResponse> {
        this.recordedRequests.push({ method: 'GET', url });
        return this.responses.get(url) || { status: 500, body: 'No mock response' };
    }
    
    async post(url: string, body: object): Promise<HttpResponse> {
        this.recordedRequests.push({ method: 'POST', url, body });
        return this.responses.get(url) || { status: 500, body: 'No mock response' };
    }
    
    getRecordedRequests() {
        return [...this.recordedRequests];
    }
}
 
// Hermetic test - completely isolated and deterministic
describe('SessionManager (hermetic)', () => {
    it('creates session with predictable values', async () => {
        // Arrange: Complete control over all external factors
        const fixedTime = new Date('2024-01-15T10:00:00Z');
        const mockClock = new FixedClock(fixedTime);
        const mockRandom = new PredictableRandom(
            [0, 1, 2, 3],                          // Predictable ints
            ['session-abc-123']                     // Predictable UUID
        );
        const mockFs = new InMemoryFileSystem();
        const mockHttp = new MockHttpClient();
        mockHttp.setResponse(
            'https://auth.example.com/users/user-456/validate',
            { status: 200, body: '{"valid": true}' }
        );
        
        const manager = new SessionManager(
            mockClock,
            mockRandom,
            mockHttp,
            mockFs
        );
        
        // Act
        const session = await manager.createSession('user-456');
        
        // Assert: Deterministic, predictable results
        expect(session.id).toBe('session-abc-123');
        expect(session.userId).toBe('user-456');
        expect(session.createdAt).toEqual(fixedTime);
        expect(session.expiresAt).toEqual(new Date('2024-01-15T11:00:00Z'));
        
        // Verify file was written
        const storedFiles = mockFs.getStoredFiles();
        expect(storedFiles.has('/sessions/session-abc-123.json')).toBe(true);
        
        // Verify HTTP call was made
        const requests = mockHttp.getRecordedRequests();
        expect(requests).toHaveLength(1);
        expect(requests[0].url).toContain('user-456');
    });
});

Critical hermetic testing principles demonstrated:

•Time is abstracted — The Clock interface allows freezing time at any point, making time-dependent tests deterministic.
•Randomness is abstracted — The RandomGenerator interface allows specifying exact sequences of 'random' values for predictable testing.
•Network is abstracted — The HttpClient interface captures all HTTP interactions. Tests never make real network calls.
•File system is abstracted — The FileSystem interface allows in-memory file operations. Tests never touch the real disk.
•All behavior is controllable — Every aspect of the test is specified in the test itself. No external factors can cause failure.

Boundary Identification

Types of boundaries:

Common Boundary Types and Abstraction Strategies
Boundary Type	Examples	Abstraction Strategy	Test Double
Infrastructure	Databases, file systems, message queues	Repository pattern, Storage interfaces	In-memory implementations, fakes
External Services	REST APIs, SOAP services, third-party SDKs	Gateway interfaces, Client wrappers	Mock clients with canned responses
Time & Randomness	System clock, UUID generators, crypto	Clock interface, Generator interface	Fixed-value implementations
Environment	Config files, environment variables	Configuration interface	In-memory configuration
User Input/Output	Console I/O, UI interactions	I/O abstractions	Captured/recorded I/O
Concurrency	Thread pools, schedulers, timers	Executor interface	Synchronous test executors

Identifying boundaries in existing code:

When working with existing code that may not follow DIP, look for these telltale signs of boundary violations:

BoundaryViolationPatterns
TypeScript
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
// ❌ Boundary violations - direct infrastructure access
 
class OrderProcessor {
    async processOrder(order: Order): Promise<void> {
        // 🚨 Direct database access - where's the abstraction?
        const db = new PostgresClient(process.env.DATABASE_URL!);
        await db.insert('orders', order);
        
        // 🚨 Direct HTTP call - can't test without network
        const stripe = new Stripe(process.env.STRIPE_KEY!);
        await stripe.charges.create({...});
        
        // 🚨 Direct time access - non-deterministic
        const now = new Date();
        order.processedAt = now;
        
        // 🚨 Direct file write - requires file system
        const fs = require('fs');
        fs.writeFileSync('/var/log/orders.log', JSON.stringify(order));
        
        // 🚨 Direct random generation - unpredictable
        order.confirmationCode = Math.random().toString(36).slice(2);
    }
}
 
// ✅ Proper boundary abstraction
 
interface OrderRepository {
    save(order: Order): Promise<Order>;
    findById(id: string): Promise<Order | null>;
}
 
interface PaymentProcessor {
    charge(amount: number, paymentMethod: PaymentMethod): Promise<ChargeResult>;
}
 
interface Clock {
    now(): Date;
}
 
interface Logger {
    log(entry: LogEntry): Promise<void>;
}
 
interface IdGenerator {
    generateConfirmationCode(): string;
}
 
class OrderProcessor {
    constructor(
        private readonly repository: OrderRepository,
        private readonly payment: PaymentProcessor,
        private readonly clock: Clock,
        private readonly logger: Logger,
        private readonly idGenerator: IdGenerator
    ) {}
    
    async processOrder(order: Order): Promise<Order> {
        // All boundaries are now abstract - fully testable
        order.processedAt = this.clock.now();
        order.confirmationCode = this.idGenerator.generateConfirmationCode();
        
        await this.payment.charge(order.total, order.paymentMethod);
        const savedOrder = await this.repository.save(order);
        await this.logger.log({ event: 'order_processed', orderId: order.id });
        
        return savedOrder;
    }
}

Hidden Boundaries

Isolation Strategies

Different testing scenarios call for different isolation strategies. Understanding when to use each approach helps you build a balanced, effective test suite.

Solitary unit tests isolate a single unit from ALL its collaborators. Every dependency is replaced with a test double. This is the purest form of unit testing.

TypeScript
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
// Solitary unit test - complete isolation
describe('ShoppingCart (solitary)', () => {
    let mockInventory: MockInventoryService;
    let mockPricing: MockPricingService;
    let mockTax: MockTaxCalculator;
    let cart: ShoppingCart;
    
    beforeEach(() => {
        // Replace ALL dependencies with mocks
        mockInventory = new MockInventoryService();
        mockPricing = new MockPricingService();
        mockTax = new MockTaxCalculator();
        
        cart = new ShoppingCart(mockInventory, mockPricing, mockTax);
    });
    
    it('calculates total using pricing and tax services', async () => {
        mockInventory.setAvailability('SKU-123', true);
        mockPricing.setPrice('SKU-123', 10.00);
        mockTax.setTaxRate(0.10); // 10% tax
        
        await cart.addItem('SKU-123', 2);
        const total = await cart.calculateTotal();
        
        // Total = (10.00 * 2) * 1.10 = 22.00
        expect(total).toBe(22.00);
        
        // Verify all collaborators were called correctly
        expect(mockInventory.checkAvailabilityCalls).toContain('SKU-123');
        expect(mockPricing.getPriceCalls).toContain('SKU-123');
        expect(mockTax.calculateCalls).toHaveLength(1);
    });
});

•✅ Complete control — Every aspect of the test is specified
•✅ Fast execution — No I/O, no waiting
•✅ Precise failure location — If it fails, the problem is in the unit
•✅ No flakiness — Deterministic by design
•⚠️ Integration gaps — Doesn't verify units work together

The Testing Pyramid

Managing Complex Dependency Graphs

ComplexDependencyGraph
TypeScript
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
// Complex dependency graph example
 
// Level 1: Low-level infrastructure
interface DatabaseConnection { /* ... */ }
interface HttpClient { /* ... */ }
interface Cache { /* ... */ }
 
// Level 2: Data access and external services
interface UserRepository {
    constructor(db: DatabaseConnection, cache: Cache);
}
 
interface AuthenticationService {
    constructor(http: HttpClient, cache: Cache);
}
 
interface NotificationService {
    constructor(http: HttpClient);
}
 
// Level 3: Business services
interface UserService {
    constructor(
        userRepo: UserRepository,
        authService: AuthenticationService,
        notificationService: NotificationService
    );
}
 
// Level 4: Application layer
class UserRegistrationUseCase {
    constructor(
        private readonly userService: UserService,
        private readonly emailValidator: EmailValidator,
        private readonly passwordPolicy: PasswordPolicy
    ) {}
    
    async registerUser(email: string, password: string): Promise<User> {
        // Business logic using multiple services
        this.emailValidator.validate(email);
        this.passwordPolicy.validate(password);
        return await this.userService.createUser(email, password);
    }
}
 
// ❌ Problem: Testing UserRegistrationUseCase requires mocking
// UserService, but if UserService is concrete, you need to
// provide its dependencies too (UserRepository, AuthService, etc.)
// The graph is entangled.

Solution: Mock at the immediate boundary

With DIP compliance at every level, testing becomes straightforward. Each unit only needs to mock its direct dependencies—not the entire tree.

IsolatedTestingComplexGraph
TypeScript
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
// ✅ Testing complex graph with DIP - mock only direct dependencies
 
// Testing UserRegistrationUseCase - only need to mock its 3 dependencies
describe('UserRegistrationUseCase', () => {
    let mockUserService: jest.Mocked<UserService>;
    let mockEmailValidator: jest.Mocked<EmailValidator>;
    let mockPasswordPolicy: jest.Mocked<PasswordPolicy>;
    let useCase: UserRegistrationUseCase;
    
    beforeEach(() => {
        // Only mock what UserRegistrationUseCase directly uses
        // We don't care about UserService's dependencies
        mockUserService = {
            createUser: jest.fn(),
            findByEmail: jest.fn(),
            // ... other methods
        } as jest.Mocked<UserService>;
        
        mockEmailValidator = {
            validate: jest.fn(),
        } as jest.Mocked<EmailValidator>;
        
        mockPasswordPolicy = {
            validate: jest.fn(),
        } as jest.Mocked<PasswordPolicy>;
        
        useCase = new UserRegistrationUseCase(
            mockUserService,
            mockEmailValidator,
            mockPasswordPolicy
        );
    });
    
    it('creates user when validation passes', async () => {
        // Arrange
        const expectedUser: User = { id: 'user-1', email: 'test@example.com' };
        mockEmailValidator.validate.mockImplementation(() => {}); // No throw = valid
        mockPasswordPolicy.validate.mockImplementation(() => {});  // No throw = valid
        mockUserService.createUser.mockResolvedValue(expectedUser);
        
        // Act
        const result = await useCase.registerUser('test@example.com', 'SecurePass123!');
        
        // Assert
        expect(result).toEqual(expectedUser);
        expect(mockEmailValidator.validate).toHaveBeenCalledWith('test@example.com');
        expect(mockPasswordPolicy.validate).toHaveBeenCalledWith('SecurePass123!');
        expect(mockUserService.createUser).toHaveBeenCalledWith('test@example.com', 'SecurePass123!');
    });
    
    it('rejects invalid email before calling user service', async () => {
        mockEmailValidator.validate.mockImplementation(() => {
            throw new ValidationError('Invalid email format');
        });
        
        await expect(
            useCase.registerUser('invalid-email', 'password')
        ).rejects.toThrow('Invalid email format');
        
        // UserService should never be called
        expect(mockUserService.createUser).not.toHaveBeenCalled();
    });
});
 
// Separately test UserService with its own mocks
describe('UserService', () => {
    let mockUserRepo: jest.Mocked<UserRepository>;
    let mockAuthService: jest.Mocked<AuthenticationService>;
    let mockNotificationService: jest.Mocked<NotificationService>;
    let service: UserService;
    
    beforeEach(() => {
        mockUserRepo = { save: jest.fn(), findByEmail: jest.fn() };
        mockAuthService = { createCredentials: jest.fn() };
        mockNotificationService = { sendWelcome: jest.fn() };
        
        service = new UserServiceImpl(mockUserRepo, mockAuthService, mockNotificationService);
    });
    
    // Test UserService in isolation from its dependencies
    it('coordinates user creation across services', async () => {
        // Test the orchestration logic of UserService
    });
});
 
// Pattern: Each layer tested independently, mocking only immediate dependencies

Complex Graph Testing Principles

•Mock at boundaries, not recursively — Each unit mocks only its direct dependencies. Don't try to mock the whole tree.
•Test each layer independently — UserRegistrationUseCase tests focus on its logic; UserService tests focus on service orchestration; Repository tests focus on data access.
•DIP at every level — If any level violates DIP (creates its own dependencies), the graph becomes entangled and hard to test.
•Interface segregation helps — Smaller, focused interfaces mean simpler mocks at each level.
•Test builders/factories — For complex object creation in tests, build test utilities that construct properly-configured mocks.

Test Isolation Anti-Patterns

Understanding what NOT to do is as important as knowing best practices. Here are common anti-patterns that undermine test isolation:

Test Isolation Anti-Patterns

•Shared mutable state — Mocks or test fixtures shared between tests without proper reset. One test's modifications affect subsequent tests, causing order-dependent failures.
•Real singletons — Using actual singleton instances in tests. These persist state across tests and can't be reset or mocked.
•Static dependencies — Code that calls static methods on concrete classes. These can't be mocked through normal means.
•Hidden time dependencies — Using new Date() or Date.now() directly. Tests become time-sensitive and may fail at midnight or during DST transitions.
•Test databases with residue — Integration tests that don't clean up properly. Leftover data causes cascading failures in subsequent tests.
•Mock overreach — Mocking internal implementation details rather than public contracts. Tests become brittle and break when implementation changes.
•Insufficient interface abstraction — Interfaces that are too close to concrete implementations, making mocks complex and fragile.
•Global environment coupling — Tests that depend on specific environment variables, file system paths, or network availability.

IsolationAntiPatterns
TypeScript
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
// ❌ ANTI-PATTERN: Shared mutable state in mocks
class GlobalMock {
    static sharedData: any[] = []; // 🚨 Shared between tests!
}
 
describe('Test A', () => {
    it('adds data', () => {
        GlobalMock.sharedData.push({ id: 1 });
        expect(GlobalMock.sharedData).toHaveLength(1);
    });
});
 
describe('Test B', () => {
    it('expects empty - but fails!', () => {
        // 🚨 This fails because Test A's data persists
        expect(GlobalMock.sharedData).toHaveLength(0); // FAILS!
    });
});
 
// ✅ FIX: Create fresh mocks for each test
describe('Test A (fixed)', () => {
    let mockData: any[];
    
    beforeEach(() => {
        mockData = []; // Fresh for each test
    });
    
    it('adds data', () => {
        mockData.push({ id: 1 });
        expect(mockData).toHaveLength(1);
    });
});
 
// ❌ ANTI-PATTERN: Real singleton
class ConfigurationSingleton {
    private static instance: ConfigurationSingleton;
    private settings = new Map<string, string>();
    
    static getInstance(): ConfigurationSingleton {
        if (!this.instance) {
            this.instance = new ConfigurationSingleton();
        }
        return this.instance;
    }
    
    set(key: string, value: string) { this.settings.set(key, value); }
    get(key: string): string | undefined { return this.settings.get(key); }
}
 
// Tests using singleton can't control configuration
class ServiceUsingSingleton {
    doWork(): string {
        // 🚨 Can't mock this singleton
        const config = ConfigurationSingleton.getInstance();
        return config.get('api-url') || 'default';
    }
}
 
// ✅ FIX: Inject configuration
interface Configuration {
    get(key: string): string | undefined;
}
 
class ServiceWithInjectedConfig {
    constructor(private readonly config: Configuration) {}
    
    doWork(): string {
        return this.config.get('api-url') || 'default';
    }
}
 
// Now tests can inject mock configuration
const mockConfig: Configuration = { get: () => 'test-url' };
const service = new ServiceWithInjectedConfig(mockConfig);

The Root Cause

Summary: Isolating Units for Testing

We've explored the principles and practices of unit isolation—the foundation of effective unit testing. Let's consolidate the key insights:

Key Takeaways

•True unit isolation requires DIP compliance — Without depending on abstractions, units cannot be tested in isolation. The dependencies are welded in place.
•Hermetic testing controls all external factors — Time, randomness, network, file system—everything that could introduce non-determinism must be abstracted and controlled.
•Identify all boundaries — Every point where code touches the outside world (infrastructure, services, environment) must have an abstraction that can be mocked.
•Choose isolation strategies deliberately — Solitary tests for pure logic, sociable tests for orchestration, narrow integration for boundary adapters.
•Mock at immediate boundaries only — Don't try to mock the entire dependency tree. Each layer mocks only what it directly uses.
•Avoid anti-patterns — Shared state, singletons, static dependencies, and hidden inputs all undermine isolation. The fix is usually better DIP compliance.

What's next:

Page Complete