Skip to main content

Documentation Index

Fetch the complete documentation index at: https://resources.devweekends.com/llms.txt

Use this file to discover all available pages before exploring further.

Chapter 7: Testing

Testing is essential for building reliable, maintainable applications. This chapter covers unit, integration, and end-to-end (E2E) testing in NestJS, including mocking strategies, test utilities, CI/CD integration, and best practices. We’ll walk through practical examples and explain how to build a robust test suite.

7.1 Why Test?

Testing provides numerous benefits that make it essential for production applications.

Benefits of Testing

Catch bugs early:
  • Find issues before they reach production
  • Reduce debugging time
  • Prevent regressions
Refactor with confidence:
  • Make changes knowing tests will catch breakages
  • Improve code quality without fear
  • Enable continuous refactoring
Ensure business logic correctness:
  • Verify requirements are met
  • Validate edge cases
  • Confirm expected behavior
Enable continuous delivery:
  • Deploy with confidence
  • Automate quality checks
  • Reduce manual testing
Document expected behavior:
  • Tests serve as living documentation
  • Show how code should be used
  • Provide examples for other developers
Analogy:
Think of tests as a building’s fire alarm system. You do not install fire alarms because you expect fires every day — you install them so that when something goes wrong, you know immediately, before the whole building burns down. Unit tests are smoke detectors in individual rooms (catch small problems fast). Integration tests are sprinkler systems that test whether multiple rooms work together. E2E tests are full fire drills that simulate real emergencies end-to-end. The teams that skip testing are the ones debugging production incidents at 3 AM.

Testing Pyramid

        /\
       /  \      E2E Tests (Few)
      /____\
     /      \     Integration Tests (Some)
    /________\
   /          \   Unit Tests (Many)
  /____________\
Unit Tests (Base):
  • Fast, isolated, many
  • Test individual components
  • Mock all dependencies
Integration Tests (Middle):
  • Test component interactions
  • Use real dependencies where possible
  • Moderate speed
E2E Tests (Top):
  • Test full user flows
  • Use real everything
  • Slow but comprehensive

Testing Strategy Comparison

AspectUnit TestsIntegration TestsE2E Tests
What’s TestedSingle class in isolationMultiple classes togetherFull HTTP request through entire stack
DependenciesAll mockedSome real, some mockedAll real (or containerized)
SpeedFast (1-5ms each)Moderate (50-500ms each)Slow (500ms-5s each)
DatabaseNever touchedIn-memory or test DBReal test database
CatchesLogic errors in one classIntegration errors, DI wiringFull-stack regressions, HTTP contract
ConfidenceNarrow (this function works)Medium (these components work together)Broad (the API works as clients expect)
MaintenanceLow (changes are local)MediumHigh (brittle if API changes)
When They BreakTells you exactly which function failedTells you which interaction failedTells you which endpoint failed
Test CountMany (70% of tests)Some (20% of tests)Few (10% of tests)
Decision Framework — What Should I Test and How?
Code Under TestTest TypeWhy
Service method with business logicUnit test with mocked repositoryFast, tests the logic in isolation
Service + Repository working togetherIntegration test with in-memory DBCatches ORM/query issues
Full API endpoint (auth, validation, response)E2E test with supertestCatches HTTP-level issues
Guard or interceptor logicUnit test with mock ExecutionContextGuards are pure logic, test them like functions
Complex database queryIntegration test with real DBORM-generated SQL may differ from expectation
Validation DTO behaviorUnit test (instantiate DTO, validate)Fast, catches decorator configuration issues
The 80/20 Rule for NestJS Testing: If you only have time for one type of test per feature, write an integration test for the service (real DI, mocked DB) and an E2E test for the happy path. These two tests catch 80% of real-world bugs. Add unit tests for complex business logic and edge cases.

7.2 Unit Testing

Unit tests verify individual components (services, controllers) in isolation. They should be fast and not depend on external systems.

Setting Up Tests

NestJS comes with Jest configured by default. Test files should end with .spec.ts and live next to the file they test (not in a separate __tests__ directory). This co-location makes it obvious which code has tests and which does not. The key utility is Test.createTestingModule() — it creates a mini NestJS application context for your test, wiring up DI exactly like the real app. This means you can swap real providers for mocks and test components in isolation while still using NestJS’s DI system.
// users/users.service.spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { UsersService } from './users.service';

