Forem: Thiago Valentim

How to test NestJS Guards

Thiago Valentim — Wed, 23 Apr 2025 13:29:06 +0000

There are plenty of articles out there discussing different testing strategies for NestJS, and even the official documentation has a section dedicated to it, so why should you care about yet another one?

If you have spent some time reading or searching for that topic, you may have noticed a shortage of deeper discussions. Many articles only scratch the surface of unit tests; even the official docs don't go further than general guidelines. You'll also probably see too much bad advice, like mocking services and database connections everywhere (want to know why it's bad advice? Check out my previous article on How to test External Dependencies with Nest).

To remedy this lack of testing resources, I started writing a Series of Testing NestJS Articles. I'll present different strategies (and their cons and pros) for each type of construct in NestJS: Services, Guards, Interceptors, Pipes, Middlewares, etc. We'll start with Guards, as they are widely used, but their tests are often overlooked.

TL:DR

If you're just looking for a quick summary and the source code you check out this repository. The general idea is:

By default, create integration tests for your Guards simulating a fake endpoint, which should be defined in a test controller within a test-only module;
Extract business logic or algorithms to the domain layer and test it with unit tests;
Finally, create higher-level e2e tests for the happy paths and one "negative" scenario for the endpoints that should be guarded.

Example Feature and Background

Consider an application named "WordWiz", created to help users generate high-quality marketing content, blog posts, and social media captions using AI. However, the level of access depends on the user's subscription tier:

Free Tier: Limited access, basic AI models, and a low word count limit.
Basic Plan: Access to better AI models, higher word limits, and additional templates.
Premium Plan: Unlimited content generation, advanced AI models, and premium integrations (e.g., SEO analysis, API access).

That application exposes three endpoints so far, each with a different subscription plan requirement:

POST content/generate: Generates AI-powered content (Free+)
GET content/templates: Retrieves available content templates (Basic+)
GET content/analytics: Provides engagement insights for generated content

We'll use the SubscriptionGuard to determine whether a user can access content. The flow diagram below illustrates how it should be implemented:

For simplicity's sake, we won't use a JWT to store the user's subscription information (which would be ideal), but a straightforward x-user-subscription header. Finally, we have all we need to start writing the tests.

Tests CAP Theorem

Before discussing implementation details, I'd like to quickly describe the characteristics of each type of test and when we should use them.

According to Vladimir Khorikov, there are four pillars of good automated tests:

Protection Against Regressions - How much do your tests protect you against bugs?
Resistance to Refactoring - How well can your tests resist internal refactors without breaking?
Fast Feedback - How fast does your test execute?
Maintainability - How easy is maintaining the test code?

Each type of test - unit, integration, and e2e - scores higher or lower in each of the pillars above. However, we can't have all of them at the same time - very much like the CAP theorem, but for tests:

The Resistance to Refactoring should always be maxed out, as we don't want brittle tests. However, we must choose between tests that run fast enough (unit) or tests that provide higher protection (e2e). We'll cover each type in the following sections with examples and further explanations.

Integration Test

Starting with integration tests is good because:

We can see the test's entire data and decision flow.
We have a good trade-off between protection and feedback speed.

The SubscriptionGuard observable behavior must be tested for all intended cases (not just the endpoints I mentioned in the last section). Hence, I start by creating a testing module, a test controller, and a test application so we can emulate the following workflow:

A request is sent to a test endpoint that requires a subscription plan
The SubscriptionGuard accepts or denies the request
The client receives an error or success response

Let's see how that works - defining a subscriptions.guard.spec.ts file:

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

A lot is going on in this test case, so let's break it down:

TestController - This is the controller that showcases how the Guard is supposed to be registered, how we can define an endpoint's subscription prerequisite (the @RequiresSubscription() decorator), and three endpoints exemplifying the different requirements.
TestModuleForGuard - The testing module that defines how we should define the SubscriptionsGuard as a provider, and the one used to start a testingModule.
beforeAll hook - We initialize the testing module and start a local HTTP server with the testing endpoints registered.
Free, Basic, and Premium plan test cases — These three cover the basic assumptions of how our SubscriptionsGuard should work. Within each test case, you can see we either set the SUBSCRIPTION_HEADER (which is just an alias for x-user-subscription) or don't send a header at all. Depending on the endpoint requirements, we have a success or failure response.

These tests don't cover all possible scenarios, but they are enough for now to illustrate an initial implementation for our Guard:

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

With that implemented, we already have all of our tests passing:

PASS src/authz/subscriptions.guard.spec.ts

From this point, you can also include the remaining test cases, which can be consulted here.

The steps above should suffice for a basic guard implementation that doesn't require much testing / don't have a complex enough logic. But can we go further? Let's find out in the next section.

Unit Testing the Subscriptions Logic - Or the "Humble Object" Pattern

Although the integration test cases above cover most cases in which we could be interested, it's worth exploring how we can further extract the domain logic from the Guard and test it in isolation, granting faster feedback. This is especially useful when, for some reason, our Guards are harder to test, and that's when the Humble Object Pattern comes into play.

In our scenario, we can apply that pattern by extracting the subscription comparison logic to its own file and testing it 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); 
  });
});

And the corresponding 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);
}

ℹ️Note: The types of subscriptions are encoded in an object instead of an enum because Enums might be considered harmful

Now, the SubscriptionsGuard implementation can be simplified by importing our new subscription 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);
  }
}

At last, we can execute all tests to ensure our behavior stays the same:

 $ npm run test
 PASS  src/authz/subscription.spec.ts
 PASS  src/authz/subscriptions.guard.spec.ts

In the next (and last) section, we'll analyze how to test our guard using actual "production" endpoints as we specified in the "Requirements" section.

When the Rubber hits the road with E2E Tests

This entire structure was designed to fulfill our "WordWiz" example app subscription requirements. So, let's recall what endpoints we have to implement:

POST content/generate: Generates AI-powered content (Free+)
GET content/templates: Retrieves available content templates (Basic+)
GET content/analytics: Provides engagement insights for generated content

We can describe the expected behavior examples as follows:

POST content/generate:
1. A Free user has access
2. A Basic plan user has access
3. A Premium plan user has access
GET content/templates:
1. A Free user does not have access
2. A Basic plan user has access
3. A Premium plan user has access
GET content/analytics:
1. A Free user does not have access
2. A Basic plan user does not have access
3. A Premium plan user has access

We already have unit tests that guarantee higher subscription requirements (like Premium+) deny access to the lower subscription plans. So, we can 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 plan', () => {
    return request(app.getHttpServer())
      .get('/content/analytics')
      .set(SUBSCRIPTION_HEADER, Subscription.Basic)
      .send()
      .expect(403);
  });
});

Notice we are not asserting the response body as it's not really important for our use case (but you can check out how it could be tested here). Finally, we can specify the actual controller implementation:

// file: src/content/content.controller.ts
import { Controller, Get, Post, UseGuards } from '@nestjs/common';
import { RequiresSubscription } from '../authz/subscription.decorator';
import { SubscriptionsGuard } from '../authz/subscriptions.guard';

@Controller('content')
@UseGuards(SubscriptionsGuard)
export class ContentController {
  @Post('generate')
  generateContent() {
    return {
      content: 'Generated content goes here',
    };
  }

  @RequiresSubscription('BASIC')
  @Get('templates')
  getTemplates() {
    return [
      {
        id: '1',
        name: 'Template 1',
        description: 'Description of Template 1',
      },
    ];
  }

  @RequiresSubscription('PREMIUM')
  @Get('analytics')
  getAnalytics() {
    return {
      generatedArticles: 25,
      averageEngagementRate: 0.74,
      topPerformingArticles: [
        {
          title: 'How to Boost Your SEO with AI',
          views: 1200,
          shares: 340,
          likes: 250,
        },
      ],
      suggestedImprovements: [
        'Use more questions in headlines to increase engagement.',
      ],
    };
  }
}

Conclusion

In this article, we went beyond the basics of testing in NestJS by diving deep into how to effectively test Guards. We discussed:

Why integration tests are a great starting point.
How to simulate real-world scenarios using a test controller.
How to apply the Humble Object pattern to extract domain logic.
How to implement e2e tests for endpoints using guards.
How to balance protection, speed, and maintainability using the Tests CAP Theorem.

The result is a more robust, maintainable, and clear testing strategy for Guards — one that avoids over-mocking and keeps your codebase reliable.

But this is just the beginning. This article is part of a broader series on testing NestJS applications, where I’ll explore how to apply similar principles to services, interceptors, pipes, middlewares, and beyond. Stay tuned for more practical guides and real-world examples that will help you master testing in NestJS. See you in the next one 👋.

Leveraging Mock Service Workers for NestJS e2e tests

Thiago Valentim — Tue, 04 Mar 2025 12:59:50 +0000

In the previous article, we discussed how almost any modern web application has to communicate with external systems. It's also safe to assume most of that communication is made via HTTP calls. In today's post, we'll learn how to:

Intercept and stub HTTP calls in NodeJS using Mock Service Workers and NestJS as the framework - No interfaces are needed this time.
Create reusable API stubs for any e2e test.
Simulate network errors.

Bonus:

