Master NestJS Guard Testing: From Integration to E2E

Want to ensure your NestJS applications are secure and your guards are airtight? Testing is key, but often overlooked. Many articles only scratch the surface, leaving you with more questions than answers. This guide provides an in-depth look at NestJS guard testing, covering integration, unit, and end-to-end (E2E) strategies. Learn how to write robust tests and avoid falling into common testing pitfalls.

TL;DR: The Ultimate NestJS Guard Testing Strategy

Here's the breakdown for effective testing NestJS guards:

Integration Tests: Simulate real-world usage with fake endpoints in a test controller within a test-only module.
Unit Tests: Extract complex logic to isolate and test with unit tests.
E2E Tests: Verify happy paths and critical "negative" scenarios for guarded endpoints.

Feature Overview: Subscription-Based Content Access

Imagine an app called "WordWiz" that uses AI to generate marketing content. User access depends on their subscription tier:

Free Tier: Basic AI models, low word count limit.
Basic Plan: Better AI models, higher word limits.
Premium Plan: Unlimited content generation, advanced models, and integrations.

The app exposes the following endpoints, each with a subscription requirement:

POST content/generate (Free+)
GET content/templates (Basic+)
GET content/analytics (Premium+)

The SubscriptionGuard determines access based on the x-user-subscription header. Let's explore how to test this.

Understanding Test Trade-offs: The Tests CAP Theorem

Before diving into code, understand the characteristics of different test types. Vladimir Khorikov outlines four pillars of good automated tests:

Protection Against Regressions: How well tests prevent bugs.
Resistance to Refactoring: How well tests withstand internal changes.
Fast Feedback: How quickly tests execute.
Maintainability: How easy tests are to maintain.

Like the CAP theorem, you can't maximize everything. Resistance to refactoring is crucial (avoid brittle tests). You must choose between fast unit tests and high-protection E2E tests.

Integration Tests: Simulating Guard Behavior

Integration tests are a sweet spot for NestJS guard testing, providing good protection with reasonable feedback speed.

Goal: Send requests to a test endpoint requiring a subscription plan and observe the SubscriptionGuard's behavior.

// file: src/authz/subscriptions.guard.spec.ts
import { Controller, Get, INestApplication, Module, UseGuards } from '@nestjs/common';
import { SubscriptionsGuard } from './subscriptions.guard';
import { Test } from '@nestjs/testing';
import * as request from 'supertest';
import { RequiresSubscription } from './subscription.decorator';
import { Subscription } from './subscriptions';
import { SUBSCRIPTION_HEADER } from './subscription.header';

@Controller()
@UseGuards(SubscriptionsGuard)
class TestController {
  @Get('/free')
  public freeEndpoint() {
    return 'success';
  }
  @RequiresSubscription(Subscription.Basic)
  @Get('/basic')
  public basicEndpoint() {
    return 'success';
  }
  @RequiresSubscription(Subscription.Premium)
  @Get('/premium')
  public premiumEndpoint() {
    return 'success';
  }
}

@Module({
  controllers: [TestController],
  providers: [SubscriptionsGuard],
})
class TestModuleForGuard {}

describe('SubscriptionsGuard', () => {
  let testApp: INestApplication;

  beforeAll(async () => {
    const testingModule = await Test.createTestingModule({
      imports: [TestModuleForGuard],
    }).compile();
    testApp = testingModule.createNestApplication();
    await testApp.init();
  });

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

  test('A Free user can access Free endpoints', async () => {
    await request(testApp.getHttpServer())
      .get('/free')
      .expect(200)
      .expect('success');
  });

  test('A Basic user can access Free and Basic endpoints', async () => {
    await request(testApp.getHttpServer())
      .get('/free')
      .set(SUBSCRIPTION_HEADER, Subscription.Basic)
      .expect(200)
      .expect('success');
    await request(testApp.getHttpServer())
      .get('/basic')
      .set(SUBSCRIPTION_HEADER, Subscription.Basic)
      .expect(200)
      .expect('success');
  });

  test('A Basic user cannot access Premium endpoints', async () => {
    await request(testApp.getHttpServer())
      .get('/premium')
      .set(SUBSCRIPTION_HEADER, Subscription.Basic)
      .expect(403);
  });
});

Key components of this test:

TestController: Defines endpoints with varying subscription requirements.
TestModuleForGuard: Configures the testing module with the SubscriptionsGuard.
beforeAll Hook: Initializes the testing module and starts a local HTTP server.
Test Cases: Verify access based on subscription level.

The initial implementation for the SubscriptionGuard:

// file: src/authz/subscriptions.guard.ts
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Observable } from 'rxjs';
import { Subscription, SubscriptionEnum } from './subscriptions';
import { SUBSCRIPTION_KEY } from './subscription.decorator';
import { SUBSCRIPTION_HEADER } from './subscription.header';

@Injectable()
export class SubscriptionsGuard implements CanActivate {
  constructor(private readonly reflector: Reflector) {}

  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    const requiredSubscription = this.reflector.getAllAndOverride<SubscriptionEnum>(SUBSCRIPTION_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);