describe('UsersService', () => {
  let service: UsersService;

  beforeEach(async () => {
    // Test.createTestingModule() mirrors @Module() -- it accepts the same
    // metadata (providers, controllers, imports). The key difference: you
    // control exactly what goes in, letting you substitute mocks for real
    // databases, HTTP clients, etc.
    const module: TestingModule = await Test.createTestingModule({
      providers: [UsersService],
    }).compile();  // .compile() resolves all dependencies and creates instances

    // module.get() retrieves a provider from the test DI container.
    // This is the same instance that would be injected into a controller.
    service = module.get<UsersService>(UsersService);
  });

  it('should be defined', () => {
    expect(service).toBeDefined();
  });
});
Practical Tip: If Test.createTestingModule().compile() throws “Nest can’t resolve dependencies,” you are missing a provider or mock in the test module. Check that every dependency in the constructor is either provided directly or mocked.

Basic Service Test

// users/users.service.spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { UsersService } from './users.service';
import { UserRepository } from './user.repository';

describe('UsersService', () => {
  let service: UsersService;
  let repository: UserRepository;

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [
        UsersService,
        {
          provide: UserRepository,
          useValue: {
            findAll: jest.fn(),
            findOne: jest.fn(),
            create: jest.fn(),
            update: jest.fn(),
            remove: jest.fn(),
          },
        },
      ],
    }).compile();

    service = module.get<UsersService>(UsersService);
    repository = module.get<UserRepository>(UserRepository);
  });

  it('should be defined', () => {
    expect(service).toBeDefined();
  });

  describe('findAll', () => {
    it('should return an array of users', async () => {
      const users = [{ id: 1, name: 'John' }];
      jest.spyOn(repository, 'findAll').mockResolvedValue(users);

      const result = await service.findAll();

      expect(result).toEqual(users);
      expect(repository.findAll).toHaveBeenCalled();
    });
  });

  describe('findOne', () => {
    it('should return a user', async () => {
      const user = { id: 1, name: 'John' };
      jest.spyOn(repository, 'findOne').mockResolvedValue(user);

      const result = await service.findOne(1);

      expect(result).toEqual(user);
      expect(repository.findOne).toHaveBeenCalledWith(1);
    });

    it('should throw if user not found', async () => {
      jest.spyOn(repository, 'findOne').mockResolvedValue(null);

      await expect(service.findOne(999)).rejects.toThrow('User not found');
    });
  });

  describe('create', () => {
    it('should create a user', async () => {
      const dto = { name: 'John', email: 'john@example.com' };
      const user = { id: 1, ...dto };
      jest.spyOn(repository, 'create').mockResolvedValue(user);

      const result = await service.create(dto);

      expect(result).toEqual(user);
      expect(repository.create).toHaveBeenCalledWith(dto);
    });
  });
});
Diagram: Unit Test Flow
Test Setup

Mock Dependencies

Create Service Instance

Execute Test

Assert Results

Cleanup

7.3 Mocking Dependencies

Mocking dependencies isolates the unit under test and makes tests fast and predictable.

Mocking Services

const mockUserRepository = {
  findAll: jest.fn(),
  findOne: jest.fn(),
  create: jest.fn(),
  update: jest.fn(),
  remove: jest.fn(),
};

const module = await Test.createTestingModule({
  providers: [
    UsersService,
    {
      provide: UserRepository,
      useValue: mockUserRepository,
    },
  ],
}).compile();

Mocking with Partial

const mockUserRepository: Partial<UserRepository> = {
  findAll: jest.fn().mockResolvedValue([]),
  findOne: jest.fn().mockResolvedValue(null),
};

const module = await Test.createTestingModule({
  providers: [
    UsersService,
    {
      provide: UserRepository,
      useValue: mockUserRepository,
    },
  ],
}).compile();

Mocking Modules

const module = await Test.createTestingModule({
  providers: [UsersService],
})
  .overrideModule(UsersModule)
  .useModule(TestUsersModule)
  .compile();

Mocking with jest.fn()

