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

REST API Testing Tool for all levels in a Test Pyramid

PactumJS is a REST API Testing Tool used to automate e2e, integration, contract & component (or service level) tests. It comes with a powerful mock server which can control the state of external dependencies. ⚡ Swift 🎈 Lightweight 🚀 Simple & Powerful 🛠️ Compelling Mock Server 💎 Elegant Data Management 🔧 Extendable & Customizable 📚 Clear & Comprehensive Testing Style 🔗 Component, Contract & E2E testing of APIs

Documentation

This readme offers an basic introduction to the library. Head over to the full documentation at https://pactumjs.github.io

• API Testing
• Integration Testing
• Component Testing
• Contract Testing
• E2E Testing

Need Help

We use Github Discussions to receive feedback, discuss ideas & answer questions.

Installation

# install pactum as a dev dependency
npm install --save-dev pactum


# install a test runner to run pactum tests

# mocha / jest / cucumber
npm install --save-dev mocha

Usage

pactum can be used for all levels of testing in a test pyramid. It can also act as an standalone mock server to generate contracts for consumer driven contract testing.

API Testing

Tests in pactum are clear and comprehensive. It uses numerous descriptive methods to build your requests and expectations.

Simple Test Cases

Using Mocha

Running simple api test expectations.

const pactum = require('pactum');

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

it('should save a new user', async () => {
  await pactum.spec()
    .post('https://jsonplaceholder.typicode.com/users')
    .withHeaders('Authorization', 'Basic xxxx')
    .withJson({
      name: 'bolt',
      email: '[e-mail]'
    })
    .expectStatus(200);
});

# mocha is a test framework to execute test cases
mocha /path/to/test

Using Cucumber

See pactum-cucumber-boilerplate for more details on pactum & cucumber integration.

// steps.js
const pactum = require('pactum');
const { Given, When, Then, Before } = require('cucumber');

let spec = pactum.spec();

Before(() => { spec = pactum.spec(); });

Given('I make a GET request to {string}', function (url) {
  spec.get(url);
});

When('I receive a response', async function () {
  await spec.toss();
});

Then('response should have a status {int}', async function (code) {
  spec.response().should.have.status(code);
});

Scenario: Check TeaPot
  Given I make a GET request to "http://httpbin.org/status/418"
  When I receive a response
  Then response should have a status 200

Mock Server

pactum can act as a standalone mock server that allows us to mock any server via HTTP or HTTPS, such as a REST endpoint. Simply it is a simulator for HTTP-based APIs.

Running pactum as a standalone mock server.

const { mock } = require('pactum');

mock.addInteraction({
  request: {
    method: 'GET',
    path: '/api/projects'
  },
  response: {
    status: 200,
    body: [
      {
        id: 'project-id',
        name: 'project-name'
      }
    ]
  }
});

mock.start(3000);

Notes

Inspired from frisby and pact.

Support

Like this project! Star it on Github. Your support means a lot to us.

Contributors

If you've ever wanted to contribute to open source, and a great cause, now is your chance! See the contributing docs for more information

Thanks to all the people who contribute.