Integration Testing at LLD Level

THE TESTING PYRAMID
══════════════════════════════════════════════════════════════
 
                            ╱╲
                           ╱  ╲
                          ╱ E2E╲            Few (~5-10%)
                         ╱──────╲           • Slowest
                        ╱        ╲          • Most brittle
                       ╱Integration╲        • Highest confidence
                      ╱────────────╲
                     ╱              ╲       Some (~20-30%)
                    ╱   Service      ╲      • Medium speed
                   ╱   Integration    ╲     • Some brittleness
                  ╱────────────────────╲    • Good coverage
                 ╱                      ╲
                ╱    Component / Pair    ╲
               ╱       Integration        ╲  More (~10-20%)
              ╱────────────────────────────╲
             ╱                              ╲
            ╱          Unit Tests            ╲  Many (~50-60%)
           ╱                                  ╲
          ╱────────────────────────────────────╲ • Fastest
                                                 • Very stable
                                                 • Limited scope
 
COSTS & BENEFITS BY LEVEL:
─────────────────────────────────────────────────────────────
Level           Speed      Setup      Maintenance   Realism
─────────────────────────────────────────────────────────────
Unit            ★★★★★      ★★★★★      ★★★★★         ★☆☆☆☆
Component Int.  ★★★★☆      ★★★★☆      ★★★★☆         ★★☆☆☆
Service Int.    ★★★☆☆      ★★★☆☆      ★★★☆☆         ★★★☆☆
E2E             ★☆☆☆☆      ★☆☆☆☆      ★☆☆☆☆         ★★★★★

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

// Using Jest test tags for categorization
// jest.config.js: modulePathIgnorePatterns based on tags
 
// ===== SMOKE TESTS: Critical path only =====
describe.each(['smoke'])('Order System Smoke Tests', () => {
    it('can connect to database', async () => {
        await expect(db.query('SELECT 1')).resolves.toBeDefined();
    });
    
    it('can authenticate with auth service', async () => {
        const token = await authService.getToken(testCredentials);
        expect(token).toBeDefined();
    });
    
    it('can create and retrieve order', async () => {
        const order = await orderService.create(minimalValidOrder);
        const retrieved = await orderService.findById(order.id);
        expect(retrieved).toBeDefined();
    });
});
 
// ===== CONTRACT TESTS: API shape verification =====
describe.each(['contract'])('Order API Contract Tests', () => {
    it('POST /orders returns expected shape', async () => {
        const response = await api.post('/orders', validOrderRequest);
        
        expect(response.status).toBe(201);
        expect(response.body).toMatchObject({
            id: expect.any(String),
            status: 'PENDING',
            items: expect.arrayContaining([
                expect.objectContaining({
                    sku: expect.any(String),
                    quantity: expect.any(Number),
                }),
            ]),
            createdAt: expect.any(String),
        });
    });
    
    it('GET /orders/:id returns 404 for non-existent', async () => {
        const response = await api.get('/orders/non-existent-id');
        expect(response.status).toBe(404);
        expect(response.body.error).toBe('Order not found');
    });
});
 
// ===== COMPONENT TESTS: Full component behavior =====
describe.each(['component'])('OrderService Component Tests', () => {
    // Uses real repository, real validator, mocked external services
    let orderService: OrderService;
    
    beforeEach(() => {
        orderService = new OrderService(
            new PostgresOrderRepository(testDb.pool),
            new OrderValidator(),
            createMockPaymentGateway(),
            createMockNotificationService(),
        );
    });
    
    describe('order lifecycle', () => {
        it('should transition through valid states', async () => {
            const order = await orderService.create(validRequest);
            expect(order.status).toBe('PENDING');
            
            await orderService.confirm(order.id);
            const confirmed = await orderService.findById(order.id);
            expect(confirmed?.status).toBe('CONFIRMED');
            
            await orderService.ship(order.id, trackingInfo);
            const shipped = await orderService.findById(order.id);
            expect(shipped?.status).toBe('SHIPPED');
        });
    });
});
 
