pos-system/docs/en/skills/testing-patterns.md

Testing Patterns

EN: Comprehensive testing best practices for GoodGo microservices including unit tests, integration tests, E2E tests, Jest configuration, mocking strategies, and debugging techniques. VI: Các thực hành tốt nhất về testing cho microservices GoodGo bao gồm unit tests, integration tests, E2E tests, cấu hình Jest, strategies mocking, và kỹ thuật debugging.

Overview / Tổng Quan

EN: Testing is a critical component of the GoodGo microservices platform. This guide provides comprehensive patterns and best practices for writing maintainable, reliable tests across all services. It covers test types, Jest configuration, mocking strategies, test utilities, and debugging techniques that ensure code quality and reliability.

VI: Testing là thành phần quan trọng của nền tảng microservices GoodGo. Hướng dẫn này cung cấp các patterns và best practices toàn diện để viết các test có thể bảo trì và đáng tin cậy trên tất cả các services. Nó bao gồm các loại test, cấu hình Jest, strategies mocking, test utilities, và kỹ thuật debugging để đảm bảo chất lượng và độ tin cậy của code.

When to Use / Khi Nào Sử Dụng

EN: Use these testing patterns when:

• Writing unit tests for services, controllers, or repositories
• Creating integration tests for middleware chains
• Building E2E tests for API endpoints
• Setting up Jest configuration for a new service
• Mocking external dependencies (Prisma, Redis, Auth SDK)
• Debugging test failures
• Improving test coverage
• Creating test utilities and factories

VI: Sử dụng các testing patterns này khi:

• Viết unit tests cho services, controllers, hoặc repositories
• Tạo integration tests cho middleware chains
• Xây dựng E2E tests cho API endpoints
• Thiết lập cấu hình Jest cho service mới
• Mocking các dependencies bên ngoài (Prisma, Redis, Auth SDK)
• Debugging test failures
• Cải thiện test coverage
• Tạo test utilities và factories

Key Concepts / Khái Niệm Chính

Test Types / Các Loại Test

1. Unit Tests / Unit Tests

EN: Test individual functions or classes in isolation with all dependencies mocked.

VI: Test các functions hoặc classes riêng lẻ một cách cô lập với tất cả dependencies được mock.

Characteristics:

• Location: Next to source files (*.test.ts) or in __tests__/ directory
• Scope: Single function, method, or class
• Dependencies: All external dependencies mocked
• Speed: Fast (<1s per test)
• Purpose: Verify logic correctness

Example: services/iam-service/src/modules/feature/__tests__/feature.service.test.ts

2. Integration Tests / Integration Tests

EN: Test multiple components working together with some real dependencies.

VI: Test nhiều components làm việc cùng nhau với một số dependencies thật.

Characteristics:

• Location: __tests__/ directory (*.test.ts)
• Scope: Multiple components interacting
• Dependencies: Mix of real and mocked dependencies
• Speed: Medium (1-5s per test)
• Purpose: Verify component integration

Example: services/iam-service/src/middlewares/__tests__/auth.middleware.test.ts

3. E2E Tests / E2E Tests

EN: Test complete request/response cycles through the entire application stack.

VI: Test các chu kỳ request/response hoàn chỉnh qua toàn bộ application stack.

Characteristics:

• Location: __tests__/*.e2e.ts
• Scope: Full API workflow from HTTP request to response
• Dependencies: Test database, mocked external services
• Speed: Slow (5-10s per test)
• Purpose: Verify end-to-end functionality

Example: services/iam-service/src/__tests__/feature.e2e.ts

Jest Configuration / Cấu Hình Jest

Standard Configuration

The standard Jest configuration for GoodGo services includes TypeScript support, coverage thresholds, and proper test environment setup.

Location: services/iam-service/jest.config.ts

import type { Config } from 'jest';

const config: Config = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  roots: ['<rootDir>/src'],
  testMatch: [
    '**/__tests__/**/*.test.ts',
    '**/__tests__/**/*.spec.ts',
    '**/__tests__/**/*.e2e.ts',
    '**/?(*.)+(spec|test).ts'
  ],
  collectCoverageFrom: [
    'src/**/*.ts',
    '!src/**/*.d.ts',
    '!src/main.ts',
    '!src/config/**/*.ts',
    '!src/**/*.config.ts'
  ],
  coverageDirectory: 'coverage',
  coverageReporters: ['text', 'lcov', 'html'],
  coverageThreshold: {
    global: {
      branches: 70,
      functions: 70,
      lines: 70,
      statements: 70
    }
  },
  setupFilesAfterEnv: ['<rootDir>/src/__tests__/setupTests.ts'],
  testTimeout: 10000,
  clearMocks: true,
  resetModules: true
};