How to transform the external data structure into domain objects using an anti-corruption layer (ACL).
Leveraging a Result class to separate application and network layer error handling.

As always, you can check out the reference repository for more details on the implementation.

ℹ️ TL:DR -> We utilize MSW to intercept NodeJS's internal request calls using the setupServer() function and a server.use() call for each test. You can check out the final code below:

import { INestApplication } from '@nestjs/common';
import { Test, TestingModule } from '@nestjs/testing';
import { http, HttpResponse, passthrough } from 'msw';
import { setupServer, SetupServerApi } from 'msw/node';
import * as request from 'supertest';
import { stubGoogleAPIResponse } from '../src/address/application/test/google-geocode-mock.handler';
import { AppModule } from '../src/app.module';

describe('Get GeoCode Address', () => {
  let app: INestApplication;
  let mockServer: SetupServerApi;

  beforeAll(() => {
    // We must define a passthrough for localhost requests so MSW doesn't log a warning.
    mockServer = setupServer(http.all('http://127.0.0.1*', passthrough));
    mockServer.listen();
  });

  afterAll(() => {
    mockServer.close();
  });

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

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

  it('returns the coordinates for a valid address', () => {
    mockServer.use(
      stubGoogleAPIResponse({
        results: [
          {
            geometry: {
              location: {
                lat: 37.4224082,
                lng: -122.0856086,
              },
            },
          },
        ],
        status: 'OK',
      }),
    );

    return request(app.getHttpServer())
      .get(
        '/addresses/geo-code?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA',
      )
      .expect({
        latitude: 37.4224082,
        longitude: -122.0856086,
      });
  });

  it('returns a 404 error when the address is not found', async () => {
    mockServer.use(
      stubGoogleAPIResponse({
        results: [],
        status: 'ZERO_RESULTS',
      }),
    );

    return request(app.getHttpServer())
      .get('/addresses/geo-code?address=invalid+address')
      .expect(404)
      .expect({
        statusCode: 404,
        message: 'Address not found',
      });
  });
  it('returns a 424 error (code=01) when the API key is invalid', async () => {
    mockServer.use(
      stubGoogleAPIResponse({
        results: [],
        status: 'REQUEST_DENIED',
        error_message: 'The provided API key is invalid.',
      }),
    );

    return request(app.getHttpServer())
      .get('/addresses/geo-code?address=invalid+address')
      .expect(424)
      .expect({
        statusCode: 424,
        message: 'Failed to get coordinates',
        code: '01',
      });
  });
  it('returns a 424 error (code=02) when there is a network error', async () => {
    mockServer.use(stubGoogleAPIResponse(HttpResponse.error()));

    return request(app.getHttpServer())
      .get('/addresses/geo-code?address=invalid+address')
      .expect(424)
      .expect({
        statusCode: 424,
        message: 'Failed to get coordinates',
        code: '02',
      });
  });
});

If you are interested in the process to get there, including the example use case, proceed with me to the following sections.

Feature

Let's consider a simple (but real-world-like) application to demonstrate MSW usage. That app returns the latitude and longitude of a given address the user inputs:

The user types a location in the search bar
The user clicks the button to "Get Coordinates"
The location's coordinates are shown along with the location.

The gherkin description below details each use case:

Feature: As a user I want to be able to see an address' cooridnates on the map.

  A user can enter an address to view their location on the map. The system
  returns either the coordinates of that address or an error when not found.

  Scenario: Successfully retrieve address coordinates
    Given the address '1600 Amphitheatre Parkway, Mountain View, CA' is valid with coordinates 37.4224082, -122.0856086
    When I search for that location's address
    Then I can see the address'coordinates

  Scenario: Handle non-existent address
    Given the address 'Invalid Address' is invalid
    When I search that location's address
    Then I receive an error message: 'Address not found'

  Scenario: Handle network error during coordinate retrieval
    Given a network error occurs
    When I search for the address 'Some Address'
    Then I see the error message: 'Failed to get coordinates'

We'll also use Google's Geocoding API to retrieve a location's coordinates. We just need to send a GET request to the API endpoint, passing the address string and the API key:

ADDRESS="Germany"
API_KEY="MY-APY-KEY" 

curl -X GET "https://maps.googleapis.com/maps/api/geocode/json?address=${ADDRESS}&key=${API_KEY}"

You'll need a Google Services API Key to fetch the real data, but fortunately, we don't even need to work with the API for our tests. We just need to know what its response looks like:

{
  "results": [
    {
      "address_components": [
        {
          "long_name": "Germany",
          "short_name": "DE",
          "types": [
            "country",
            "political"
          ]
        }
      ],
      "formatted_address": "Germany",
      "geometry": {
        "bounds": {
          "south": 47.270114,
          "west": 5.8663425,
          "north": 55.0815,
          "east": 15.0418962
        },
        "location": {
          "lat": 51.165691,
          "lng": 10.451526
        },
        "location_type": "APPROXIMATE",
        "viewport": {
          "south": 47.270114,
          "west": 5.8663425,
          "north": 55.0815,
          "east": 15.0418962
        }
      },
      "place_id": "ChIJa76xwh5ymkcRW-WRjmtd6HU",
      "types": [
        "country",
        "political"
      ]
    }
  ],
 "status": "OK"
}

ℹ️ Note: We'll consider the Geocode API always returns a single result for simplicity.

So, the data that really matters to us can be obtained from response.results[0].geometry.location. Let's keep that in mind when we start implementing the service. For now, let's note down a simplified type of that response:

export type GoogleGeocodeResponse = {
  results: {
    geometry: {
      location: {
        lat: number;
        lng: number;
      };
    };
  }[];
  status: string;
  error_message?: string; // This property exists when an error occurs.
};

The error_message property determines when an application error occurs —yes, they send a 200 status even when there is an error.

Now that we have everything we need to start writing the test cases, let's proceed to the next section.

Defining the e2e test cases

The first step is to write the test scenario descriptions with the .todo() suffix as we won't implement them just yet:

import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import * as request from 'supertest';
import { AppModule } from '../src/app.module';
import { http, HttpResponse } from 'msw';
import { setupServer, SetupServerApi } from 'msw/node';

describe('Get GeoCode Address', () => {
  let app: INestApplication;

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

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

  it.todo('returns the coordinates for a valid address');
  it.todo('returns a 404 error for an invalid address');
  it.todo('returns a 424 (code=01) error when the API key is invalid');  // Extra test for a technical edge case
  it.todo('returns a 424 (code=02) error when there is a network error');
});

Notice that we have an extra test case above: returns a 424 (code=01) error when the API key is invalid. This is an unlikely scenario, but it was put there for a good reason - to simulate how we should handle unexpected errors.

If the API Key is invalid (or has expired), we want to associate a specific error code with it so the client side can report that via an automated channel. Moreover, we don't want to let the user know the underlying reason for failure, so the error message doesn't say anything about the API Key.

Writing the success test case

Let's start with the success scenario test case:

 it('returns the latitude/longitude for a valid address', () => {
    // How do we stub the geo-code API response? 🤔
    const expectedCoordinates = {
      latitude: 37.4224082,
      longitude: -122.0856086,
    }
    return request(app.getHttpServer())
      .get(
        '/addresses/geo-code?address=Germany',
      )
      .expect(200)
      .expect(expectedCoordinates);
  });

The test is straightforward. We send a request to the GET /addresses/geocode endpoint and expect to get Germany's coordinates as a response. But since we won't connect to the real API, we must stub this response with MSW. To implement this, we must use MSW's NodeJS integration.

ℹ️ Note: MSW default mode works in the browser with Service Workers, so we need a slightly different route to make it work with NodeJS

import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import * as request from 'supertest';
import { AppModule } from '../src/app.module';
import { http, HttpResponse } from 'msw';
import { setupServer, SetupServerApi } from 'msw/node';

describe('Get GeoCode Address', () => {
  let app: INestApplication;
  let mockServer: SetupServerApi;

  const handlers = [
    // Intercept "GET 'https://maps.googleapis.com/maps/api/geocode" requests...
    http.get(
      'https://maps.googleapis.com/maps/api/geocode/json',
      () => {
        // ...and respond to them using this JSON response.
        return HttpResponse.json(
          {
            results: [
              {
                geometry: {
                  location: {
                    lat: 37.4224082,
                    lng: -122.0856086,
                  },
                },
              },
            ],
            status: 'OK'
          },
        );
      },
    ),
  ];

  beforeAll(() => {
    mockServer = setupServer(...handlers);
    mockServer.listen();
  });

  afterAll(() => {
    mockServer.close();
  });

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

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

  it('returns the coordinates for a valid address', () => {
    const expectedCoordinates = {
      latitude: 37.4224082,
      longitude: -122.0856086,
    }
    return request(app.getHttpServer())
      .get(
        '/addresses/geo-code?address=Germany',
      )
      .expect(200)
      .expect(expectedCoordinates);
  });
});

The key steps to setup MSW above are:

Define the request handler array containing the handler that should respond to HTTP calls made to the geocode API
Setup the server with the list of handlers.
Make the server start listening
Ensure we close it in the afterAll block

Now, we must implement the controller and the service that should handle this request. We'll communicate with our Geocode API using NestJS HttpModule.