describe('UsersService', () => {
  let service: UsersService;
  let repository: jest.Mocked<UserRepository>;

  beforeEach(async () => {
    const mockRepository = {
      findAll: jest.fn(),
      findOne: jest.fn(),
      create: jest.fn(),
    };

    const module = await Test.createTestingModule({
      providers: [
        UsersService,
        {
          provide: UserRepository,
          useValue: mockRepository,
        },
      ],
    }).compile();

    service = module.get(UsersService);
    repository = module.get(UserRepository);
  });

  it('should find all users', async () => {
    const users = [{ id: 1, name: 'John' }];
    repository.findAll.mockResolvedValue(users);

    const result = await service.findAll();

    expect(result).toEqual(users);
    expect(repository.findAll).toHaveBeenCalledTimes(1);
  });
});
Tip: Use mocks for unit tests to isolate components. Use real dependencies for integration tests to verify actual interactions. Common Mistake: Over-mocking to the point where tests only verify that mock methods were called, not that the actual logic works. If your test does nothing but check expect(repository.create).toHaveBeenCalledWith(dto), you are testing the wiring, not the behavior. A good unit test verifies the output given specific inputs, and uses mocks only to control the environment. Another Mistake: Forgetting jest.clearAllMocks() in beforeEach. Without it, mock call counts and return values leak between tests, causing flaky failures that are maddening to debug.

7.4 Testing Controllers

Controllers handle HTTP requests and should be tested with mocked services.

Controller Test Example

// users/users.controller.spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

describe('UsersController', () => {
  let controller: UsersController;
  let service: UsersService;

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      controllers: [UsersController],
      providers: [
        {
          provide: UsersService,
          useValue: {
            findAll: jest.fn(),
            findOne: jest.fn(),
            create: jest.fn(),
            update: jest.fn(),
            remove: jest.fn(),
          },
        },
      ],
    }).compile();

    controller = module.get<UsersController>(UsersController);
    service = module.get<UsersService>(UsersService);
  });

  it('should be defined', () => {
    expect(controller).toBeDefined();
  });

  describe('findAll', () => {
    it('should return an array of users', async () => {
      const users = [{ id: 1, name: 'John' }];
      jest.spyOn(service, 'findAll').mockResolvedValue(users);

      const result = await controller.findAll();

      expect(result).toEqual(users);
      expect(service.findAll).toHaveBeenCalled();
    });
  });

  describe('create', () => {
    it('should create a user', async () => {
      const dto = { name: 'John', email: 'john@example.com' };
      const user = { id: 1, ...dto };
      jest.spyOn(service, 'create').mockResolvedValue(user);

      const result = await controller.create(dto);

      expect(result).toEqual(user);
      expect(service.create).toHaveBeenCalledWith(dto);
    });
  });
});

7.5 Integration Testing

Integration tests verify how components work together (e.g., service + database). They are slower than unit tests but catch more real-world issues.

Setting Up Integration Tests

// users/users.integration.spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { TypeOrmModule } from '@nestjs/typeorm';
import { UsersService } from './users.service';
import { User } from './entities/user.entity';

describe('UsersService Integration', () => {
  let service: UsersService;
  let module: TestingModule;

  beforeAll(async () => {
    module = await Test.createTestingModule({
      imports: [
        TypeOrmModule.forRoot({
          type: 'sqlite',
          database: ':memory:',
          entities: [User],
          synchronize: true,
        }),
        TypeOrmModule.forFeature([User]),
      ],
      providers: [UsersService],
    }).compile();

    service = module.get<UsersService>(UsersService);
  });

  afterAll(async () => {
    await module.close();
  });

  beforeEach(async () => {
    // Clean database before each test
    const repository = module.get(getRepositoryToken(User));
    await repository.clear();
  });

  it('should create a user', async () => {
    const dto = { name: 'John', email: 'john@example.com' };
    const user = await service.create(dto);

    expect(user).toBeDefined();
    expect(user.name).toBe(dto.name);
    expect(user.email).toBe(dto.email);
  });

  it('should find all users', async () => {
    await service.create({ name: 'John', email: 'john@example.com' });
    await service.create({ name: 'Jane', email: 'jane@example.com' });

    const users = await service.findAll();

    expect(users).toHaveLength(2);
  });
});
Tip: Use an in-memory database (e.g., SQLite) for fast, isolated integration tests. Clean up data between tests to avoid side effects.

7.6 End-to-End (E2E) Testing

E2E tests simulate real user scenarios by making HTTP requests to your app. They test the entire stack, from HTTP layer to database.

Setting Up E2E Tests

// test/app.e2e-spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import * as request from 'supertest';
import { AppModule } from './../src/app.module';

describe('AppController (e2e)', () => {
  let app: INestApplication;

  beforeAll(async () => {
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = moduleFixture.createNestApplication();
    await app.init();
  });

  afterAll(async () => {
    await app.close();
  });

  it('/ (GET)', () => {
    return request(app.getHttpServer())
      .get('/')
      .expect(200)
      .expect('Hello World!');
  });
});