export default config;

Key Configuration Points

• preset: 'ts-jest': Enables TypeScript support
• testEnvironment: 'node': Sets Node.js environment (not browser)
• coverageThreshold: Enforces minimum 70% coverage across all metrics
• setupFilesAfterEnv: Loads test setup file before each test suite
• clearMocks: Automatically clears mock calls between tests
• resetModules: Resets module cache for test isolation

Setup Files / Files Thiết Lập

Test Setup File

The setup file (setupTests.ts) configures global mocks and test utilities that are available across all tests.

Location: services/iam-service/src/__tests__/setupTests.ts

Key Features:

• Mock external services (logger, tracing, database, Redis)
• Configure test environment variables
• Set up global test utilities
• Initialize Prometheus mocks

Example:

import { jest } from '@jest/globals';

// EN: Mock environment variables for tests
// VI: Mock biến môi trường cho tests
process.env.NODE_ENV = 'test';
process.env.DATABASE_URL = 'postgresql://test:test@localhost:5432/test_db';
process.env.REDIS_URL = 'redis://localhost:6379/1';

// EN: Mock external services to avoid real network calls
// VI: Mock các service bên ngoài để tránh gọi mạng thật
jest.mock('@goodgo/logger', () => ({
  logger: {
    info: jest.fn(),
    error: jest.fn(),
    warn: jest.fn(),
    debug: jest.fn(),
  },
}));

// EN: Global test utilities
// VI: Utilities test toàn cục
global.testUtils = {
  createMockReq: (overrides = {}) => ({
    body: {},
    params: {},
    query: {},
    headers: {},
    ...overrides,
  }),
  createMockRes: () => {
    const res: any = {};
    res.status = jest.fn().mockReturnValue(res);
    res.json = jest.fn().mockReturnValue(res);
    res.send = jest.fn().mockReturnValue(res);
    return res;
  },
  createMockNext: () => jest.fn(),
};

Common Patterns / Các Pattern Thường Dùng

Unit Test Pattern

Structure: Follow the AAA (Arrange-Act-Assert) pattern for clarity.

describe('FeatureService', () => {
  let service: FeatureService;
  let mockRepository: any;

  beforeEach(() => {
    // EN: Clear all mocks before each test
    // VI: Xóa tất cả mocks trước mỗi test
    jest.clearAllMocks();
    
    mockRepository = {
      findById: jest.fn(),
      create: jest.fn(),
    };
    service = new FeatureService(mockRepository);
  });

  describe('create', () => {
    it('should create a feature successfully', async () => {
      // EN: Arrange
      // VI: Chuẩn bị
      const testData = { name: 'test-feature', title: 'Test Feature' };
      const mockFeature = {
        id: 'test-id',
        name: testData.name,
        // ... other fields
      };
      mockRepository.create.mockResolvedValue(mockFeature);

      // EN: Act
      // VI: Thực hiện
      const result = await service.create(testData);

      // EN: Assert
      // VI: Kiểm tra
      expect(mockRepository.create).toHaveBeenCalledWith(testData);
      expect(result).toEqual(mockFeature);
    });
  });
});

Real Example: services/iam-service/src/modules/feature/__tests__/feature.service.test.ts

Integration Test Pattern

Integration tests verify that multiple components work together correctly.