Implementing the first version of Controller and Service

We can use NestJS CLI to create an 'AddressModule', an 'AddressController', and an 'AddressService' to scaffold their basic structure:

nest g module address
nest g controller address
nest g service address

Then, implement the communication with the GeoCode API at the service layer:

import { Injectable } from '@nestjs/common';
import { Coordinates } from '../domain/coordinates';
import { HttpService } from '@nestjs/axios';
import { firstValueFrom } from 'rxjs';

export type GoogleGeocodeResponse = {
  results: {
    geometry: {
      location: {
        lat: number;
        lng: number;
      };
    };
  }[];
};

@Injectable()
export class AddressService {
  constructor(private readonly httpService: HttpService) {}

  async getGeoCode(address: string): Promise<Coordinates> {
    const response = await firstValueFrom(
      this.httpService.get<GoogleGeocodeResponse>(
        `https://maps.googleapis.com/maps/api/geocode/json?key=test&address=${address}`,
      ),
    );

    const { lat, lng } = response.data.results[0].geometry.location;

    return new Coordinates(lat, lng);
  }
}

Note that we're returning a domain object from that service: Coordinates. It represents a coordinate Value Object and should be responsible for validating itself. This centralizes the logic that defines what is a valid coordinate, making it reusable and safe to be used by other services:

export class Coordinates {
  public readonly latitude: number;
  public readonly longitude: number;

  constructor(lat: number, lng: number) {
    if (!Coordinates.isValid(lat, lng)) {
      throw new Error(`Invalid coordinates: lat=${lat}, lng=${lng}`);
    }

    this.latitude = lat;
    this.longitude = lng;
  }

  static isValid(lat: number, lng: number): boolean {
    return (
      typeof lat === 'number' &&
      typeof lng === 'number' &&
      lat >= -90 &&
      lat <= 90 &&
      lng >= -180 &&
      lng <= 180
    );
  }
}

Now we must inject this AddressService into our AddressController:

import { Controller, Get, Query } from '@nestjs/common';
import { Coordinates } from './domain/coordinates';
import { AddressService } from './application/address.service';

@Controller('addresses')
export class AddressController {
  constructor(private readonly addressService: AddressService) {}

  @Get('geo-code')
  async getGeoCode(@Query('address') address: string): Promise<Coordinates> {
    return this.addressService.getGeoCode(address);
  }
}

Lastly, let's update the AddressModule to import NestJS's HttpModule to provide the HttpService:

import { Module } from '@nestjs/common';
import { AddressController } from './address.controller';
import { AddressService } from './application/address.service';
import { HttpModule } from '@nestjs/axios';

@Module({
  imports: [HttpModule],
  controllers: [AddressController],
  providers: [AddressService],
})
export class AddressModule {}

With all the pieces fitted, we can run the test case:

$ pnpm run test:e2e
 PASS  test/get-address-coordinates.e2e-spec.ts

And then the first cycle is completed! Well, almost. If you execute the test command above, you'll also notice it logs a warning:

[MSW] Warning: intercepted a request without a matching request handler:

        • GET http://127.0.0.1:36245/addresses/geo-code?address=Germany

So, how do we get rid of it?

Fixing MSW "intercepted request without a matching request handler" warning