// ===== SERVICE TESTS: Cross-service integration =====
describe.each(['service'])('Order-Inventory Integration', () => {
    // Tests with real Order and Inventory services
    let orderService: OrderService;
    let inventoryService: InventoryService;
    
    beforeEach(async () => {
        // Wire real services together
        orderService = await serviceContainer.resolve(OrderService);
        inventoryService = await serviceContainer.resolve(InventoryService);
    });
    
    it('should reserve inventory when order created', async () => {
        await inventoryService.stock('SKU-001', 100);
        
        const order = await orderService.create({
            items: [{ sku: 'SKU-001', quantity: 5 }],
        });
        
        const availability = await inventoryService.getAvailable('SKU-001');
        expect(availability).toBe(95); // 100 - 5 reserved
    });
});

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

// ===== PATTERN: Test Environment Builder =====
class TestEnvironment {
    private containers: StartedTestContainer[] = [];
    private services: Map<string, unknown> = new Map();
    
    async setup(): Promise<void> {
        // Start containers in parallel
        const [postgres, redis, rabbitmq] = await Promise.all([
            new PostgreSqlContainer('postgres:15').start(),
            new GenericContainer('redis:7').withExposedPorts(6379).start(),
            new GenericContainer('rabbitmq:3-management')
                .withExposedPorts(5672, 15672)
                .start(),
        ]);
        
        this.containers.push(postgres, redis, rabbitmq);
        
        // Configure services with container endpoints
        this.services.set('db', {
            host: postgres.getHost(),
            port: postgres.getPort(),
            database: postgres.getDatabase(),
            username: postgres.getUsername(),
            password: postgres.getPassword(),
        });
        
        this.services.set('redis', {
            host: redis.getHost(),
            port: redis.getMappedPort(6379),
        });
        
        this.services.set('rabbitmq', {
            host: rabbitmq.getHost(),
            port: rabbitmq.getMappedPort(5672),
        });
        
        // Run migrations
        await this.runMigrations();
    }
    
    async teardown(): Promise<void> {
        await Promise.all(this.containers.map(c => c.stop()));
    }
    
    getConfig(service: string): unknown {
        return this.services.get(service);
    }
    
    private async runMigrations(): Promise<void> {
        const dbConfig = this.getConfig('db') as DatabaseConfig;
        const migrator = new Migrator(dbConfig);
        await migrator.runAll();
    }
}
 
// ===== USAGE IN TEST SUITE =====
describe('Order System Integration', () => {
    let env: TestEnvironment;
    let orderService: OrderService;
    
    beforeAll(async () => {
        env = new TestEnvironment();
        await env.setup();
        
        // Initialize services with test environment config
        const container = new ServiceContainer();
        container.register('dbConfig', env.getConfig('db'));
        container.register('redisConfig', env.getConfig('redis'));
        container.register('rabbitmqConfig', env.getConfig('rabbitmq'));
        await container.initialize();
        
        orderService = container.resolve(OrderService);
    }, 120000); // Allow 2 minutes for container startup
    
    afterAll(async () => {
        await env.teardown();
    });
    
    it('should process order through entire system', async () => {
        // Test runs against isolated, containerized infrastructure
        const order = await orderService.create(validOrder);
        expect(order.status).toBe('PENDING');
    });
});
 
// ===== PATTERN: Shared Test Environment (for speed) =====
// globalSetup.ts - runs once before all test files
export default async function globalSetup() {
    const env = new TestEnvironment();
    await env.setup();
    
    // Store config for test files to access
    process.env.TEST_DB_HOST = env.getConfig('db').host;
    process.env.TEST_DB_PORT = env.getConfig('db').port.toString();
    // ... other configs
    
    // Store containers for teardown
    (global as any).__TEST_ENV__ = env;
}
 
// globalTeardown.ts
export default async function globalTeardown() {
    const env = (global as any).__TEST_ENV__;
    await env?.teardown();
}

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

# Example GitHub Actions workflow with staged testing
name: CI Pipeline
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
 
