Nestjs-pact NPM

About

This package enables you to consume Pact.js in a way that can be used very easily in NestJS. \ Like the nature of Pact, this package is for testing purposes only.

If you are not familiar with Pact, Pact is fast, easy and reliable testing framework for integrating web apps, APIs and microservices. Read more on Pact official website

There are two main modules suggested; one for the Producer role (Verifier), and one for the Consumer role (creating Pact files and publish), each loaded separately. Of course you can also use both modules and play the role of Consumer and Producer at the same time.

Installation

npm i -D nestjs-pact

Introduction

The use of each of the modules suggested here, is made in the common and accepted form of NestJS modules. The simplest way is to use the register method and pass the settings directly. It is also enable to use the registerAsync method to pass the settings in the form of useFactory or useClass for example.

One more thing - the usage of the modules is done in tests only, which is not quite common in the use of NestJS modules, so there are some good examples down below. The obvious advantage of this package is that Pact can be used in combination with the techniques and benefits offered by NestJS.

Getting Started

Soon we will add a full working end-to-end example to demonstrate how to Pact is working with NestJS with nestjs-pact package

Consumer

In order to use the Consumer module, you need to follow a few simple steps, let's go over it!

First, create a file called pact.module.ts in your test folder (or wherever you put your tests), and simply load the PactConsumerModule like below:

test/pact/pact.module.ts

import { Module } from '@nestjs/common';
import { PactConsumerModule } from 'nestjs-pact';

@Module({
  imports: [
    PactConsumerModule.register({ ... }),
  ],
})
export class PactModule {}

Yay, now let's create the test file! let's call it my-test.spec.ts

test/pact/my-test.spec.ts

import { Pact } from '@pact-foundation/pact';
import { Test } from '@nestjs/testing';
import { PactFactory } from 'nestjs-pact';
import { PactModule } from '@test/pact/pact.module';

describe('Pact', () => {
  let pactFactory: PactFactory;
  let provider: Pact;

  beforeAll(async () => {
    const moduleRef = await Test.createTestingModule({
      imports: [SomeOtherModule, AndAnotherModuleYouNeed, PactModule],
    }).compile();

    pactFactory = moduleRef.get(PactFactory);

    provider = pactFactory.createContractBetween({
      consumer: 'Consumer Service Name',
      provider: 'Producer Service Name',
    });

    await provider.setup();
  });

  afterEach(() => provider.verify());

  afterAll(() => provider.finalize());

  describe('when something happens', () => {
    describe('and another thing happens too', () => {
      beforeAll(() => provider.addInteraction({ ... }));

      it('should do something', () => {
        return expect( ... );
      });
    });
  });
});

If you are not sure how to write the test itself, the great end-to-end example from Pact's Github would surely help!

Now let's look how we can publish the pacts created from the test file to a Pact broker!

test/pact/publish-pacts.ts

import { NestFactory } from '@nestjs/core';
import { Logger, LoggerService } from '@nestjs/common';
import { Publisher } from '@pact-foundation/pact';
import { PactModuleProviders } from 'nestjs-pact';
import { PactModule } from '@test/pact/pact.module';

(async () => {
  const app = await NestFactory.createApplicationContext(PactModule);

  const publisher: Publisher = app.get(PactModuleProviders.PactPublisher);
  const logger: LoggerService = app.get(Logger);

  if (process.env.CI !== 'true') {
    logger.log('Skipping Pact publish as not on CI');
    process.exit(0);
  }

  try {
    await publisher.publishPacts();

    logger.log('Pact contract publishing complete!');
    logger.log('');
    logger.log('Head over to https://test.pact.dius.com.au/ and login with');
    logger.log('=> Username: dXfltyFMgNOFZAxr8io9wJ37iUpY42M');
    logger.log('=> Password: O5AIZWxelWbLvqMd8PkAVycBJh2Psyg1');
    logger.log('to see your published contracts.');
  } catch (e) {
    logger.error('Pact contract publishing failed: ', e);
  }
})();

npx ts-node test/pact/publish-pacts.ts

Run the file and you are good to go :)

Note: in your tsconfig.json file make sure you set allowJs to true in order to run the file

Producer

The usage in the Producer service is quite easy; In your /test folder (or wherever you put your tests) create a simple test module with NestJS Test.createTestingModule method and import the PactProducerModule module from nestjs-pact.

You can use register or registerAsync method, make sure you stick to PactProducerOptions interface options. \ After creating the Nest application from the testing module, pass the app instance to the verify method, it will generate a random (available) port, spin up the application and run the verifier against the application url.

You can read more about Pact Verification in the official Pact documentation

Here is a quick and simple example:

import { Test } from '@nestjs/testing';
import { INestApplication, Logger, LoggerService } from '@nestjs/common';
import { PactProducerModule, PactVerifierService } from 'nestjs-pact';
import { AppModule } from '@app/app.module';

describe('Pact Verification', () => {
  let verifierService: PactVerifierService;
  let logger: LoggerService;
  let app: INestApplication;

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

    verifierService = moduleRef.get(PactVerifierService);
    logger = moduleRef.get(Logger);

    app = moduleRef.createNestApplication();

    await app.init();
  });

  it('validates the expectations of Matching Service', async () => {
    const { output } = await verifierService.verify(app);

    logger.log('Pact Verification Completed!');
    logger.log(output);
  });

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

Contributing

If you want to contribute to the project, I will be more than happy :) \ Take a few minutes to review the project code, and start get your hands dirty.

It is important to note the following steps beforehand:

Fork the repository
Create your branch in the form of <bug|feature>/<semver-path>/<description> (git checkout -b feature/minor/add-something)
Commit the changes to your branch
Push your changes to your remote branch
Open a pull request