The WARN happened because MSW detected we sent a request to a local server (hence the 127.0.0.1 IP address) but didn't register any handler. To solve this, we must define a passthrough handler because we don't want to change or stub responses from our own server:

  const handlers = [
    http.get('https://maps.googleapis.com/maps/api/geocode/json', () => HttpResponse.json(geocodeResponse),
    http.get('http://127.0.0.1*', passthrough),
  ];

The message is gone now when running the e2e test cases:

 PASS  test/app.e2e-spec.ts
 PASS  test/get-address-coordinates.e2e-spec.ts

Test Suites: 2 passed, 2 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        4.713 s, estimated 5 s
Ran all test suites.
------------------------

Refactoring MSW response stubs to allow response per test case

Before implementing the subsequent test cases, which should handle error scenarios, we must refactor the existing code slightly because they are globally defined. That means any request to the maps/api/geocode/json endpoint produces the same success response.

Each test case sends a request to MSW Server but gets the same response.

The alternative that allows us to define per-use-case response is MSW's use method. This method dynamically attaches request handlers to MSW's server, which can later be removed by calling resetHandlers(). Therefore, we'll implement three main changes to our test code:

Remove the specific request handlers from the server setup.
Add test-case-specific request handlers with mockServer.use()
Extract the code that creates a request handler to a file next to the AddressSevice so we encapsulate its details.

import { INestApplication } from '@nestjs/common';
import { Test, TestingModule } from '@nestjs/testing';
import { http, passthrough } from 'msw';
import { setupServer, SetupServerApi } from 'msw/node';
import * as request from 'supertest';
import { stubGoogleAPIResponse } from '../src/address/application/test/google-geocode-mock.handler';
import { AppModule } from '../src/app.module';

describe('Get GeoCode Address', () => {
  let app: INestApplication;
  let mockServer: SetupServerApi;

  beforeAll(() => {
    // We must define a passthrough for localhost requests so MSW doesn't log a warning.
    mockServer = setupServer(http.all('http://127.0.0.1*', passthrough));
    mockServer.listen();
  });

  afterAll(() => {
    mockServer.close();
  });

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

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

  it('returns the coordinates for a valid address', () => {
    mockServer.use(
      stubGoogleAPIResponse({
        results: [
          {
            geometry: {
              location: {
                lat: 37.4224082,
                lng: -122.0856086,
              },
            },
          },
        ],
        status: 'OK',
      }),
    );

    return request(app.getHttpServer())
      .get('/addresses/geo-code?address=Germany')
      .expect({
        latitude: 37.4224082,
        longitude: -122.0856086,
      });
  });
});

And this is the stubGoogleAPIResponse() implementation code:

import { http, HttpResponse } from 'msw';
import { GoogleGeocodeResponse } from '../address.service';

export function stubGoogleAPIResponse(
  response: GoogleGeocodeResponse | Response,
) {
  return http.get(
    'https://maps.googleapis.com/maps/api/geocode/json',
    () =>
      response instanceof Response ? response : HttpResponse.json(response),
    {
      // Ensure this stubbed response is only used once.
      once: true,
    },
  );
}

ℹ️ Note: The stub accepts an instance of Response as a possible input to simulate errors.

And that's all we needed to refactor at this point. In the next section we'll implement the error cases.

Implementing the error cases

There are three error cases we have to simulate now:

Address not found. Response: { results: [], status: 'ZERO_RESULTS' }
The API Key is invalid. Response: { results: [], status: 'REQUEST_DENIED' }
There is a network error. In this case, the request is aborted and we don't receive a response from the server.

Let's write down each of these error cases:

 it('returns a 404 error when the address is not found', async () => {
    mockServer.use(
      stubGoogleAPIResponse({
        results: [],
        status: 'ZERO_RESULTS',
      }),
    );

    return request(app.getHttpServer())
      .get('/addresses/geo-code?address=invalid+address')
      .expect(404)
      .expect({
        statusCode: 404,
        message: 'Address not found',
      });
  });
 it('returns a 424 error (code=01) when the API key is invalid', async () => {
    mockServer.use(
      stubGoogleAPIResponse({
        results: [],
        status: 'REQUEST_DENIED',
        error_message: 'The provided API key is invalid.',
      }),
    );

    return request(app.getHttpServer())
      .get('/addresses/geo-code?address=invalid+address')
      .expect(424)
      .expect({
        statusCode: 424,
        message: 'Failed to get coordinates',
        code: '01',
      });
  });
  it('returns a 424 error (code=02) when there is a network error', async () => {
    mockServer.use(stubGoogleAPIResponse(HttpResponse.error()));

    return request(app.getHttpServer())
      .get('/addresses/geo-code?address=invalid+address')
      .expect(424)
      .expect({
        statusCode: 424,
        message: 'Failed to get coordinates',
        code: '02',
      });
  });

The first two test cases are similar - they only need to specify the JSON response. The third test, however, has to respond with HttpResponse.error() to simulate a network error.

ℹ️ Note: You can also easily simulate responses with error status by passing a second argument to the HttpResponse.json() method in the stub handler. For instance: HttpResponse.json(response, { status: 404 })

Handling errors at the service and controller layer.

The last piece of the puzzle is handling each of these errors. To do so, we'll separate error handling into two layers:

Application Layer - The service takes the API response and verifies whether this is a success or an error result. Then, it returns that result to the layer above instead of throwing an error. We use the Result class for that purpose.
Network Layer - The controller takes the response from the service and decides how to response to each type of error - formatting the messages accordingly and specifying the response status.

The diagram below depicts the error-handling flow:

So let's start with the Service. We'll define a constant to hold all known error messages that Google's API responds so we can map them to specific Error classes:

export const GeoLocationErrorCode = {
  AddressNotFound: 'ADDRESS_NOT_FOUND',
  InvalidAPIKey: 'INVALID_API_KEY',
  UnknownException: 'UNKNOWN',
  NetworkException: 'NETWORK',
  InvalidRequest: 'INVALID_REQUEST',
} as const;

export class AddressNotFoundError extends ApplicationError {
  constructor() {
    super('Address not found', GeoLocationErrorCode.AddressNotFound);
  }
}

export class InvalidAPIKeyError extends ApplicationError {
  constructor() {
    super('Failed to get coordinates', GeoLocationErrorCode.InvalidAPIKey);
  }
}

export class GeoLocationNetworkError extends ApplicationError {
  constructor() {
    super('Failed to get coordinates', GeoLocationErrorCode.NetworkException);
  }
}

export class InvalidInputError extends ApplicationError {
  constructor() {
    super('Invalid input', GeoLocationErrorCode.InvalidRequest);
  }
}

export class UnknownGeolocationError extends ApplicationError {
  constructor() {
    super('Unknown error', GeoLocationErrorCode.UnknownException);
  }
}

Then, we'll capture each possible error and map it to our application-level errors:

@Injectable()
export class AddressService {
  private readonly logger = new Logger(AddressService.name);
  constructor(private readonly httpService: HttpService) {}

  async getGeoCode(
    address: string,
  ): Promise<Result<Coordinates, ApplicationError | AxiosError>> {
    const response = await firstValueFrom(
      this.httpService
        .get<GoogleGeocodeResponse>(
          `https://maps.googleapis.com/maps/api/geocode/json?key=test&address=${address}`,
        )
        .pipe(
          catchError((error: AxiosError) => {
            if (error.response) {
              return of(error);
            }

            if (error.request) {
              return of(new GeoLocationNetworkError());
            }

            return of(new UnknownGeolocationError());
          }),
        ),
    );

    if (response instanceof Error) {
      return Result.fail(response);
    }

    const data = response.data;

    if (data.status !== 'OK') {
      this.logger.error(`Failed to get coordinates: ${data.error_message}`);
      switch (data.status) {
        case 'ZERO_RESULTS':
          return Result.fail(new AddressNotFoundError());
        case 'REQUEST_DENIED':
          return Result.fail(new InvalidAPIKeyError());
        case 'INVALID_REQUEST':
          return Result.fail(new InvalidInputError());
        default:
          return Result.fail(new UnknownGeolocationError());
      }
    }

    const { lat, lng } = data.results[0].geometry.location;

    return Result.ok(new Coordinates(lat, lng));
  }
}

ℹ️ Note: You can check out the implementation details of the Result class in the repository code.

Finally, the AddressController decides how to map each type of error to a specific network exception:

import {
  Controller,
  Get,
  HttpException,
  NotFoundException,
  Query,
} from '@nestjs/common';
import { Coordinates } from './domain/coordinates';
import {
  AddressService,
  GeoLocationErrorCode,
} from './application/address.service';

@Controller('addresses')
export class AddressController {
  constructor(private readonly addressService: AddressService) {}

  @Get('geo-code')
  async getGeoCode(@Query('address') address: string): Promise<Coordinates> {
    const result = await this.addressService.getGeoCode(address);

    if (result.isOk()) {
      return result.value;
    }

    switch (result.error.code) {
      case GeoLocationErrorCode.AddressNotFound:
        throw new NotFoundException('Address not found', {
          cause: result.error,
        });
      case GeoLocationErrorCode.InvalidAPIKey:
        throw new HttpException(
          {
            statusCode: 424,
            message: 'Failed to get coordinates',
            code: '01',
          },
          424,
          {
            cause: result.error,
          },
        );
      case GeoLocationErrorCode.NetworkException:
        throw new HttpException(
          {
            statusCode: 424,
            message: 'Failed to get coordinates',
            code: '02',
          },
          424,
          {
            cause: result.error,
          },
        );
      case GeoLocationErrorCode.InvalidRequest:
        throw new HttpException(
          {
            statusCode: 424,
            message: 'Failed to get coordinates',
            code: '03',
          },
          424,
          {
            cause: result.error,
          },
        );
      default:
        throw result.error;
    }
  }
}

This finalizes our last cycle. Each error scenario is handled by the AddressService, turned into a Result object, and mapped to an HttpException at the AddressController. Running our e2e tests is the final litmus test that everythingworks as intended:

$ pnpm run test:e2e
 PASS  test/get-address-coordinates.e2e-spec.ts

Test Suites: 2 passed, 2 total
Tests:       6 passed, 6 total
Snapshots:   0 total
Time:        5.061 s
Ran all test suites.

Review and Conclusion

How to test external dependencies with Nest

Thiago Valentim — Mon, 10 Feb 2025 13:11:47 +0000

Almost every back-end application has to communicate with external dependencies at some point. In this post, we'll learn how to properly test them using NestJS - and no, it's not simply "mocking out" stuff. Here's what we'll cover:

Types of dependencies: Managed VS Unmanaged;
Types of Test Doubles;
When to use Mocks and when to replace them with Spies;
When to use Stubs;

And as always, you can check out the final code at the public repository. Good reading!

Types of Dependencies

Vladimir Khorikov, in his exceptional book "Unit Testing: Principles, Practices and Patterns", categorizes dependencies (broadly) into two types:

Managed Dependencies— Out-of-process dependencies our application has full control and are only visible to the external world through our system. Example: Database.
Unmanaged Dependencies - Out-of-process dependencies that we don't exert full control over their state and are visible to the external world. Example: SMTP Server.

Put an image here illustrating these two types of dependencies

While managed dependencies shouldn't be mocked during tests to preserve the application's behavior, unmanaged dependencies have to be replaced with test doubles. For instance, when part of a use case flow consists of sending an email to a user, we don't want to send an actual email — and potentially fill up some spam inboxes.

So, what do we do instead? Let's start with an example of an authentication flow.

The Feature

Suppose we're tasked to implement a signup endpoint - one of the very first steps when building a new application. The requirement is described using Gherkin for the sake of explicitness:

Feature: Sign up
  Scenario: A user signs up successfully
    When a user signs up with email "new-user@mail.com" and password "password"
    Then they are authenticated
    And they should receive an email with subject "Welcome".
  Scenario: A user sign up fails due to leaked password
    Given the password "weak" has leaked in a rainbow table
    When a user tries to sign up with the email "new-user@mail.com" and password "weak"
    Then they receive an error message: "Your password has leaked in a data breach. Please choose a different one."

Just by looking at the requirements, we can foresee we'll need an EmailService to send that confirmation email and a PasswordService that verifies whether the given password has leaked in a rainbow table (Consider we have an external API available that returns that information). Here's a chart illustrating how that flow should look like:

With that context in mind, let's move forward to the implementation.

Creating the test cases

A helpful tip when developing a new feature is to start by defining the acceptance test descriptions in our code (we already did the high-level one with the Gherkin syntax). Let's use the base end-to-end Nest example and write down the specifications:

describe('SignUp user (e2e)', () => {
  let testingApp: INestApplication<App>;

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

    testingApp = testingModule.createNestApplication();
    await testingApp.init();
  });

  test.todo('creates a new user and sends a confirmation email');
  test.todo('returns an error when password hash is in a rainbow table')
});

Now that we have both cases noted, we can pick the easiest one to define and implement. Let's do so and start with the success case:

  test('create a new user and sends a confirmation email', async () => {
    const server = testingApp.getHttpServer();
    const response = await request(server).post('/auth/signup').send({
      email: 'new-user@mail.com',
      password: 'password',
    });

    const jwtRegex = /^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+$/;
    expect(response.body).toHaveProperty(
      'accessToken',
      expect.stringMatching(jwtRegex),
    );
    // How do we test that the email was sent?
  });

At this point, we can implement the simplest possible controller to make the test pass:

import { Controller, Post } from '@nestjs/common';

@Controller('auth')
export class AuthController {
  @Post('signup')
  signup() {
    return {
      accessToken: 'a.jwt.token',
    };
  }
}

The test is pretty simple. We expect the endpoint to accept an email and a password in the body and return a jwt in the response. We don't have to verify the jwt's validity now, so we just check the expected syntax ({alpha}.{alpha}.{alpha}). Then, the open question is how to verify that the email was sent. Well, mocks are designed precisely to do that.

Using mocks to verify the external dependency

So, let's define what we expect the EmailService to look like and utilize jest's "spyOn()" method to create a spy that can observe and modify the service's behavior:

// file: src/email/email.service.ts
import { Injectable } from '@nestjs/common';

export type SendEmailInput = {
  to: string;
  subject: string;
  content: string;
};

@Injectable()
export class EmailService {
  public sendEmail(input: SendEmailInput) {
    console.log('Sending email to %s with subject %s', input.email, input.subject);
  }
}

And the updated test file:

 test('create a new user and sends a confirmation email', async () => {
    // Arrange
    const server = testingApp.getHttpServer();
    const emailService = testingApp.get(EmailService);
    const spy = jest
      .spyOn(emailService, 'sendEmail')
      .mockImplementationOnce(() => {}) // We don't need any real implementation
      .mockName('mockedSendEmail'); // this is used to display a custom function name instead of `jest.fn()` if this test fails.

    // Act
    const response = await request(server).post('/auth/signup').send({
      email: 'new-user@mail.com',
      password: 'password',
    });

    // Assert
    const jwtRegex = /^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+$/;
    expect(response.body).toHaveProperty(
      'accessToken',
      expect.stringMatching(jwtRegex),
    );
    expect(spy).toHaveBeenCalledTimes(1);
    expect(spy).toHaveBeenCalledWith({
      to: 'new-user@mail.com',
      subject: 'Welcome!',
      content: 'Welcome to our app!',
    });
  });