describe('Auth Middleware', () => {
  const mockNext = jest.fn();

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

  it('should authenticate valid token and attach user to request', () => {
    // EN: Arrange
    // VI: Chuẩn bị
    const mockReq = createMockReq({
      headers: { authorization: 'Bearer valid-token' },
    });
    const mockRes = createMockRes();

    // EN: Act
    // VI: Thực hiện
    const middleware = authenticate({ secret: jwtSecret });
    middleware(mockReq as Request, mockRes as Response, mockNext);

    // EN: Assert
    // VI: Kiểm tra
    expect(mockNext).toHaveBeenCalled();
    expect(mockReq.user).toBeDefined();
  });
});

Real Example: services/iam-service/src/middlewares/__tests__/auth.middleware.test.ts

E2E Test Pattern

E2E tests use supertest to test complete HTTP request/response cycles.

import request from 'supertest';
import express from 'express';
import { createRouter } from '../routes';

describe('Feature Endpoints E2E', () => {
  let app: express.Application;

  beforeAll(() => {
    // EN: Set up test environment
    // VI: Thiết lập môi trường test
    process.env.NODE_ENV = 'test';
    app = express();
    app.use(express.json());
    app.use(createRouter());
  });

  describe('POST /api/v1/features', () => {
    it('should create a feature successfully', async () => {
      // EN: Arrange
      // VI: Chuẩn bị
      const featureData = {
        name: 'test-feature',
        title: 'Test Feature',
        description: 'A test feature for E2E testing'
      };

      // EN: Act
      // VI: Thực hiện
      const response = await request(app)
        .post('/api/v1/features')
        .send(featureData)
        .expect(201);

      // EN: Assert
      // VI: Kiểm tra
      expect(response.body).toMatchObject({
        success: true,
        message: 'Feature created successfully / Feature đã được tạo thành công',
      });
    });
  });
});

Real Example: services/iam-service/src/__tests__/feature.e2e.ts

Mocking Strategies / Chiến Lược Mocking

Mock Prisma Database

Mock Prisma client to avoid real database connections in unit tests.

// In setupTests.ts or individual test files
jest.mock('../config/database.config', () => ({
  connectDatabase: jest.fn(),
  prisma: {
    $queryRaw: jest.fn(),
    $disconnect: jest.fn(),
    feature: {
      create: jest.fn(),
      findMany: jest.fn(),
      findUnique: jest.fn(),
      update: jest.fn(),
      delete: jest.fn(),
    },
  },
}));

// Usage in tests
const { prisma } = require('../config/database.config');

test('should create user', async () => {
  prisma.feature.create.mockResolvedValue({
    id: 'test-id',
    name: 'test-feature',
    // ... other fields
  });
  
  const result = await createFeature({ name: 'test-feature' });
  expect(result).toBeDefined();
});

Mock Redis

Mock Redis client for caching and session management tests.

jest.mock('../config/redis.config', () => ({
  getRedisClient: jest.fn().mockReturnValue({
    call: jest.fn(),
    connect: jest.fn(),
    disconnect: jest.fn(),
  }),
}));

Mock External APIs

Mock external HTTP calls using Jest mocks.

jest.mock('axios');
import axios from 'axios';
const mockedAxios = axios as jest.Mocked<typeof axios>;

test('should fetch external data', async () => {
  mockedAxios.get.mockResolvedValue({ 
    data: { result: 'success' } 
  });
  
  const result = await fetchExternalData();
  expect(result).toEqual({ result: 'success' });
});

Mock Auth SDK

Mock authentication SDK functions for middleware and service tests.

jest.mock('@goodgo/auth-sdk', () => ({
  createToken: jest.fn(),
  verifyToken: jest.fn(),
  extractTokenFromHeader: jest.fn(),
}));

// Setup mock implementations
(verifyToken as jest.Mock).mockImplementation((token) => {
  if (token === 'valid-token') {
    return { userId: '123', role: 'user' };
  }
  throw new Error('Invalid token');
});

Testing Utilities / Utilities Test

Test Factory Pattern

Create reusable test data factories for consistent test data.