    if (!requiredSubscription) {
      return true; // Equivalent to the Free plan - no need for subscriptions
    }

    const userSubscription = context.switchToHttp().getRequest().headers[SUBSCRIPTION_HEADER];

    switch (requiredSubscription) {
      case Subscription.Basic: {
        return (
          userSubscription === Subscription.Basic ||
          userSubscription === Subscription.Premium
        );
      }
      case Subscription.Premium: {
        return userSubscription === Subscription.Premium;
      }
      default: {
        return false;
      }
    }
  }
}

Unit Testing with the "Humble Object" Pattern

For complex logic, extract the domain logic from the Guard and test it in isolation. This is where the Humble Object Pattern comes in handy.

// file: src/authz/subscription.spec.ts
import { subscription } from './subscriptions';

describe('Subscription', () => {
  test('A Basic subscription allows Basic features', () => {
    const result = subscription('BASIC').allows('BASIC');
    expect(result).toBe(true);
  });

  test('A Basic subscription does not allow Premium features', () => {
    const result = subscription('BASIC').allows('PREMIUM');
    expect(result).toBe(false);
  });

  test('A Premium subscription allows Basic features', () => {
    const result = subscription('PREMIUM').allows('BASIC');
    expect(result).toBe(true);
  });

  test('A Premium subscription allows Premium features', () => {
    const result = subscription('PREMIUM').allows('PREMIUM');
    expect(result).toBe(true);
  });
});

Corresponding domain logic implementation:

// file: src/authz/subscriptions.ts
export const Subscription = {
  Basic: 'BASIC',
  Premium: 'PREMIUM',
} as const;
export type SubscriptionEnum = (typeof Subscription)[keyof typeof Subscription];

export const subscription = (sub: SubscriptionEnum) => ({
  allows: (feature: SubscriptionEnum) => {
    if (sub === Subscription.Premium) {
      return true;
    }
    if (sub === Subscription.Basic && feature === Subscription.Basic) {
      return true;
    }
    return false;
  },
});

export function isSubscription(sub: string): sub is SubscriptionEnum {
  return Object.values(Subscription).includes(sub as SubscriptionEnum);
}

Now, the SubscriptionsGuard implementation is clean:

// file: src/authz/subscriptions.guard.ts
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Observable } from 'rxjs';
import { SUBSCRIPTION_KEY } from './subscription.decorator';
import { SUBSCRIPTION_HEADER } from './subscription.header';
import {
  isSubscription,
  subscription,
  SubscriptionEnum,
} from './subscriptions';

@Injectable()
export class SubscriptionsGuard implements CanActivate {
  constructor(private readonly reflector: Reflector) {}

  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    const requiredSubscription = this.reflector.getAllAndOverride<
      SubscriptionEnum | undefined
    >(SUBSCRIPTION_KEY, [context.getHandler(), context.getClass()]);

    if (!requiredSubscription) {
      return true;
    }

    const userSubscription: string = context.switchToHttp().getRequest()
      .headers[SUBSCRIPTION_HEADER];

    if (!isSubscription(userSubscription)) {
      return false;
    }

    return subscription(userSubscription).allows(requiredSubscription);
  }
}

E2E Tests: Validating Guard Behavior in Production Endpoints

Finally, test the integrated system with real endpoints:

POST content/generate (Free+)
GET content/templates (Basic+)
GET content/analytics (Premium+)

Focus on the highest subscription requirement for each endpoint.

// file: 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';
import { SUBSCRIPTION_HEADER } from '../src/authz/subscription.header';
import { Subscription } from '../src/authz/subscriptions';

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

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

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

  it('/content/generate (POST) - generates content successfully', () => {
    return request(app.getHttpServer())
      .post('/content/generate')
      .set(SUBSCRIPTION_HEADER, Subscription.Basic)
      .send()
      .expect(201);
  });

  it('/content/templates (GET) - returns a list of templates', () => {
    return request(app.getHttpServer())
      .get('/content/templates')
      .set(SUBSCRIPTION_HEADER, Subscription.Basic)
      .send()
      .expect(200);
  });

  it('/content/templates (GET) - denies request when user does not have basic plan', () => {
    return request(app.getHttpServer())
      .get('/content/templates')
      .send()
      .expect(403);
  });

  it('/content/analytics (GET) - provides engagement insights for generated content', () => {
    return request(app.getHttpServer())
      .get('/content/analytics')
      .set(SUBSCRIPTION_HEADER, Subscription.Premium)
      .send()
      .expect(200);
  });

  it('/content/analytics (GET) - denies request when user does not have premium', () => {
    return request(app.getHttpServer())
      .get('/content/analytics')
      .send()
      .expect(403);
  });
});

Level Up Your NestJS Guard Testing

By combining integration, unit, and E2E tests, you can achieve comprehensive coverage for your testing NestJS guards. Remember to consider the trade-offs between different test types. Embrace the Humble Object Pattern to isolate complex logic and write maintainable tests. With this guide, you're one step closer to building robust and secure NestJS applications.