Executing this test will fail because the EmailService isn't used in our dummy authentication controller. Let's fix this:

import { Body, Controller, Post } from '@nestjs/common';
import { EmailService } from '../email/email.service';

@Controller('auth')
export class AuthController {
  constructor(private readonly emailService: EmailService) {}

  @Post('signup')
  signup(@Body() input: { email: string; password: string }) {
    this.emailService.sendEmail({
      to: input.email,
      subject: 'Welcome!',
      content: 'Welcome to our app!',
    });
    return {
      accessToken: 'a.jwt.token',
    };
  }
}

ℹ️ Note
We haven't defined a type for our body nor its validation because it's out of the scope of this article.

Finally, our test case is green now. We asserted that an email is sent to the user by verifying the EmailService.sendEmail() method. All good, right? Well, not so much. Let's think of a few drawbacks of that approach:

To spy on sendEmail(), we must know its exact name beforehand: jest.spyOn(emailService, 'sendEmail'). ' If we change that method's name or signature, our tests must also change.
Whenever we need to mock that EmailService on other test files for different use cases, we must repeat the code to spy on that same method again. If we have to change that method's name or signature as before, the amount of work is multiplied by the number of places using it.
We must know the exact parameter names and schema in the assertion step: expect(spy).toHaveBeenCalledWith({ to: 'to,' subject: 'subject,' content: '...content...' }) If that signature ever changes, all places using it break too.

In summary, using mocks by default might be helpful in the short term. Still, they increase the likelihood of breaking our test code — and a very relevant metric for good automated tests is their maintainability. We don't want the headache of changing a bunch of test files just because our code's internal structure has also changed. So, what's the alternative?

Spy, Don't Mock

A Spy is basically a handwritten mock. They serve the same purpose, replacing an outgoing interaction between our system and the external world, but creating a spy gives us more control over its interface and behavior while also fostering reusability. But just before creating our spy, we must create an interface that defines the observable (and "mockable") behavior of that EmailService:

export type SendEmailInput = {
  to: string;
  subject: string;
  content: string;
};

export abstract class IEmailService {
  abstract sendEmail(input: SendEmailInput): void;
}

ℹ️ Note
We define the "interface" above as an abstract class because we can use an abstract class as an injection token in NestJS and also use the implements keyword - If we used an interface instead, we would have to create a symbol to represent that dependency, something like const EMAIL_SERVICE = Symbol.for('EmailService')

And the module has to be changed as well to provide this interface:

// File: src/email/email.module.ts
@Module({
  providers: [
    {
      provide: IEmailService,
      useClass: EmailService,
    },
  ],
  exports: [IEmailService],
})
export class EmailModule {}

Although I don't recommend creating an interface for dependencies before there are at least two different implementations, creating one to enable spies is a reasonable exception to the rule. We want our spy to implement the exact same "API" as our production server, no more and no less. Before checking out the spy implementation, let's take a look on how it's used in the test case:

 test('create a new user and sends a confirmation email', async () => {
    // Arrange
    const server = testingApp.getHttpServer();

    // Act
    const response = await request(server).post('/auth/signup').send({
      email: 'new-user@mail.com',
      password: 'password',
    });

    // Assert
    const jwtRegex = /^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+$/;
    expect(response.body).toHaveProperty(
      'accessToken',
      expect.stringMatching(jwtRegex),
    );

    const emailServiceSpy = testingApp.get<EmailServiceSpy>(IEmailService); // The Spy is provided via the IEmailService token. However, we have to type it in the generics with `testingApp.get<EmailServiceSpy>` to have access to its helper methods below.

    emailServiceSpy
      .shouldHaveSentNumberOfEmails(1)
      .toAddress('new-user@mail.com')
      .withSubject('Welcome!')
      .withContent('Welcome to our app!');
  });

As you can notice from the code above, we build a spy that exposes a fluent-interface API we can use to build the assertions. Comparing to the use of mocks, it has the following benefits:

Readability. The assertion methods names can be written using more meaningful words than the parameter names alone.
Encapsulation. We don't have to know the actual parameter names inside the sendEmail() method - this is abstracted by the helper methods
Customizability. We can add and modify these helper methods for more complex use cases
Reusability. Once our spy is defined, we can reuse it for all tests with the IEmailService as a dependency.

Finally, here's the EmailSpy implementation (intentionally postponed as I deem its utilization more meaningful than the implementation details):

// File: src/email/test/email.service.spy.ts
@Injectable({
  scope: Scope.TRANSIENT, // Scope is transient to ensure we always provide a different instance for every class that depends on it.
})
export class EmailServiceSpy implements IEmailService {
  private readonly emailsSent: SendEmailInput[] = [];
  private readonly logger = new Logger(EmailServiceSpy.name);

  sendEmail(input: SendEmailInput): void {
    this.logger.debug(
      `Sending email to ${input.to} with subject ${input.subject}`,
    );
    this.emailsSent.push(input);
  }

  shouldHaveSentNumberOfEmails(expected: number) {
    expect(this.emailsSent.length).toBe(expected);
    return this;
  }

  toAddress(email: string) {
    const lastEmail = this.emailsSent.at(-1);
    expect(lastEmail?.to).toEqual(email);
    return this;
  }

  withSubject(subject: string) {
    const lastEmail = this.emailsSent.at(-1);
    expect(lastEmail?.subject).toEqual(subject);
    return this;
  }

  withContent(content: string) {
    const lastEmail = this.emailsSent.at(-1);
    expect(lastEmail?.content).toEqual(expect.stringContaining(content));
    return this;
  }
}

In the next section we'll cover using Stubs for our second feature scenario: 'returns an error when password hash is in a rainbow table'

Using Stubs for incoming interactions

Now that we covered testing an outgoing interaction with a Spy, let's get back to the second feature and write down its test case:

  test('returns an error when password hash is in a rainbow table', async () => {
    // Arrange
    const server = testingApp.getHttpServer();
    // We should have a way to stub the response of a "PasswordService" we haven't created yet.

    // Act
    const response = await request(server).post('/auth/signup').send({
      email: 'new-user@mail.com',
      password: 'weak',
    });

    // Assert
    expect(response.status).toBe(400);
    expect(response.body).toEqual({
      title: 'Bad Request',
      detail:
        'Your password has leaked in a data breach. Please choose a different one.',
    });
  });

The question now is how to fake the response of our yet-to-be-made PasswordService to simulate it returned true to the inquiry: "Is the password weak?". Again, let's use an interface to define what that service could look like:

// File: src/auth/password.service.interface.ts
export abstract class IPasswordService {
  abstract isPasswordInRainbowTable(password: string): Promise<boolean>;
}

Pretty straightforward. It receives a password as an input and returns true if found in a rainbow table and false otherwise. This abstract service must have an implementation that will be used by our AuthController as follows:

// File: src/auth/auth.controller.ts
@Controller('auth')
export class AuthController {
  constructor(
    private readonly emailService: IEmailService,
    private readonly passwordService: IPasswordService,
  ) {}

  @Post('signup')
  async signup(@Body() input: { email: string; password: string }) {
    const isPasswordInRainbowTable =
      await this.passwordService.isPasswordInRainbowTable(input.password);

    if (isPasswordInRainbowTable) {
      throw new BadRequestException({
        title: 'Bad Request',
        detail:
          'Your password has leaked in a data breach. Please choose a different one.',
      });
    }

    this.emailService.sendEmail({
      to: input.email,
      subject: 'Welcome!',
      content: 'Welcome to our app!',
    });
    return {
      accessToken: 'a.jwt.token',
    };
  }
}

And an example implementation:

// File: src/auth/password.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { IPasswordService } from './password.service.interface';

@Injectable()
export class PasswordService implements IPasswordService {
  private readonly logger = new Logger(PasswordService.name);

  isPasswordInRainbowTable(password: string): Promise<boolean> {
    this.logger.debug(`Checking if password is in rainbow table: ${password}`);
    return Promise.resolve(false);
  }
}

And the Provider definition:

// File: src/auth.module.ts
import { Module } from '@nestjs/common';
import { EmailModule } from '../email/email.module';
import { AuthController } from './auth.controller';
import { IPasswordService } from './password.service.interface';
import { PasswordService } from './password.service';

@Module({
  imports: [EmailModule],
  providers: [{ provide: IPasswordService, useClass: PasswordService }],
  controllers: [AuthController],
})
export class AuthModule {}

Up to this point, the e2e test we defined above fails because the PasswordService always returns false, so the password is always valid. Now, we have to replace the production implementation with the fake one in our tests, and for that, we'll leverage the jest-mock-extended library:

// File: src/auth/test/password.service.stub.ts
import { DeepMockProxy, mockDeep } from 'jest-mock-extended';
import { IPasswordService } from '../password.service.interface';