export class TestFactory {
  static createUser(overrides = {}) {
    return {
      id: 'test-user-1',
      email: 'test@example.com',
      name: 'Test User',
      createdAt: new Date(),
      ...overrides
    };
  }

  static createAuthToken(userId: string) {
    return jwt.sign({ userId }, 'test-secret');
  }

  static async cleanDatabase() {
    await prisma.user.deleteMany();
    await prisma.feature.deleteMany();
  }
}

// Usage
const user = TestFactory.createUser({ name: 'Custom Name' });
const token = TestFactory.createAuthToken(user.id);

Mock Request/Response Helpers

Use global test utilities for creating mock Express request/response objects.

// Available via global.testUtils (from setupTests.ts)
const mockReq = global.testUtils.createMockReq({
  headers: { authorization: 'Bearer token' },
  params: { id: '123' },
});

const mockRes = global.testUtils.createMockRes();
const mockNext = global.testUtils.createMockNext();

Common Test Scenarios / Các Tình Huống Test Thường Gặp

Testing Error Handling

it('should handle database errors gracefully', async () => {
  // EN: Arrange - Mock database error
  // VI: Chuẩn bị - Mock lỗi database
  prismaMock.user.findUnique.mockRejectedValue(
    new Error('Database connection failed')
  );
  
  // EN: Act & Assert
  // VI: Thực hiện & Kiểm tra
  await expect(userService.findById('123')).rejects.toThrow();
  
  // Or for HTTP endpoints
  const response = await request(app)
    .get('/api/users/123')
    .expect(500);
    
  expect(response.body).toEqual({
    success: false,
    error: {
      code: 'INTERNAL_ERROR',
      message: 'Internal server error / Lỗi máy chủ nội bộ',
    },
  });
});

Testing Validation

describe('Validation', () => {
  it('should reject invalid email', async () => {
    const response = await request(app)
      .post('/api/auth/register')
      .send({ email: 'invalid-email', password: '123456' })
      .expect(400);
      
    expect(response.body.error.code).toBe('VALIDATION_ERROR');
  });
});

Testing Authorization

it('should deny access for user with incorrect role', () => {
  const mockReq = createMockReq({
    user: { userId: 'user-123', role: 'user' },
  });
  
  const middleware = authorize('admin');
  middleware(mockReq as Request, mockRes as Response, mockNext);
  
  expect(mockNext).not.toHaveBeenCalled();
  expect(mockStatus).toHaveBeenCalledWith(403);
});

Test Commands / Lệnh Test

Add these scripts to package.json:

{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch",
    "test:coverage": "jest --coverage",
    "test:unit": "jest --testPathPattern=\\.test\\.ts$",
    "test:e2e": "jest --testPathPattern=\\.e2e\\.ts$",
    "test:ci": "jest --coverage --silent --maxWorkers=2"
  }
}

Usage:

• pnpm test: Run all tests
• pnpm test:watch: Run tests in watch mode
• pnpm test:coverage: Generate coverage report
• pnpm test:unit: Run only unit tests
• pnpm test:e2e: Run only E2E tests
• pnpm test:ci: Run tests optimized for CI/CD

Debugging Tests / Debugging Tests

VS Code Debug Configuration

Create .vscode/launch.json for debugging tests:

{
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Jest Tests",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["test", "--", "--runInBand"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    }
  ]
}

Debug Tips

1. Use test.only() to run a single test:

   it.only('should test specific behavior', () => {
     // Only this test will run
   });
   

2. Use --detectOpenHandles for async issues:

   pnpm test --detectOpenHandles
   

3. Use --runInBand for sequential execution:

   pnpm test --runInBand
   

4. Add temporary console.log:

   console.log('Debug value:', someValue);
   

5. Use debugger breakpoints in VS Code

Best Practices / Thực Hành Tốt Nhất

Test Organization

• ✅ Each test is independent and isolated
• ✅ Tests follow AAA pattern (Arrange-Act-Assert)
• ✅ Use descriptive test names that explain what is being tested
• ✅ Group related tests using describe blocks
• ✅ Use beforeEach/afterEach for setup/cleanup