jobs:
  # STAGE 1: Fast feedback (< 2 minutes)
  quick-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install dependencies
        run: npm ci
      
      - name: Lint
        run: npm run lint
      
      - name: Type check
        run: npm run typecheck
      
      - name: Unit tests
        run: npm run test:unit
        
      - name: Smoke tests (SQLite)
        run: npm run test:smoke
 
  # STAGE 2: Component tests (5-10 minutes)
  component-tests:
    runs-on: ubuntu-latest
    needs: quick-checks
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: test
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432
    
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      
      - name: Run migrations
        run: npm run db:migrate
        env:
          DATABASE_URL: postgres://postgres:test@localhost:5432/test
      
      - name: Component integration tests
        run: npm run test:component
        env:
          DATABASE_URL: postgres://postgres:test@localhost:5432/test
 
  # STAGE 3: Full service tests (10-20 minutes)
  service-tests:
    runs-on: ubuntu-latest
    needs: component-tests
    # Only run on main branches, not every PR
    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop'
    
    services:
      postgres:
        image: postgres:15
        env: { POSTGRES_PASSWORD: test }
        ports: ['5432:5432']
      
      redis:
        image: redis:7
        ports: ['6379:6379']
      
      rabbitmq:
        image: rabbitmq:3-management
        ports: ['5672:5672']
    
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run db:migrate
      
      - name: Service integration tests
        run: npm run test:service
        timeout-minutes: 20
 
  # STAGE 4: E2E tests (20-30 minutes)
  e2e-tests:
    runs-on: ubuntu-latest
    needs: service-tests
    if: github.ref == 'refs/heads/main'
    
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
      
      - name: Start application
        run: npm run start:test &
        
      - name: Wait for app ready
        run: npx wait-on http://localhost:3000/health
        
      - name: E2E tests
        run: npm run test:e2e
        timeout-minutes: 30
 
  # Parallel nightly: Full suite + performance
  nightly-full:
    runs-on: ubuntu-latest
    if: github.event_name == 'schedule'
    
    strategy:
      matrix:
        shard: [1, 2, 3, 4]  # Parallelize across 4 machines
    
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      
      - name: Run all integration tests (shard ${{ matrix.shard }})
        run: npm run test:integration -- --shard=${{ matrix.shard }}/4

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

// ===== ANTI-PATTERN: Race Condition =====
// ❌ BAD: Assumes async operation completes immediately
it('should send notification after order created', async () => {
    await orderService.create(validOrder);
    
    // Notification is sent async - may not be complete yet!
    const notifications = await notificationService.getRecent();
    expect(notifications).toHaveLength(1); // FLAKY!
});
 
// ✅ GOOD: Wait for the async operation to complete
it('should send notification after order created', async () => {
    const order = await orderService.create(validOrder);
    
    // Wait for notification to appear
    await waitForCondition(
        async () => {
            const notifications = await notificationService
                .findByOrderId(order.id);
            return notifications.length > 0;
        },
        { timeout: 5000, interval: 100 }
    );
    
    const notifications = await notificationService.findByOrderId(order.id);
    expect(notifications).toHaveLength(1);
    expect(notifications[0].orderId).toBe(order.id);
});
 
// ===== ANTI-PATTERN: Shared Test Data =====
// ❌ BAD: Tests share data, execution order matters
beforeAll(async () => {
    await seedTestCustomer({ id: 'customer-1' });
});
 
it('should find customer', async () => {
    const customer = await service.findById('customer-1');
    expect(customer).toBeDefined();
});
 
it('should delete customer', async () => {
    await service.delete('customer-1');
    // Now the previous test would fail if run after this one!
});
 
// ✅ GOOD: Each test owns its data
it('should find customer', async () => {
    const customer = await factory.createCustomer();
    
    const found = await service.findById(customer.id);
    expect(found?.id).toBe(customer.id);
});
 
it('should delete customer', async () => {
    const customer = await factory.createCustomer();
    
    await service.delete(customer.id);
    
    const found = await service.findById(customer.id);
    expect(found).toBeNull();
});
 