export function createPasswordServiceStub(): DeepMockProxy<IPasswordService> {
  return mockDeep<IPasswordService>();
}

export type PasswordServiceStub = DeepMockProxy<IPasswordService>;

This library provides a powerful mockDeep<I> function that can mock all methods (and deeply nested ones) of a given interface. With that stub defined, we can change the test case to make the isPasswordInRainbowTable(password) method return true:

  test('returns an error when password hash is in a rainbow table', async () => {
    // Arrange
    const server = testingApp.getHttpServer();
    const passwordServiceStub =
      testingApp.get<PasswordServiceStub>(IPasswordService);
    passwordServiceStub.isPasswordInRainbowTable.mockResolvedValueOnce(true);

    // Act
    const response = await request(server).post('/auth/signup').send({
      email: 'new-user@mail.com',
      password: 'weak',
    });

    // Assert
    expect(response.status).toBe(400);
    expect(response.body).toEqual({
      title: 'Bad Request',
      detail:
        'Your password has leaked in a data breach. Please choose a different one.',
    });
  });

Note that when we use a stub, we don't verify whether its method was called or what parameters it used - this is actually an anti-pattern. When we replace an incoming interaction from an external system, we should only care about the data it returns, and how that external dependency is called is merely an implementation detail.

Revision and Conclusion

This article discussed how to test unmanaged dependencies in Nest, and here are some key takeaways for your convenience:

We can define our system's dependencies as managed or unmanaged
We don't have control over unmanaged dependencies states, which are visible to the external world. Example: SMTP server;
We do have control over managed dependencies, which are hidden from the external world. Example: Our Database;
Managed dependencies should be used as is in our integration tests, while unmanaged ones should be replaced with test doubles;
Use Mocks when replacing outgoing interactions (our system sends data elsewhere), and Stubs when replacing incoming interactions (our system receives data from the external world);
Prefer using Spies over Mocks as they provide higher maintainability and customizability.

And that's all for today's post, fellow reader 😉. Thank you for reading this far, and let me know if you have more questions about testing strategies in NestJS.

Don't go all-in Clean Architecture: An alternative for NestJS applications

Thiago Valentim — Tue, 19 Mar 2024 20:52:52 +0000

Introduction

Hello again, my fellow readers! Lately, I've seen many people talking about Clean Architecture, both its pros and cons, and I thought it would be worth sharing some insights and takeaways from my past experiences as a Nest Consultant. In this short(er) post, I intend to show you the dangers of blindly adopting Clean Architecture in a new or existing project and what alternatives we have to ensure high-quality standards and ease of refactoring.

If you are that anxious type of person (or just don't have enough time to read the article now), I got you. You can check out the reference repository, which contains the implementation of the alternative I propose here: An application DSL.

If you are, however, interested in the details of how "Clean Architecture" might compromise your application, keep reading - I promise to be as concise as possible. Here's the summary of what we'll cover:

Why would we use Clean Architecture
Pitfalls of Clean Architecture
Creating abstractions where it matters: DSL
Using a DSL to leverage high protection against regressions and resistance to refactorings

Let's do this.

Why Clean Architecture

Clean Architecture is a term Uncle Bob coined in his homonymous book. I won't dive into its details now, as there are many resources out there with thorough explanations. Instead, we can focus on what I consider to be its main point: Independence.

If you read through the many definitions of Clean Architecture, you'll notice they have this sense of "Independability of details" in common. The idea is to divide our software into layers, each with its own well-defined responsibility, and the more high-level layers not depending on the lower-level ones (for instance, domain layer depending on infra layer). You can see this famous depiction of said architecture:

Pragmatically, we can apply this to a Nest application by creating an Interface for our services, separating the Presenter layer (Controller) from the Use Case (Services):

// user.service.interface.ts
export interface IUserService {
  findAll(): Promise<User[]>;
}

// user.service.ts
import { Injectable } from '@nestjs/common';
import { IUserService } from './user.service.interface';
import { User } from './user.entity';

@Injectable()
export class UserService implements IUserService {
  async findAll(): Promise<User[]> {
    // Implementation to retrieve all users
  }
}

// users.controller.ts
import { Controller, Get, Inject } from '@nestjs/common';
import { IUserService } from './user.service.interface';
import { User } from './user.entity';

@Controller('users')
export class UsersController {
  constructor(
    @Inject(UserService) private readonly userService: IUserService
  ) {}

  @Get()
  async findAll(): Promise<User[]> {
    return this.userService.findAll();
  }
}

In the example above, the UsersController uses the Dependency Inversion Principle (DIP) to separate the two layers we've mentioned. This approach decouples the controller and the implementation details of how the user service works. When we first see and apply this strategy, it sounds like a fantastic approach—but in reality, not always. I've been there, done that.

So, what's the problem? Isn't it great that we can easily separate and decouple these two layers?

The problem of Indirection

To be fair, indirection itself is not a problem. In fact, many complex systems are scalable precisely because of their well-thought abstractions and indirections. Recent advances in AI and LLMs are a good example of this. However, the issue arises when there is a proliferation of abstractions - which often happens when we go all-in for Clean Architecture.

Have you ever read an application's source code where you need to open dozens of tabs just to get to the gist of the business logic? This is generally an indication of excessive indirection. When we create interfaces for every layer and over-utilize DIP, we almost always get a complex-as-hell dependency tree. It hinders readability and understandability, especially for beginners.

Moreover, there's an additional problem of creating interfaces beforehand, which is nicely summarized by Vladimir Khorikov: "Abstractions are not created, they are discovered". That means good abstractions should only appear in your code base once there are at least two implementations for it. Otherwise, you'll risk creating a "pseudo-interface" only suitable for the underlying implementing class. You'll notice that pattern when you see an interface that looks like this:

interface Repository<Entity> {
  find(options: {
    select: keyof Entity,
    where: WhereOptions<Entity>,
    relations: Relations<Entity>
  }): Promise<Entity>
}

This might look innocuous initially, but it uses many terms and structures of Typeorm's Repository class. That means it will grow over time to look more and more like Typeorm's Repository and will fall short when the need arises to implement it for a different library.

Alright, so, if creating these abstractions too early might be bad for our architecture, what should we do to ensure we are not relying too much on frameworks or libraries?

Acceptance Tests and DSL to the rescue

Wait, what? How are acceptance tests an alternative to a Software Architecture? A good question, indeed. The reasoning here is simple, though. Whenever someone wants to adopt Clean Arch, they almost always want to have loosely coupled layers. But why is that? Well, so that they can easily change the underlying implementation without affecting the whole application. In other words, they want Resistance to Refactoring. That's exactly where Acceptance Tests shine.

Acceptance Tests, as defined by Dave Farley, are tests that "focuses on the outcome/purpose of the software, and not the technologies or implementation details. From a back-end perspective, that means an e2e type of test that (often) sees the API as a black box. Here's an example acceptance test for a [POST] /signup endpoint in Nest:

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

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

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

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

  test('/signup (POST) returns 400 when email is invalid', () => {
    return request(app.getHttpServer())
      .post('/iam/signup')
      .send({
        email: 'invalid-email',
        password: 'password',
        passwordConfirmation: 'password',
      })
      .expect(400);
  });

  test("/signup (POST) returns 400 when password and confirmation don't match", () => {
    return request(app.getHttpServer())
      .post('/iam/signup')
      .send({
        email: 'mail@mail.com',
        password: 'password',
        passwordConfirmation: 'password-different',
      })
      .expect(400);
  });

  test('/signup (POST) returns 201 and access token when email and password are valid', async () => {
    return request(app.getHttpServer())
      .post('/iam/signup')
      .send({
        email: 'mail@mail.com',
        password: 'password',
        passwordConfirmation: 'password',
      })
      .expect(201)
      .expect('Content-Type', /json/)
      .expect((response) => {
        expect(response.body.accessToken).toBeTruthy();
      });
  });

  test('/signup (POST) returns 409 when email is in use', async () => {
    await request(app.getHttpServer()).post('/iam/signup').send({
      email: 'mail@mail.com',
      password: 'password',
      passwordConfirmation: 'password',
    });

    return request(app.getHttpServer())
      .post('/iam/signup')
      .send({
        email: 'mail@mail.com',
        password: 'password',
        passwordConfirmation: 'password',
      })
      .expect(409);
  });
});

When focusing our testing strategy on Acceptance Tests, we ensure the highest possible Resistance to Refactoring and maintain a high Protection Against Regressions (Bugs). This means we can safely change the underlying implementation details to suit our needs.

On that note, these tests still depend on the supertest library. Moreover, we often see database queries in these tests to ensure we have saved some state change, and that will also couple with the ORM or query builder (or, God Forbid, manual SQL queries) you chose, making your tests brittle.

So, the last addition to this is using a Domain-Specific Language (DSL) for tests. A DSL, as well-explained in this video, is either an external or internal language we can use to write our tests and code in business terms. That pattern has the least coupling with the implementation details and increases the test's readability. Here's what our tests look like when using it:

import { INestApplication } from '@nestjs/common';
import { Test, TestingModule } from '@nestjs/testing';
import { AppModule } from './../src/app.module';
import { DSL, dsl as createDSL } from './dsl/dsl';