Mocking

• ✅ Mock external dependencies (database, APIs, services)
• ✅ Use jest.clearAllMocks() in beforeEach to reset mocks
• ✅ Verify mock calls to ensure correct behavior
• ✅ Keep mocks simple and focused

Coverage

• ✅ Maintain >70% code coverage (as per Jest config)
• ✅ Focus on covering critical business logic
• ✅ Don't sacrifice test quality for coverage percentage
• ✅ Review coverage reports regularly

Test Data

• ✅ Use factories for creating test data
• ✅ Keep test data realistic and representative
• ✅ Clean up test data after tests (if using real database)
• ✅ Use meaningful test values, not just 'test' or 123

Error Testing

• ✅ Test both success and error scenarios
• ✅ Test edge cases and boundary conditions
• ✅ Test validation errors
• ✅ Test error messages and error codes

Performance

• ✅ Keep unit tests fast (<1s each)
• ✅ Avoid unnecessary async operations in unit tests
• ✅ Use --maxWorkers in CI for parallel execution
• ✅ Don't test implementation details, test behavior

Examples from Project / Ví Dụ Từ Dự Án

Real Test Examples

1. Unit Test: services/iam-service/src/modules/feature/__tests__/feature.service.test.ts
2. Integration Test: services/iam-service/src/middlewares/__tests__/auth.middleware.test.ts
3. E2E Test: services/iam-service/src/__tests__/feature.e2e.ts
4. Setup File: services/iam-service/src/__tests__/setupTests.ts
5. Jest Config: services/iam-service/jest.config.ts

Test Structure Examples

• Repository Tests: services/iam-service/src/modules/feature/__tests__/feature.repository.test.ts
• Controller Tests: services/iam-service/src/modules/health/__tests__/health.controller.test.ts
• Middleware Tests: services/iam-service/src/middlewares/__tests__/correlation.middleware.test.ts

Quick Reference / Tham Khảo Nhanh

Test Type Decision Tree

Need to test complete HTTP flow?
├─ Yes → E2E Test (*.e2e.ts)
└─ No → Multiple components interacting?
    ├─ Yes → Integration Test (*.test.ts)
    └─ No → Unit Test (*.test.ts)

Common Jest Matchers

Matcher	Purpose	Example
toBe()	Exact equality	expect(value).toBe(5)
toEqual()	Deep equality	expect(obj).toEqual({a: 1})
toMatchObject()	Partial match	expect(obj).toMatchObject({a: 1})
toHaveBeenCalled()	Function called	expect(mockFn).toHaveBeenCalled()
toHaveBeenCalledWith()	Called with args	expect(mockFn).toHaveBeenCalledWith('arg')
toThrow()	Throws error	expect(() => fn()).toThrow()
toBeDefined()	Not undefined	expect(value).toBeDefined()
toBeNull()	Is null	expect(value).toBeNull()
toContain()	Array/string contains	expect(array).toContain('item')

Mock Function Helpers

// Create mock
const mockFn = jest.fn();

// Set return value
mockFn.mockReturnValue('value');
mockFn.mockResolvedValue('async value');
mockFn.mockRejectedValue(new Error('error'));

// Set implementation
mockFn.mockImplementation((arg) => arg * 2);

// Clear/reset
mockFn.mockClear();      // Clear call history
mockFn.mockReset();      // Reset to initial state
jest.clearAllMocks();    // Clear all mocks

Related Skills / Skills Liên Quan

• Comment Code: Writing bilingual comments in tests
• Security: Testing security-critical code
• API Design: Testing API endpoints and responses
• Project Rules: Code organization for tests

Resources / Tài Nguyên

Official Documentation

• Jest Documentation
• Supertest Documentation
• jest-mock-extended

Internal Documentation

• Service Development Guide
• Local Development Setup
• Troubleshooting Guide

Tools

• Jest: JavaScript testing framework
• Supertest: HTTP assertion library
• jest-mock-extended: Enhanced mocking for TypeScript
• ioredis-mock: Redis mock for testing