E2E Test with Authentication

// auth/auth.e2e-spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import * as request from 'supertest';
import { AppModule } from '../src/app.module';

describe('Auth (e2e)', () => {
  let app: INestApplication;
  let accessToken: string;

  beforeAll(async () => {
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = moduleFixture.createNestApplication();
    await app.init();
  });

  afterAll(async () => {
    await app.close();
  });

  describe('POST /auth/register', () => {
    it('should register a new user', () => {
      return request(app.getHttpServer())
        .post('/auth/register')
        .send({
          name: 'John Doe',
          email: 'john@example.com',
          password: 'Password123!',
        })
        .expect(201)
        .expect((res) => {
          expect(res.body).toHaveProperty('id');
          expect(res.body.email).toBe('john@example.com');
        });
    });
  });

  describe('POST /auth/login', () => {
    it('should login and return access token', async () => {
      const response = await request(app.getHttpServer())
        .post('/auth/login')
        .send({
          email: 'john@example.com',
          password: 'Password123!',
        })
        .expect(200);

      expect(response.body).toHaveProperty('access_token');
      accessToken = response.body.access_token;
    });
  });

  describe('GET /auth/profile', () => {
    it('should get user profile with valid token', () => {
      return request(app.getHttpServer())
        .get('/auth/profile')
        .set('Authorization', `Bearer ${accessToken}`)
        .expect(200)
        .expect((res) => {
          expect(res.body).toHaveProperty('email');
        });
    });

    it('should return 401 without token', () => {
      return request(app.getHttpServer())
        .get('/auth/profile')
        .expect(401);
    });
  });
});
Diagram: E2E Test Flow
Test Setup

Create App Instance

HTTP Request (supertest)

App Processes Request

Controller → Service → Repository → Database

Response

Assert Response

Cleanup

7.7 Testing Async Operations

Handle async operations properly in tests.

Testing Promises

it('should handle async operations', async () => {
  const result = await service.findAll();
  expect(result).toBeDefined();
});

// Or using resolves/rejects
it('should resolve with data', async () => {
  await expect(service.findAll()).resolves.toEqual([]);
});

it('should reject with error', async () => {
  await expect(service.findOne(999)).rejects.toThrow('Not found');
});

Testing Observables

import { firstValueFrom } from 'rxjs';

it('should handle observables', async () => {
  const result = await firstValueFrom(service.getStream());
  expect(result).toBeDefined();
});

7.8 Test Utilities

NestJS provides utilities to make testing easier.

Override Provider

const module = await Test.createTestingModule({
  providers: [UsersService, UserRepository],
})
  .overrideProvider(UserRepository)
  .useValue(mockRepository)
  .compile();

Override Guard

This is one of the most useful testing patterns in NestJS. When testing a controller, you usually do not want to deal with real authentication — you just want to test the route logic. Overriding the guard with a simple canActivate: () => true lets every request through.
const module = await Test.createTestingModule({
  controllers: [UsersController],
  providers: [UsersService],
})
  .overrideGuard(JwtAuthGuard)
  // Replace the real JWT guard with one that always allows access.
  // For testing protected routes, you can also attach a fake user:
  // canActivate: (ctx) => { ctx.switchToHttp().getRequest().user = mockUser; return true; }
  .useValue({ canActivate: () => true })
  .compile();
Practical Tip: If your controller expects request.user to be populated (because the guard normally sets it), your override guard must also set it. Otherwise, your handler will get undefined when it accesses req.user, and you will spend 20 minutes wondering why your test fails.

Override Interceptor

const module = await Test.createTestingModule({
  providers: [UsersService],
})
  .overrideInterceptor(LoggingInterceptor)
  .useValue({ intercept: () => {} })
  .compile();

7.9 Testing Edge Cases

Edge Case 1: Testing request-scoped providers Request-scoped providers create a new instance per request, but Test.createTestingModule() creates singleton instances by default. To test request-scoped behavior, you need to use module.resolve() instead of module.get()resolve() creates a new instance each time, mimicking request scope.
// module.get() returns the same instance every time (singleton behavior)
const service1 = module.get(RequestScopedService); // Instance A
const service2 = module.get(RequestScopedService); // Instance A (same)

