TEST_MOCKING_STANDARDIZATION.md

Test Mocking Standardization - Implementation Summary

Overview

This document summarizes the standardization of mocking patterns across the TeachLink backend test suite.

Date: April 24, 2026
Status: Complete
Files Modified/Created: 5

---

What Was Done

1. Documentation Created

docs/testing-standards.md

• Comprehensive guide covering all mocking patterns
• Detailed explanations of when to use each approach
• Best practices for Jest mocks and TypeORM testing
• Common testing scenarios with examples
• Troubleshooting guide

docs/TESTING_GUIDELINES.md

• Quick-start guide for developers
• Three testing patterns with examples
• Mock factory reference
• Test structure templates
• Migration guide for existing tests
• Quick reference cards

2. Mock Factory Library Created

test/utils/mock-factories.ts

Provides 13 reusable mock factory functions:

• createMockRepository<T>() - TypeORM Repository with all standard methods
• createMockQueryBuilder<T>() - TypeORM QueryBuilder for complex queries
• createMockCachingService() - Full CachingService mock
• createMockRedisClient() - Redis client (ioredis API)
• createMockBullQueue<T>() - Bull job queue
• createMockHttpClient() - NestJS HttpService
• createMockConfigService() - ConfigService with config map
• createMockMailer() - Nodemailer transporter
• createMockEventEmitter() - EventEmitter2 instance
• createMockExecutionContext() - For testing guards
• createMockS3Client() - AWS S3 client
• createMockElasticsearchClient() - Elasticsearch client
• createPartialMock<T>() - Helper for deep partial mocks

Each factory:

• Uses proper jest.Mocked<T> typing
• Includes all commonly-used methods
• Has sensible default implementations
• Is fully documented with JSDoc comments

3. Sample Tests Refactored

Three test files were refactored to demonstrate the standardized approach:

src/users/users.service.spec.ts

• Replaced untyped any mocks with properly typed mocks
• Added mock factories usage
• Added afterEach cleanup
• Improved comments and structure
• Better variable naming (mockRepository instead of repo)

src/caching/caching.service.spec.ts

• Replaced inline Redis mock with createMockRedisClient()
• Replaced inline ConfigService mock with createMockConfigService()
• Added afterEach cleanup
• Improved consistency and maintainability

src/media/media.service.spec.ts

• Replaced untyped mocks with jest.Mocked<any> typing
• Improved comments and organization
• Added afterEach cleanup
• Better variable naming (prefix with mock)

---

Key Changes Overview

Before (Inconsistent Patterns)

// Pattern 1: Untyped, manual objects
let userRepository: any;
beforeEach(() => {
  userRepository = {
    createQueryBuilder: jest.fn().mockReturnValue(queryBuilder),
  };
});

// Pattern 2: Manual Redis mock (100+ lines)
let mockRedis = {
  get: jest.fn(),
  set: jest.fn(),
  // ... 20+ other methods manually listed
};

// Pattern 3: No types, unclear structure
let service: any;
let cache: any;
let storage: any;

After (Standardized Patterns)

// Import factories once
import { createMockRepository, createMockRedisClient } from 'test/utils/mock-factories';

// Use typed mocks with single line
let mockRepository: jest.Mocked<Repository<User>>;
let mockRedis: jest.Mocked<Redis>;

beforeEach(() => {
  mockRepository = createMockRepository<User>();
  mockRedis = createMockRedisClient();
  service = new Service(mockRepository, mockRedis);
});

---

Three Testing Patterns

Pattern A: NestJS Integration Testing

For controllers, complex services, infrastructure testing

const module: TestingModule = await Test.createTestingModule({
  controllers: [UserController],
  providers: [UserService, { provide: CachingService, useValue: mockCache }],
}).compile();

Pattern B: Direct Service Instantiation

For unit testing service logic in isolation

service = new UserService(mockRepository, mockCache);

Pattern C: Pure Function Testing

For utilities and validators with no mocks

expect(validateEmail('test@example.com')).toBe(true);

---

Usage Instructions

For New Tests

1. Import mock factories at top of file:

   import { createMockRepository, createMockCachingService } from 'test/utils/mock-factories';

2. Use in beforeEach:

   beforeEach(() => {
     mockRepository = createMockRepository<User>();
     mockCache = createMockCachingService();
     service = new Service(mockRepository, mockCache);
   });

3. Clean up in afterEach:

   afterEach(() => {
     jest.clearAllMocks();
   });

