PactumJS is an MIT-licensed JavaScript library for REST API testing that automates end-to-end, integration, contract, and component (service-level) tests across every level of the test pyramid, aimed at Node.js developers and QA engineers who want one tool for API verification and API mocking.

What it is

PactumJS is a REST API testing tool distributed as the npm package pactum. It lives in the JavaScript and Node.js ecosystem and provides a chainable spec() API for building HTTP requests and assertions, plus a standalone mock server for HTTP or HTTPS interactions. The library positions itself as usable at all levels of a test pyramid: API testing, integration testing, component or service-level testing, contract testing, and E2E testing. It is written in JavaScript, carries the MIT licence, and its homepage and full documentation sit at https://pactumjs.github.io.

The concrete problem it solves is that API testing across several pyramid levels usually requires stitching together separate request clients, assertion helpers, and mock servers. PactumJS replaces that assembly with a single dependency that both drives real HTTP calls and simulates HTTP-based APIs. Rather than writing bespoke request wrappers, a test calls descriptive methods such as get, post, withHeaders, withJson, and expectStatus directly, and a mock server can stand alone to generate contracts for contract testing.

Key capabilities

• Chainable request building and assertions through spec(), for example await spec().get('http://httpbin.org/status/418').expectStatus(418).
• Request configuration methods including withHeaders('Authorization', 'Basic xxxx') and withJson({ name: 'bolt', email: '[email protected]' }).
• Standalone mock server via mock.addInteraction() and mock.start(3000), described as a simulator for HTTP-based APIs over HTTP or HTTPS.
• Mock interactions generated to produce contracts for contract testing.
• BDD style support through Cucumber, documented with the pactum-cucumber-boilerplate and step definitions using Before, Given, When, and Then from @cucumber/cucumber.
• Assertion surface on responses, such as spec.response().should.have.status(code) combined with await spec.toss().
• Coverage of component, contract, and E2E testing of APIs, plus integration and API testing guides in the documentation.

Who uses it and how

• Teams testing a full test pyramid in one codebase, using the same spec() style for API, integration, component, contract, and E2E layers.
• Node.js projects running tests under a test runner, with Mocha, Jest, or Cucumber named as the execution layer (mocha /path/to/test).
• BDD-oriented teams that write Gherkin scenarios such as "Given I make a GET request to ..." and wire them to PactumJS steps, following the pactum-cucumber-boilerplate.
• Service and component owners who need a local or standalone mock server for an HTTP-based API while real dependencies are unavailable.
• Teams generating contracts for contract testing by running PactumJS as a standalone mock server rather than as part of a test suite.

Getting started

Install as a development dependency with npm install --save-dev pactum and pair it with a test runner such as npm install --save-dev mocha, or scaffold a project directly with npx pactum-init.

How it compares

PactumJS is a library rather than a test runner, so the runners named around it — Mocha, Jest, and Cucumber — execute the tests while PactumJS supplies request building, assertions, mocking, and contract generation. In that arrangement the runner owns discovery and reporting, and PactumJS owns the HTTP behaviour under test.

When to use it — and when not to

PactumJS is a JavaScript library, so teams not working on Node.js will need another tool, and the repository README describes itself as only a basic introduction, with the authoritative material hosted at https://pactumjs.github.io. The project is actively maintained, with its last push on 2026-08-11, 18 open issues, and 620 stars, but no database, object storage, or SMTP component is mentioned in the README, so self-hosting means running the package and a test runner rather than operating infrastructure.

# 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

npx pactum-init

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

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

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

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

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

// steps.js
const pactum = require('pactum');
const { Given, When, Then, Before } = require('@cucumber/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);
});

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