// module.resolve() creates a new instance each time (request-scope behavior)
const service1 = await module.resolve(RequestScopedService); // Instance A
const service2 = await module.resolve(RequestScopedService); // Instance B (different)
Edge Case 2: Testing guards that depend on request.user When you override a guard in tests, the guard’s canActivate() method no longer runs — which means it no longer attaches the user to the request. If your controller reads req.user, you need your mock guard to set it:
.overrideGuard(JwtAuthGuard)
.useValue({
  canActivate: (ctx: ExecutionContext) => {
    const req = ctx.switchToHttp().getRequest();
    req.user = { id: 1, email: 'test@test.com', roles: ['admin'] };
    return true;
  },
})
Edge Case 3: E2E tests with database state leaking between tests If Test A creates a user and Test B assumes an empty database, Test B fails when run after Test A. Solutions: (1) Truncate all tables in beforeEach (fast but requires careful ordering for foreign keys); (2) Use database transactions — start a transaction in beforeEach, roll it back in afterEach (no data persists, extremely fast); (3) Use unique test data with random IDs so tests never collide. Edge Case 4: Testing interceptors that use RxJS operators Interceptors return Observables, which means testing them requires subscribing or converting to promises. Use firstValueFrom() from rxjs to convert the Observable to a promise in your test:
import { firstValueFrom, of } from 'rxjs';

it('should transform response', async () => {
  const interceptor = new TransformInterceptor();
  const mockHandler = { handle: () => of({ name: 'John' }) };
  const mockContext = {} as ExecutionContext;

  const result$ = interceptor.intercept(mockContext, mockHandler);
  const result = await firstValueFrom(result$);

  expect(result).toEqual({ success: true, data: { name: 'John' }, timestamp: expect.any(String) });
});

7.9 CI/CD Integration

Automate tests in your CI pipeline to ensure code is always tested before deployment.

GitHub Actions Workflow

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:14
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: testdb
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run unit tests
        run: npm run test

      - name: Run E2E tests
        run: npm run test:e2e
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/testdb

      - name: Generate coverage
        run: npm run test:cov

      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          files: ./coverage/lcov.info

Test Scripts

// package.json
{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch",
    "test:cov": "jest --coverage",
    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
    "test:e2e": "jest --config ./test/jest-e2e.json"
  }
}

7.10 Best Practices

Following best practices ensures your tests are maintainable and effective.

Test Organization

Structure tests by feature:
users/
├── users.service.ts
├── users.service.spec.ts
├── users.controller.ts
├── users.controller.spec.ts
└── users.integration.spec.ts

Naming Conventions

describe('UsersService', () => {
  describe('findAll', () => {
    it('should return an array of users', () => {});
    it('should return empty array when no users exist', () => {});
  });
});

Test Isolation

Each test should be independent:
beforeEach(async () => {
  // Reset mocks
  jest.clearAllMocks();
  
  // Clean database
  await repository.clear();
});

Use Descriptive Test Names

// Bad
it('works', () => {});

// Good
it('should return user when valid ID is provided', () => {});

Test Edge Cases

describe('findOne', () => {
  it('should return user for valid ID', () => {});
  it('should throw error for invalid ID', () => {});
  it('should throw error for non-existent user', () => {});
  it('should handle null ID', () => {});
});

Keep Tests Fast

  • Use mocks for unit tests
  • Use in-memory databases for integration tests
  • Run E2E tests separately
  • Use test parallelization

Coverage Goals

Aim for:
  • 80%+ coverage for business logic
  • 100% coverage for critical paths
  • Focus on quality over quantity

Clean Up Resources

afterAll(async () => {
  await app.close();
  await databaseConnection.close();
});

Best Practices Checklist

  • Write tests for all business logic
  • Use mocks for unit tests, real dependencies for integration/E2E
  • Keep tests fast and isolated
  • Use coverage reports to identify gaps
  • Run tests on every commit and pull request
  • Name tests clearly and organize by feature
  • Clean up resources after each test
  • Test edge cases and error scenarios
  • Keep test code maintainable
  • Use descriptive test names

7.11 Summary

You’ve learned how to test NestJS applications at every level: Key Concepts:
  • Unit Tests: Test individual components in isolation
  • Integration Tests: Test component interactions
  • E2E Tests: Test full user flows
  • Mocking: Isolate components for testing
  • CI/CD: Automate testing in pipelines
Best Practices:
  • Write tests for all business logic
  • Use mocks for unit tests
  • Keep tests fast and isolated
  • Test edge cases
  • Maintain high coverage
  • Clean up resources
Next Chapter: Learn about microservices architecture, message brokers, and distributed systems with NestJS.