// ===== ANTI-PATTERN: Time Dependency =====
// ❌ BAD: Depends on actual system time
it('should expire old orders', async () => {
    const order = await orderService.create({
        ...validOrder,
        createdAt: new Date(), // "Now"
    });
    
    // This test might fail at 23:59:59!
    const tomorrow = new Date();
    tomorrow.setDate(tomorrow.getDate() + 1);
    
    const expired = await orderService.findExpiredBefore(tomorrow);
    expect(expired).toContain(order.id);
});
 
// ✅ GOOD: Use controllable time
it('should expire old orders', async () => {
    const fixedTime = new Date('2024-01-15T12:00:00Z');
    timeProvider.freeze(fixedTime);
    
    const order = await orderService.create(validOrder);
    
    // Advance time by 2 days
    timeProvider.advanceBy({ days: 2 });
    
    const expiredBefore = timeProvider.now();
    const expired = await orderService.findExpiredBefore(expiredBefore);
    expect(expired.map(o => o.id)).toContain(order.id);
    
    timeProvider.unfreeze();
});
 
// ===== PATTERN: Retry Wrapper for Known Flaky Operations =====
async function withRetry<T>(
    operation: () => Promise<T>,
    options: { retries: number; delay: number }
): Promise<T> {
    let lastError: Error;
    
    for (let attempt = 1; attempt <= options.retries; attempt++) {
        try {
            return await operation();
        } catch (error) {
            lastError = error as Error;
            if (attempt < options.retries) {
                await sleep(options.delay * attempt); // Exponential backoff
            }
        }
    }
    
    throw lastError!;
}
 
// Use for external service calls that may have transient failures
it('should sync with external inventory', async () => {
    const result = await withRetry(
        () => inventorySync.syncFromWarehouse(),
        { retries: 3, delay: 1000 }
    );
    
    expect(result.success).toBe(true);
});

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

// ===== STRATEGY 1: Comprehensive Logging =====
class IntegrationTestLogger {
    private logs: LogEntry[] = [];
    
    capture(level: string, message: string, context?: object): void {
        this.logs.push({
            timestamp: new Date().toISOString(),
            level,
            message,
            context,
        });
    }
    
    dumpOnFailure(): void {
        console.log('\n=== Integration Test Logs ===');
        for (const entry of this.logs) {
            console.log(`[${entry.timestamp}] ${entry.level}: ${entry.message}`);
            if (entry.context) {
                console.log(JSON.stringify(entry.context, null, 2));
            }
        }
    }
    
    clear(): void {
        this.logs = [];
    }
}
 
// Usage in tests
let testLogger: IntegrationTestLogger;
 
beforeEach(() => {
    testLogger = new IntegrationTestLogger();
    // Inject logger into services
    orderService.setLogger(testLogger);
    inventoryService.setLogger(testLogger);
});
 
afterEach(function() {
    // 'this' in Jest/Mocha contains test state
    if (this.currentTest?.state === 'failed') {
        testLogger.dumpOnFailure();
    }
    testLogger.clear();
});
 
// ===== STRATEGY 2: Database State Snapshots =====
class DatabaseDebugger {
    async snapshotState(label: string): Promise<void> {
        const tables = await this.getAllTables();
        const snapshot: Record<string, unknown[]> = {};
        
        for (const table of tables) {
            snapshot[table] = await this.db.query(
                `SELECT * FROM ${table} ORDER BY id`
            );
        }
        
        console.log(`\n=== DB Snapshot: ${label} ===`);
        console.log(JSON.stringify(snapshot, null, 2));
    }
    
    async diffStates(before: string, after: string): Promise<void> {
        // Compare snapshots to see what changed
    }
}
 
// Usage in failing test investigation
it('should update inventory correctly', async () => {
    const debugger = new DatabaseDebugger(testDb);
    
    await debugger.snapshotState('Before order creation');
    
    const order = await orderService.create(validOrder);
    
    await debugger.snapshotState('After order creation');
    
    expect(inventory.quantity).toBe(95); // Why is this failing?
});
 
// ===== STRATEGY 3: Request/Response Recording =====
class HttpRecorder {
    private recordings: HttpExchange[] = [];
    