describe('Signup (e2e)', () => {
  let app: INestApplication;
  let dsl: DSL;

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

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

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

  test('/signup (POST) returns 400 when email is invalid', async () => {
    const response = await dsl.iam.signup({
      email: 'invalid-email',
      password: 'password',
      passwordConfirmation: 'password',
    });

    dsl.iam.assert(response).toBeBadRequest();
  });

  test("/signup (POST) returns 400 when password and confirmation don't match", async () => {
    const response = await dsl.iam.signup({
      email: 'mail@mail.com',
      password: 'password',
      passwordConfirmation: 'password-different',
    });

    dsl.iam.assert(response).toBeBadRequest();
  });

  test('/signup (POST) returns 201 and access token when email and password are valid', async () => {
    const response = await dsl.iam.signup({
      email: 'mail@mail.com',
      password: 'password',
      passwordConfirmation: 'password',
    });

    dsl.iam.assert(response).toBeUserSignedUpSuccessfully();
  });

  test('/signup (POST) returns 409 when email is in use', async () => {
    await dsl.iam.signup({
      email: 'mail@mail.com',
      password: 'password',
      passwordConfirmation: 'password',
    });

    const response = await dsl.iam.signup({
      email: 'mail@mail.com',
      password: 'password',
      passwordConfirmation: 'password',
    });

    dsl.iam.assert(response).toBeUserExistsConflict();
  });
});

The dsl object above encapsulates HTTP request calls to our application, and it's divided by domains - in this case, we have Identity and Access Management (IAM). This allows us to abstract how our application is called and also how we assert that something has happened, as in the dsl.iam.assert(response).toBeUserSignedUpSuccessfully() call. The underlying implementation could be a call to a database, a check in an array, or anything else.

This DSL also encourages reusability. When testing for a sign-in feature, we can use the DSL above to sign up a user beforehand, not needing to manually insert a "user" into our database using a specific library. With that powerful tool in hand, you almost don't need any other type of test to ensure your application is always working as intended.

Conclusion

As seen above, Clean Architecture has relevant tenets: encapsulation, low coupling, and separation of concerns. That said, we also discussed how it might increase indirections, which hinder an application's maintainability. So, if you plan on applying it to a new or existing project, first consider why you want to do it. If you're looking for ease of refactoring, focusing on Acceptance Tests and creating a DSL might be a better alternative. In that case, you'll have fewer interfaces and classes to read while keeping the implementation detail loosened from the application's behavior.

I hope this article has shed some light on this controversial topic. Leave a comment if you have more thoughts on that note - it's always worth sharing our experiences 😉. See you in the next one!

Unit Testing Auth0 Custom Database Scripts

Thiago Valentim — Wed, 13 Mar 2024 14:11:43 +0000

Introduction

Welcome, fellow developers! Today I want to present you a step-by-step technique on how to test Auth0’s custom actions and databases in Javascript. For those of you who don’t know Auth0, it’s an identity management platform that you can connect to your existing or new applications, and configure it to easily provide authentication and authorization mechanisms. It’s one of the easiest solutions for IAM nowadays.

You can check the reference repository if you just want to see the final result, but I encourage you to keep reading if you also want to understand the thought process. Here's what we'll learn:

How to use auth0-deploy-cli to keep you tenant's configuration, code, and settings in a local repo
How to create tests for your custom database
How to apply TDD to create the tests above and implement the scripts
How to use Spies instead of Mocks to test network calls to external services
How to inject dependencies in database scripts
How to use globally-defined objects for testing
How to properly handle errors in Auth0

Without further ado, let's get into it!

Auth0 Custom Database Scripts

So, what are Auth0’s custom database scripts? To be concise, these are scripts used to connect to an existing application’s database to perform the following actions:

Create - This script will create a user in your database when someone signs up via Auth0
Login - This script authenticates a user against the credentials stored in your database.
Delete - Once a user is deleted via Auth0’s dashboard or Management API, this script ensures the user is also deleted in your database.
Get User - This script determines whether a user with a given email exists. It’s executed when users change their password to determine if they exist.
Verify - This script marks the current user’s email address as verified in your database
Change Password - This script should change the password stored for the current user in your database.

These actions must be highly maintainable and reliable — after all, your application’s authorization and authentication flows will go through them. Creating unit tests for these custom database scripts is extremely valuable to ensure everything is working as expected while also serving as live documentation for IAM. In the next section, we’ll see what we need to start creating tests for our Auth0 Tenant scripts.

Pulling the tenant data

Before creating tests for our scripts, we need our tenant’s data and configuration in our local machines. To do so, we must install auth0-deploy-cli. This tool can download your tenant’s configuration and schema to local folders. Follow the steps below to configure it and pull your tenant’s data:

The steps below assume you already have an Auth0 tenant created.

Create a new Database authentication method. We’ll use this as our example external database that Auth0 needs to connect to and synchronize with. Go to Authentication > Database > Create DB Connection to create it.
1. Go to the Custom Database tab and toggle the Use my own Database switch. This will enable all the custom database action scripts.
Install the CLI tool using your preferred package manager: yarn add -D auth0-deploy-cli
Create an Auth0 Application to represent the CLI tool access. To do so, go to the dashboard, Applications > Applications > Create Application > Machine to Machine.
1. Select the Auth0 Management API as the authorized party. Then, you can select all the permissions for the purpose of this exercise - ideally, you’d go with the least-privileges strategy.
Create a file named config.json in the root of your project, and put the following data into it:

{
  "AUTH0_DOMAIN": "auth0-domain", // You can check this in the application you just created, under the `settings` tab
  "AUTH0_CLIENT_ID": "auth0-deploy-application-client-id",
  "AUTH0_CLIENT_SECRET": "auth0-deploy-application-client-secret",
  "AUTH0_ALLOW_DELETE": false
}
// These values are used by the CLI to connect to your Auth0 tenant and potentially pull / push data.

Create a script in your package.json file to pull changes from the tenant to your local file system:

{
  "scripts": {
      "a0deploy export -c config.json --format=yaml --output_folder=tenant"
  }
}

Execute the script with your package manager. Then, your directory structure will look like the following:

📦tenant
 ┣ 📂databases
 ┃ ┗ 📂Database // This folder represents the Database Authentication we've created
 ┃ ┃ ┣ 📜change_password.js
 ┃ ┃ ┣ 📜create.js
 ┃ ┃ ┣ 📜delete.js
 ┃ ┃ ┣ 📜get_user.js
 ┃ ┃ ┣ 📜login.js
 ┃ ┃ ┗ 📜verify.js
 ┣ 📂emailTemplates
 ┣ 📂hooks
 ┣ 📂pages
 ┣ 📂rules
 ┗ 📜tenant.yaml // This file stores all the tenant's settings and data

At this point, we’re ready to start creating tests for our database scripts. We’ll see how to do that in the next section.

Creating tests for database scripts

Finally, we have (almost) everything set up to start writing our tests - but before we do so, let’s make it clear that we need an example definition of an API that is a port to our external database. You can check out all the requirements in the Readme file, but let’s take care of a single endpoint for now, the signup:

POST /signup - used to create users
- Body:
  - `email`: The user's email
  - `password`: The user's password
  - `passwordConfirmation`: The user's password confirmation
- Response:
  - ✅ **Success**:
    - **status**: 201
    - **body**: 
      - `id`: The user's id
  - ❌ **Error**: 
    - **status**: 400 | 500
    - **body**: 
      - `error`: The error message

With that information, we’ll start defining which tests we need before implementing anything. Create a new file under /tenant/test/databases/create.test.js . There, we’ll determine what needs to be done:

const { test, describe } = require('node:test');
const assert = require('node:assert/strict');

describe('Create user script', () => {
  test.todo('successfully creates a user');
  test.todo('calls axios post with correct parameters');
  test.todo('throws validation error when user already exists');
  test.todo('throws error with descriptive message when something goes wrong');
});

Notice that we’re using node’s native test module - the idea is to use the least number of dependencies, and node’s test runner has all features we need here - while also being way faster than jest.

To execute test files with node’s test runner, we need to add another script to our package.json file:

{
    "scripts": {
      "test": "node --test"
    }
}

Now, you can simply execute it like yarn test and see the results. Remember, you’ll need Node’s LTS version to make it work!

So, we must pick one test case above and define its body. Then, we’ll implement the least amount of code that we need to make it pass - this is how we apply the famous Test-Driven Development (TDD). Let’s start with the first test, namely, “successfully creates a user”. This is the easiest one to begin with - if you look at the generated comments for the create.js script, the expected result when the user is successfully created is that it should call the callback function with null:

// There are three ways this script can finish:
  // 1. A user was successfully created
  //     callback(null);
  // 2. This user already exists in your database
  //     callback(new ValidationError("user_exists", "my error message"));
  // 3. Something went wrong while trying to reach your database
  //     callback(new Error("my error message"));

Considering that requirement now, let’s define the test body as follows:

const { test, describe, mock } = require('node:test');
const assert = require('node:assert/strict');
const { randomUUID } = require('node:crypto');
const { create } = require('../../databases/Database/create');

