NestJS Guards: Master Testing Strategies for Robust Authorization

Want to ensure your NestJS application's authorization is rock solid? Many NestJS testing articles only scratch the surface. This guide dives deep into effective strategies for testing NestJS Guards, showing you how to write robust, maintainable tests that prevent unwanted access. Learn how to comprehensively test your authorization logic focusing on integration tests, unit tests, and end-to-end (e2e) tests.

TL;DR: Testing NestJS Guards Like a Pro

Integration Tests First: Simulate real endpoint access using a test controller within a dedicated test module.
Isolate Logic for Unit Tests: Extract complex authorization logic into separate, testable functions.
E2E Tests for Key Scenarios: Validate happy paths and crucial "negative" scenarios for guarded endpoints.

WordWiz Example: Subscription-Based Content Generation

Imagine "WordWiz," an AI-powered content generation app. Access to features depends on the user's subscription tier: Free, Basic, or Premium.

Here's how access is structured:

Free: Limited access, basic AI.
Basic: Better AI, higher limits.
Premium: Unlimited content, advanced AI, SEO analysis.

The application exposes three key endpoints:

POST content/generate: AI content generation (Free+)
GET content/templates: Content templates (Basic+)
GET content/analytics: Engagement insights (Premium+)

We'll use a SubscriptionGuard and header x-user-subscription to enforce access based on the user's plan.

Tests CAP Theorem: Balancing Act

Good automated tests have four pillars:

Protection Against Regressions: How well tests catch bugs.
Resistance to Refactoring: Tests don't break with internal changes.
Fast Feedback: Test execution speed.
Maintainability: Ease of maintaining test code.

Like the CAP theorem, you can't maximize everything. Prioritize resistance to refactoring to avoid brittle tests. Then, choose between fast unit tests or higher protection from e2e tests.

Integration Tests: Seeing the Whole Picture for Testing Guards

Integration tests provide a good balance between protection and feedback speed.

Steps include:

Send a request to a test endpoint protected by a SubscriptionGuard.
The SubscriptionGuard either accepts or rejects the request.
The client receives the corresponding success or error response.

Let's consider the subscriptions.guard.spec.ts:

// 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 { App } from 'supertest/types';
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 & App;
    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);
    });
})

Breakdown

TestController: Defines endpoints with different subscription requirements using @RequiresSubscription() decorator. Register the guard correctly.
TestModuleForGuard: Sets up the testing module, registering the SubscriptionsGuard as a provider.
beforeAll: Initializes the testing module and starts a local HTTP server.
Test cases: Cover basic assumptions about how the SubscriptionsGuard should work by setting SUBSCRIPTION_HEADER with different subscription plans. Verify success or failure responses accordingly.

Here's a basic implementation for 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;
            }
        }
    }
}

These robust integration tests quickly validate the initial guard implementation.

Unit Testing the Subscription Logic: Humble Object Pattern

For complex logic, apply the Humble Object Pattern: extract the subscription comparison logic and test it in isolation for faster feedback.

Tests defined as follows:

// 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);
    });
});

Implementation of business logic is defined as follows:

// 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);
}

Update the guard implementation to use the new abstracted function:

// 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);
    }
}

Finally, re-run all tests to confirm stable behavior.

E2E Tests: Validating the Real Deal

E2E tests validate the entire structure, ensuring it fulfills the "WordWiz" subscription requirements. Focus on testing the highest subscription requirement for each endpoint and negative scenarios: A free user should not have access if they do not have permissions.

Create E2E tests that validate real endpoints like content/generate, content/templates, and content/analytics work as expected.

// 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);
    });
});

Key Takeaways: Solid NestJS Guard Testing

By combining integration, unit, and e2e tests, you can comprehensively validate your NestJS Guards. Start with integration tests, isolate logic for unit tests, and use e2e tests to confirm real-world behavior. This approach ensures robust authorization and a secure application.