For Existing Tests

Refactor gradually:

1. Identify pattern (A, B, or C)
2. Replace manual mocks with factory functions
3. Add type annotations (jest.Mocked<T>)
4. Add afterEach cleanup
5. Run tests to verify: npm run test

Reference docs/TESTING_GUIDELINES.md "Migration Guide" section.

---

Benefits of Standardization

Before

• ❌ Inconsistent mocking approaches across codebase
• ❌ Manual mock setup (100+ lines for complex services)
• ❌ Untyped mocks leading to runtime errors
• ❌ Duplicate mock code across multiple test files
• ❌ Difficult to maintain/update mocks

After

• ✅ Single standardized approach per pattern
• ✅ Reusable mock factories (copy-paste mocking patterns)
• ✅ Full TypeScript type safety with jest.Mocked<T>
• ✅ DRY principle - mocks defined once, used everywhere
• ✅ Easy to maintain and update mocks centrally
• ✅ Clear documentation for all testing patterns
• ✅ Faster test file creation
• ✅ Improved test reliability

---

Quick Reference

Import Factories

import { createMockRepository, createMockRedisClient } from 'test/utils/mock-factories';

Create Mocks

const mockRepo = createMockRepository<User>();
const mockRedis = createMockRedisClient();
const mockCache = createMockCachingService();
const mockQueue = createMockBullQueue();
const mockHttp = createMockHttpClient();

Set Mock Return Values

// Async
mockRepo.findOne.mockResolvedValue({ id: '1' });
mockHttp.get.mockReturnValue(of({ data }));

// Sync
mockService.validate.mockReturnValue(true);

// Implementation
mockService.process.mockImplementation((x) => x * 2);

Assert Mock Calls

expect(mockRepo.findOne).toHaveBeenCalled();
expect(mockRepo.findOne).toHaveBeenCalledWith({ where: { id: '1' } });
expect(mockService.save).toHaveBeenCalledTimes(1);

Clean Up

afterEach(() => {
  jest.clearAllMocks();
});

---

Documentation Files

All documentation is in the docs/ directory:

File	Purpose
testing-standards.md	Comprehensive mocking patterns and best practices
TESTING_GUIDELINES.md	Quick-start guide for developers
test/utils/mock-factories.ts	Mock factory implementations

---

Next Steps

1. Immediate: Developers should reference TESTING_GUIDELINES.md when writing tests

2. Gradual Migration: Refactor existing test files using the migration guide:

   • Focus on critical services first
   • Use pattern consistency as guide
   • Run full test suite after each refactoring

3. Code Review: When reviewing test PRs:

   • Check for mock factory usage
   • Verify jest.Mocked<T> typing
   • Ensure afterEach cleanup
   • Recommend standardization for inconsistent patterns

4. CI/CD: Ensure tests pass in CI:

   npm run test:ci

---

Examples for Reference

Refactored Test File Example

See src/users/users.service.spec.ts for a complete example of standardized mocking.

Factory Usage Examples

See test/utils/mock-factories.ts JSDoc comments for detailed usage of each factory.

---

Troubleshooting

Issue	Solution	Docs
Import fails	Check tsconfig.json has "baseUrl": "."	TESTING_GUIDELINES.md
Type errors	Ensure "jest" in types array	TESTING_GUIDELINES.md
Mock not called	Use mockResolvedValue for async	TESTING_GUIDELINES.md
Tests fail in CI	Add afterEach cleanup	TESTING_GUIDELINES.md

---

Test Commands

# Run all tests
npm run test

# Watch mode for development
npm run test:watch

# Coverage report
npm run test:cov

# Specific test file
npm run test -- src/users/users.service.spec.ts

# Pattern matching
npm run test -- --testNamePattern="findById"

# CI pipeline
npm run test:ci

---

Metrics

• Documentation Pages: 2 (testing-standards.md + TESTING_GUIDELINES.md)
• Mock Factories: 13 reusable factory functions
• Total Mock Methods: 100+ methods across all factories
• Sample Tests Refactored: 3 (users, caching, media)
• Estimated Time Savings: 2-3 hours per new test file (vs. manual mocking)

---

Questions?

Refer to:

1. docs/TESTING_GUIDELINES.md - Quick answers for developers
2. docs/testing-standards.md - Deep dive into patterns
3. test/utils/mock-factories.ts - Implementation details
4. Refactored test files as working examples

---

Standardization Complete ✅
Ready for adoption across the TeachLink backend project.