Backend Testing

Patterns

1. Mock dependencies at module level

jest.mock('../../../src/models/exerciseModel');
jest.mock('../../../src/models/workoutDayModel');

const mockExerciseModel = ExerciseModel as jest.Mocked<typeof ExerciseModel>;
const mockWorkoutDayModel = WorkoutDayModel as jest.Mocked<typeof WorkoutDayModel>;

2. Controllers – mock req/res

req = { params: {}, body: {} };
res = { status: jest.fn().mockReturnThis(), json: jest.fn().mockReturnThis() };

3. Services – mock models, assert calls

mockWorkoutDayModel.exists.mockResolvedValue(true);
mockExerciseModel.create.mockResolvedValue(created);

const result = await ExerciseService.create(input);

expect(mockWorkoutDayModel.exists).toHaveBeenCalledWith(1);
expect(mockExerciseModel.create).toHaveBeenCalledWith(input);
expect(result).toEqual(created);

4. Cleanup

beforeEach(() => jest.clearAllMocks());
afterEach(() => consoleErrorSpy?.mockRestore());

Coverage

• Excluded: src/index.ts, src/config/database.ts
• Reports: coverage/ (lcov)

Integration Tests

Purpose

Test API routes with a real database, no mocks. Exercise request validation, DB queries, and error handling without running the full container stack.

When to Add

• Need to verify SQL, transactions, or DB constraints
• Want faster feedback than component tests
• Component tests are too heavy for a given change

Suggested Setup (if adding)

1. Config: jest.config.integration.js with testMatch: ['**/test/integration/**/*.test.ts']
2. DB: Use test DB (e.g. xq_fitness with test credentials) or Docker Compose
3. Pattern: Start Express app, use supertest against app, run migrations, seed if needed
4. Cleanup: Truncate tables or use transactions per test

Example Pattern

import request from 'supertest';
import app from '../../src/app';

describe('POST /api/v1/routines', () => {
  it('creates routine and persists to DB', async () => {
    const res = await request(app)
      .post('/api/v1/routines')
      .send({ name: 'Test', isActive: true })
      .expect(201);
    expect(res.body.id).toBeDefined();
    // Optionally query DB to verify
  });
});

Component Tests

Component tests hit the live API over HTTP with a real database. Follow the project workflow.

Reference

Use the component-test rule: .cursor/rules/component-test.mdc (or write-service/.cursor/rules/component-test.mdc).

Quick Workflow

1. Build: ./build-write-service.sh (from write-service root)
2. Client: npm run generate:client then npm install
3. Env: xq-infra generate -f ./test-env and xq-infra up
4. Run: npm run test:component or npm run test:component:ci
5. Teardown: xq-infra down

Structure

• Tests: test/component/workflows/**/*.test.ts
• Helpers: test/component/helpers/ (api-client, test-data, cleanup, database)
• Setup/Teardown: test/component/setup.ts, teardown.ts
• Config: jest.config.component.js (uses @chauhaidang/xq-test-utils)

Patterns

• Use ApiClient from helpers/api-client.ts (generated client wrapper)
• Use testData from helpers/test-data.ts for unique payloads
• Use CleanupHelper to track and delete created resources
• Use DatabaseHelper from @chauhaidang/xq-test-utils for DB assertions
• Default URLs: API_BASE_URL, HEALTH_CHECK_URL (test-env gateway on 8080)

Port Conflicts

If startup fails, check for other stacks (e.g. read-service) using the same ports. Run xq-infra down in other service directories.

Summary Checklist

Unit tests

• Mock all external modules (models, services)
• Use jest.clearAllMocks() in beforeEach
• Assert both return values and mock call arguments

Component tests

• Follow .cursor/rules/component-test.mdc
• Build image, generate client, run xq-infra up before tests
• Use CleanupHelper and unique test data

Integration tests (if added)

• Use real DB, no mocks
• Isolate tests (transactions or truncate)
• Use supertest against the Express app