describe('Create user script', () => {
  test('successfully creates a user', async () => {
    // Arrange
    const user = makeUserData();
    const callback = mock.fn();

    // Act
    await create(user, callback);

    // Assert
    assert.equal(callback.mock.callCount(), 1);
    assert.deepEqual(callback.mock.calls[0].arguments, [null]);
  });
  test.todo('calls axios post with correct parameters');
  test.todo('throws validation error when user already exists');
  test.todo('throws error with descriptive message when something goes wrong');
});

function makeUserData() {
  return {
    email: 'user@mail.com',
    password: randomUUID(),
    tenant: 'test-tenant',
    client_id: 'test-client-id',
    connection: 'Database',
  };
}

As you can see, the only expected behavior here is that our callback function, created using node’s mock utility, was called with null argument. the makeUserData() utility function returns an object with the interface the create script expects.

Now, after executing this test and seeing it failing, we’ll change the source code to make it pass:

// You have to manually  change the code below to explicitly export the `create` function,
// otherwise you can't import that function into the test file. It still works in Auth0, so no need to worry :)
module.exports.create = async function create(user, callback) {
  // Auto-generated docs redacted
  return callback(null);
};

The first test should pass now. Great! That's our first step towards implementing this create custom script. Before we move to the next ones, we can perform a slight improvement to our "Assert" block in our test code, which reads a bit weird now:

// Assert
assert.equal(callback.mock.callCount(), 1);
assert.deepEqual(callback.mock.calls[0].arguments, [null]);

We can improve the readability of this type of test by creating a new utility:

// mock-extended.js file
const { mock } = require('node:test');
const assert = require('node:assert/strict');

function mockFn() {
  const mockedFunction = mock.fn();
  mockedFunction.shouldHaveBeenCalledOnceWith = (expectedArgument) => {
    assert.equal(mockedFunction.mock.callCount(), 1);
    assert.deepEqual(
      mockedFunction.mock.calls[0].arguments[0],
      expectedArgument
    );
  };
  return mockedFunction;
}

module.exports = {
  mockFn,
};

The mock-extended file above exposes a factory to create an enhanced node's native mock object. This object has an additional shouldHaveBeenCalledOnceWith(argument) method to increase the test readability. Here's how we can rewrite the test:

test('successfully creates a user', async () => {
    // Arrange
    const user = makeUserData();
    const callback = mockFn();

    // Act
    await create(user, callback);

    // Assert
    callback.shouldHaveBeenCalledOnceWith(null);
  });

Way more expressive, don't you agree? The next step is to implement another todo test, test.todo('calls axios post with correct parameters');. This test will require more sophistication, so we'll dive into it in the next section.

Creating and injecting Spies to communicate with external services

Mocking is a common practice when testing your application's behavior when communicating with external services. Mocks are a particular type of Test Double, an object used to replace the production one for testing purposes. However, mocks in Javascript are not so great because they don't provide a nice API for stubbing returned values or checking for called values (as you can notice with the callback mock example, we had to create a new utility).

A more helpful approach when we want to override communication with external services is to create a Spy. A Spy is an object that follows the same API as the production one but returns canned data and stores what was called internally. This is useful to make the test code cleaner and readable while also encapsulating the details of how the stubbing process works underneath it. Moreover, you can reutilize the Spy definition across different tests.

So, let's get back to what we needed for the new test:

test.todo('calls axios post with correct parameters');

This test aims to ensure we called axios.post with the URL and body parameters as defined in the requirements:

URL: POST /signup
Body: email, password, and passwordConfirmation

We'll use an AxiosSpy class to test this with a nice fluent interface. However, to use this spy, we also need the create script to accept an instance of axios as an additional parameter, otherwise we can't inject our spy:

module.exports.create = async function create(user, callback, axios = require('axios') {
  // Auto-generated docs redacted
  return callback(null);
};

The default value of this axios instance will be used in the production environment. Now, let's get back to the test:

const { test, describe } = require('node:test');
const { mockFn } = require('../utils/mock-extended');
const { AxiosSpy, HttpMethod } = require('../utils/axios.spy');
const { randomUUID } = require('node:crypto');
const { create } = require('../../databases/Database/create');

describe('Create user script', () => {
  test('successfully creates a user', async () => {
    // Arrange
    const user = makeUserData();
    const callback = mockFn();
    const axiosSpy = new AxiosSpy();

    // Act
    await create(user, callback, axiosSpy);

    // Assert
    callback.shouldHaveBeenCalledOnceWith(null);
  });
  test('calls axios post with correct parameters', async () => {
    // Arrange
    const user = makeUserData();
    const callback = mockFn();
    const axiosSpy = new AxiosSpy();

    // Act
    await create(user, callback, axiosSpy);

    // Assert
    axiosSpy
      .shouldHaveSentNumberOfRequests(1)
      .withUrl(new URL('https://backend/signup'))
      .withMethod(HttpMethod.Post)
      .withBody({
        email: user.email,
        password: user.password,
        passwordConfirmation: user.password,
      });
  });
  test.todo('throws validation error when user already exists');
  test.todo('throws error with descriptive message when something goes wrong');
});

function makeUserData() {
  return {
    email: 'user@mail.com',
    password: randomUUID(),
    tenant: 'test-tenant',
    client_id: 'test-client-id',
    connection: 'Database',
  };
}

Notice that we also had to change the first test case to inject the AxiosSpy instance, otherwise, it would try to use the actual axios object. We execute the test to see it failing, and then we can add the missing implementation:

module.exports.create = async function create(
  user,
  callback,
  axios = require('axios')
) {
  const { email, password } = user;

  await axios.post(new URL('https://backend/signup'), {
    email,
    password,
    passwordConfirmation: password,
  });

  return callback(null);
};

This should suffice to make the test pass, so we'll dive into the next step: using global objects.

Using global references in tests

Checking the next test we need to implement you'll notice it requires a globally defined object:

test.todo('throws validation error when user already exists');

This ValidationError is an internal error created by Auth0's runtime that you can use without importing it. The create function template comes with the following comment:

// 2. This user already exists in your database
  //     callback(new ValidationError("user_exists", "my error message"));

So, how do we make it available for our tests? Simple enough, just define a ValidationError class in the test file global context:

global.ValidationError = class ValidationError extends Error {
  constructor(code, message) {
    super(message);
    this.code = code;
  }
};

Now, we can write down the test specification:

test('throws validation error when user already exists', async () => {
    // Arrange
    const user = makeUserData();
    const callback = mockFn();
    const axiosSpy = new AxiosSpy();
    axiosSpy.stubResponseFor(
      HttpMethod.Post,
      new URL('https://backend/signup'),
      {
        status: 404,
        body: {
          error: 'user already exists',
        },
      }
    );

    // Act
    await create(user, callback, axiosSpy);

    // Assert
    callback.shouldHaveBeenCalledOnceWith(
      new ValidationError('user_exists', 'User already exists')
    );
  });

We can execute this test to guarantee it's failing for the right reason now: the callback function wasn't called with that validation error. Here's what we need to change to make it pass:

module.exports.create = async function create(
  user,
  callback,
  axios = require('axios')
) {
const { email, password } = user;

try {
  await axios.post(new URL('https://backend/signup'), {
    email,
    password,
    passwordConfirmation: password,
  });
} catch (error) {
  return callback(new ValidationError('user_exists', 'User already exists'));
}
  return callback(null);
};

Now the test works again ✅. We can use this same strategy for other globally-defined objects in Auth0, such as the configuration object used to store sensitive information.

The final step now is to make sure the last test also passes. It should be straightforward, as we don't need any additional constructs:

test('throws error with descriptive message when something goes wrong', async () => {
    // Arrange
    const user = makeUserData();
    const callback = mockFn();
    const axiosSpy = new AxiosSpy();
    axiosSpy.stubUnexpectedErrorFor(
      HttpMethod.Post,
      new URL('https://backend/signup'),
      new Error('Network error')
    );

    // Act
    await create(user, callback, axiosSpy);

    // Assert
    callback.shouldHaveBeenCalledOnceWith(
      new Error(
        'Something went wrong while trying to sign up user (Network error)'
      )
    );
  });

This test ensures we handle unexpected errors properly, wrapping their message into our own. Here's the implementation to make it pass:

module.exports.create = async function create(
  user,
  callback,
  axios = require('axios')
) {
const { email, password } = user;

try {
  await axios.post(new URL('https://backend/signup'), {
    email,
    password,
    passwordConfirmation: password,
  });
} catch (error) {
  if (error.response?.status === 404)
    return callback(new ValidationError('user_exists', 'User already exists'));

  return callback(
    new Error(
      `Something went wrong while trying to sign up user (${error.message})`
    )
  );
}
  return callback(null);
};

Now all unit tests are passing, and we've completed the create script.

Conclusion

Automated tests are undeniably essential to ensure our code's maintainability. Without proper tests, we can't trust any code changes and have to rely on expensive manual tests. Auth0's custom scripts aren't an exception—in fact, since they play such an important role in our system, they should be thoroughly tested. This article explained how to do it while also teaching a few tips and tricks.

If readers show enough interest, the next article in this series will discuss how to perform integration tests and use them in your CI. I hope this one has helped you start testing Auth0 scripts.

See you in the next one!