pactum

What is pactum?

Pactum is a REST API testing tool that allows you to write tests in a simple and readable manner. It supports various types of testing including functional, end-to-end, and performance testing. Pactum is designed to be easy to use and integrates well with other testing frameworks.

What are pactum's main functionalities?

API Testing

This feature allows you to test REST APIs by making HTTP requests and validating the responses. The code sample demonstrates a GET request to a sample API and checks the status code and JSON response.

const pactum = require('pactum');
pactum.spec()
  .get('https://jsonplaceholder.typicode.com/posts/1')
  .expectStatus(200)
  .expectJson({
    userId: 1,
    id: 1,
    title: 'sunt aut facere repellat provident occaecati excepturi optio reprehenderit',
    body: 'quia et suscipit\nsuscipit...'
  })
  .toss();

Mock Server

Pactum allows you to create a mock server to simulate API responses. This is useful for testing scenarios where the actual API is not available. The code sample shows how to set up a mock server that responds to a GET request.

const pactum = require('pactum');
const { mock } = pactum;
mock.addInteraction({
  request: {
    method: 'GET',
    path: '/api/users'
  },
  response: {
    status: 200,
    body: [{ id: 1, name: 'John Doe' }]
  }
});
mock.start(3000);

BDD Style Testing

Pactum supports Behavior-Driven Development (BDD) style testing, which makes tests more readable and easier to understand. The code sample demonstrates how to write BDD style tests using Given, When, and Then.

const pactum = require('pactum');
const { Given, When, Then } = require('pactum').bdd;
Given('a user exists', () => {
  pactum.spec()
    .get('https://jsonplaceholder.typicode.com/users/1')
    .expectStatus(200);
});
When('I get the user details', () => {
  pactum.spec()
    .get('https://jsonplaceholder.typicode.com/users/1');
});
Then('I should see the user details', () => {
  pactum.spec()
    .get('https://jsonplaceholder.typicode.com/users/1')
    .expectJson({
      id: 1,
      name: 'Leanne Graham'
    });
});

Other packages similar to pactum

supertest

Supertest is a popular library for testing Node.js HTTP servers. It provides a high-level abstraction for testing HTTP, making it easy to write tests for your APIs. Compared to Pactum, Supertest is more focused on testing Express.js applications and does not offer built-in support for BDD style testing or mock servers.

chai-http

Chai-HTTP is an extension of the Chai assertion library that provides HTTP integration testing capabilities. It allows you to make HTTP requests and assertions in a fluent style. While Chai-HTTP is powerful, it requires more setup and does not offer the same level of built-in features as Pactum, such as mock servers and BDD style testing.

nock

Nock is a library for HTTP mocking and expectations. It allows you to intercept HTTP requests and provide predefined responses, making it useful for testing without making actual network requests. Nock is more focused on mocking and does not provide the same level of API testing capabilities as Pactum.

README

pactum

Introduction

pactum is a REST API Testing Tool that combines the implementation of consumer driven contract library Pact for Javascript.

Installation

npm install pactum --save-dev

Creating Simple Tests

Running a single component test expectation.

const pactum = require('pactum');

it('should be a teapot', async () => {
  await pactum
    .get('http://httpbin.org/status/418')
    .expectStatus(418)
    .toss();
});

Running a component test with the help of mock server & a single mock interaction. If the mock interaction is not exercised, the test will fail.

const pactum = require('pactum');

before(async () => {
  await pactum.mock.start();
});

it('GET - one interaction', async () => {
  await pactum
    .addMockInteraction({
      withRequest: {
        method: 'GET',
        path: '/api/projects/1'
      },
      willRespondWith: {
        status: 200,
        headers: {
          'content-type': 'application/json'
        },
        body: {
          id: 1,
          name: 'fake'
        }
      }
    })
    .get('http://localhost:9393/api/projects/1')
    .expectStatus(200)
    .expectJsonLike({
      id: 1,
      name: 'fake'
    })
    .toss();
});

after(async () => {
  await pactum.mock.stop();
});

Running a component test with the help of mock server & a single pact interaction. If the mock interaction is not exercised, the test will fail.

const pactum = require('pactum');

before(async () => {
  await pactum.mock.start();
});

it('GET - one interaction', async () => {
  await pactum
    .addPactInteraction({
      consumer: 'little-consumer',
      provider: 'projects-service',
      state: 'when there is a project with id 1',
      uponReceiving: 'a request for project 1',
      withRequest: {
        method: 'GET',
        path: '/api/projects/1'
      },
      willRespondWith: {
        status: 200,
        headers: {
          'content-type': 'application/json'
        },
        body: {
          id: 1,
          name: 'fake'
        }
      }
    })
    .get('http://localhost:9393/api/projects/1')
    .expectStatus(200)
    .expectJsonLike({
      id: 1,
      name: 'fake'
    })
    .toss();
});

after(async () => {
  await pactum.mock.stop();
});

API

Basics

Basics

Method	Description	Usage
get	performs a GET request on the resource	pactum.get('url')
expectStatus	expects a status code from the resource	pactum.get('url').expectStatus(200)
toss	executes the test case and returns a promise	await pactum.get('url').toss()

HTTP Methods

HTTP Methods

Method	Description	Usage
get	performs a GET request on the resource	pactum.get('')
post	performs a POST request on the resource	pactum.post('')
put	performs a PUT request on the resource	pactum.put('')
delete	performs a DELETE request on the resource	pactum.delete('')
patch	performs a PATCH request on the resource	pactum.patch('')
head	performs a HEAD request on the resource	pactum.head('')
options	performs a OPTIONS request on the resource	pactum.options('')