    recordRequest(req: Request, res: Response): void {
        this.recordings.push({
            request: {
                method: req.method,
                url: req.url,
                headers: req.headers,
                body: req.body,
            },
            response: {
                status: res.status,
                headers: res.headers,
                body: res.body,
            },
            duration: res.timing,
        });
    }
    
    dump(): void {
        console.log('\n=== HTTP Exchanges ===');
        for (const exchange of this.recordings) {
            console.log(`${exchange.request.method} ${exchange.request.url}`);
            console.log(`  Status: ${exchange.response.status}`);
            console.log(`  Duration: ${exchange.duration}ms`);
        }
    }
}
 
// ===== STRATEGY 4: Minimal Reproduction =====
// When a test fails, create the smallest possible test that reproduces it
 
describe('REPRO: Order inventory not decremented', () => {
    // Strip out everything except what's needed to reproduce
    it('minimal reproduction', async () => {
        // 1. Minimal data setup
        await inventoryRepo.save({ sku: 'TEST', quantity: 10 });
        
        // 2. The operation
        await orderService.create({ items: [{ sku: 'TEST', quantity: 1 }] });
        
        // 3. The assertion
        const inv = await inventoryRepo.findBySku('TEST');
        console.log('Inventory after:', inv);
        expect(inv?.quantity).toBe(9);
    });
});

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

// ===== STRATEGY 1: Parallel Test Files, Isolated Databases =====
// Each test file gets its own database schema or database instance
 
// jest.config.js
module.exports = {
    maxWorkers: 4, // Run 4 test files in parallel
    globalSetup: './test/globalSetup.ts',
    globalTeardown: './test/globalTeardown.ts',
};
 
// globalSetup.ts - Create worker-specific databases
export default async function() {
    const workerCount = parseInt(process.env.JEST_WORKERS || '4');
    
    for (let i = 1; i <= workerCount; i++) {
        await createDatabase(`testdb_worker_${i}`);
        await runMigrations(`testdb_worker_${i}`);
    }
}
 
// testSetup.ts - Each worker uses its own database
const workerId = process.env.JEST_WORKER_ID || '1';
const databaseUrl = `postgres://localhost/testdb_worker_${workerId}`;
 
export const testDb = new TestDatabase(databaseUrl);
 
// ===== STRATEGY 2: Schema-Per-Test Isolation =====
// Each test creates its own schema within a shared database
 
describe('Order Tests', () => {
    let schema: string;
    
    beforeAll(async () => {
        schema = `test_${Date.now()}_${randomId()}`;
        await db.query(`CREATE SCHEMA ${schema}`);
        await db.query(`SET search_path TO ${schema}`);
        await runMigrations();
    });
    
    afterAll(async () => {
        await db.query(`DROP SCHEMA ${schema} CASCADE`);
    });
    
    // Tests run in isolated schema
});
 
// ===== STRATEGY 3: Data Namespacing =====
// Tests use prefixed IDs to avoid collisions without separate databases
 
const testPrefix = `test-${Date.now()}-${workerId}`;
 
function createTestId(entity: string): string {
    return `${testPrefix}-${entity}-${randomId()}`;
}
 
// Each test's data is namespaced
it('should process order', async () => {
    const customerId = createTestId('customer');
    const orderId = createTestId('order');
    
    await customerRepo.save({ id: customerId, name: 'Test' });
    const order = await orderService.create({
        id: orderId,
        customerId,
    });
    
    // Cleanup only our namespaced data
    await orderRepo.deleteByPrefix(testPrefix);
    await customerRepo.deleteByPrefix(testPrefix);
});
 
// ===== STRATEGY 4: Sharding Across CI Runners =====
// Distribute tests across multiple CI machines
 
// package.json
{
    "scripts": {
        "test:shard": "jest --shard=$SHARD_INDEX/$TOTAL_SHARDS"
    }
}
 
// GitHub Actions
jobs:
  test:
    strategy:
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - run: npm run test:shard
        env:
          SHARD_INDEX: ${{ matrix.shard }}
          TOTAL_SHARDS: 4