pactum

library0.2.0jsnpmunverified

PactumJS is a lightweight and powerful open-source REST API testing tool designed to automate various levels of API testing, including end-to-end (e2e), integration, contract, and component (service level) tests. It emphasizes a clear and comprehensive testing style, utilizing numerous descriptive methods for building requests and defining expectations. The current stable version is 3.9.1, with minor releases occurring frequently, demonstrating active development and maintenance. Key differentiators include its compelling built-in mock server, elegant data management capabilities for dynamic values, robust built-in JSON schema validation, and an extendable architecture. PactumJS supports various JavaScript test runners like Mocha, Jest, and Cucumber, making it adaptable to different testing frameworks and helping simplify complex API testing scenarios across the entire test pyramid.

testing http-networking

npm install pactum

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PACTUM

pactum

testingjavascriptv0.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

spec

✓ import { spec } from 'pactum'

✗ import pactum from 'pactum'; pactum.spec(); // 'spec' is a named export, not a property of a default export

The primary function to start a test specification. Use named import for ESM/TypeScript. For CommonJS, use `const { spec } = require('pactum');`.

pactum (module object)

✓ import * as pactum from 'pactum'

✗ import pactum from 'pactum'; // There is no default export; 'pactum' contains named exports and properties

Import the entire module to access global settings (e.g., `pactum.settings`), `stash`, or other utilities. Use `* as` for ESM or `const pactum = require('pactum');` for CommonJS.

Spec

✓ import type { Spec } from 'pactum'

✗ import { Spec } from 'pactum'; // 'Spec' is a type, not a runtime value, leading to potential bundler issues or runtime errors if treated as a value

Type import for the `spec` instance, providing TypeScript users with proper type annotations for their test specifications.

Demonstrates basic GET and POST requests, status code assertions, and JSON body matching using PactumJS with an ESM setup and environment variable for authentication.

import { spec } from 'pactum'; describe('HTTPBin API Tests', () => { it('should respond with a 418 status code (teapot)', async () => { await spec() .get('http://httpbin.org/status/418') .expectStatus(418); }); it('should save a new user via POST request', async () => { // In a real scenario, use process.env.AUTH_TOKEN or a secure method for credentials const authToken = process.env.TEST_AUTH_TOKEN ?? 'Basic aHR0cGJpbjpwYXNzd29yZA=='; await spec() .post('https://jsonplaceholder.typicode.com/users') .withHeaders('Authorization', authToken) .withJson({ name: 'John Doe', email: 'john.doe@example.com', username: 'johndoe' }) .expectStatus(201) // POST to /users typically returns 201 Created .expectJsonMatch({ name: 'John Doe', email: 'john.doe@example.com' }); }); });

Debug

Known issues

gotchaPactumJS is a testing library, not a test runner. It must be used in conjunction with a test runner like Mocha, Jest, or Cucumber. Failing to install and configure a test runner will result in no tests being executed.

fix

Install a test runner (e.g., `npm install --save-dev mocha`) and configure your `package.json` scripts to run tests (e.g., `"test": "mocha tests/**/*.js"`).

affects: >=1.0.0

gotchaAsynchronous PactumJS calls (e.g., `spec()`, `spec().toss()`) must be `await`-ed within `async` test functions. Forgetting `await` will cause tests to complete prematurely, potentially leading to false positives or 'timeout' errors in your test runner if it waits for the async operation.

fix

Ensure all PactumJS operations that return a Promise are prefixed with `await` and that their containing test function is marked `async` (e.g., `it('...', async () => { await spec()... })`).

affects: >=1.0.0

gotchaWhen asserting response headers using methods like `expectHeaderContains()` or `expectHeader()`, the header names are often case-sensitive and may require lowercase characters, depending on the server implementation. Forgetting this can lead to 'Header not found' errors.

fix

Always check the exact casing of the header in the actual API response (e.g., via a proxy or network inspector) or try using a common lowercase variant like `'content-type'`.

affects: >=1.0.0

gotchaContract testing with PactumJS typically requires the `pactumjs-flow-server` to manage and compare assumed and actual API behaviors. This server needs to be set up and running separately for contract test execution and reporting.

fix

Refer to the PactumJS documentation for setting up the `pactumjs-flow-server` (e.g., via Docker) and configuring your project to publish/consume flows and interactions.

affects: >=3.0.0

gotchaGlobal configurations (e.g., `pactum.settings.setBaseUrl()`, `pactum.settings.setDefaultHeaders()`) can inadvertently affect other tests if not reset or isolated properly. This can lead to test flakiness or unexpected side effects.

fix

Utilize test runner hooks (`beforeEach`, `afterEach`) to set up and tear down global configurations, or use localized settings within `spec()` chains where possible to ensure test isolation.

affects: >=1.0.0

Errors

Common errors & fixes

Timeout of 2000ms exceeded. For async tests and hooks, ensure "done()" is called or a Promise is returned.

An `async` test function containing PactumJS calls did not `await` all asynchronous operations, causing the test to exit before the HTTP request or assertion completed.

fix

Ensure all PactumJS methods (e.g., `spec()`, `spec().toss()`) are prefixed with `await` and the test function is marked `async`.

Error: Header 'Content-Type' not found in response.

The header name provided in the `expectHeader` or `expectHeaderContains` assertion does not exactly match the case of the header returned by the API.

fix

Check the exact casing of the header in the actual API response (e.g., via a proxy or network inspector) or try using a common lowercase variant like `'content-type'`.

TypeError: pactum.spec is not a function

Incorrect import statement. `spec` is a named export, not available directly on the `pactum` default import or as a property of a `require`'d module unless explicitly deconstructed.

fix

Use named import: `import { spec } from 'pactum'` (ESM) or object destructuring: `const { spec } = require('pactum')` (CommonJS).

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/pactumjs/pactum ↗

packagehttps://www.npmjs.com/package/pactum ↗

homepagehttps://pactumjs.github.io ↗