To use PactumJS, install it as a development dependency. You should also install a test runner like Mocha, Jest, or Cucumber to execute your tests.

Alternatively, you can use the npx pactum-init command to scaffold a new project automatically.

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

# install a test runner to run pactum tests
npm install --save-dev mocha

or use the initializer

npx pactum-init

PactumJS uses a spec() builder pattern to construct HTTP requests and define expectations. You can chain methods like .get(), .post(), .withHeaders(), and .withJson() to build the request, and use .expectStatus() or other expectation methods to validate the response.

To execute the test in a Mocha environment, use the mocha command pointing to your test file.

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: 'bolt@swift.run'
    })
    .expectStatus(200);
});

PactumJS can act as a standalone mock server to simulate HTTP/HTTPS-based APIs. You define interactions using mock.addInteraction(), specifying the request (method and path) and the desired response (status and body). Finally, call mock.start(port) to begin listening for requests on the specified port.

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

You can control the logging behavior of PactumJS using environment variables. This is useful for CI/CD environments or when you want to change log verbosity without modifying code.

• PACTUM_LOG_LEVEL: Sets the minimum log level. Supported values are TRACE, DEBUG, INFO, WARN, ERROR, SILENT, and VERBOSE.
• PACTUM_DISABLE_LOG_COLORS: Set to true to disable colored output in the logs.

If you want to redirect PactumJS logs to your own logging framework (like Winston or Bunyan), you can provide a custom Logger object via setLogger. The object must implement the following methods, each accepting an array of messages:

• trace(messages: any[])
• debug(messages: any[])
• info(messages: any[])
• warn(messages: any[])
• error(messages: any[])

import { setLogger } from 'pactum';

setLogger({
  trace: (msgs) => console.log('[TRACE]', ...msgs),
  debug: (msgs) => console.log('[DEBUG]', ...msgs),
  info: (msgs) => console.log('[INFO]', ...msgs),
  warn: (msgs) => console.warn('[WARN]', ...msgs),
  error: (msgs) => console.error('[ERROR]', ...msgs),
});

Data templates allow you to define structured data patterns. Use stash.addDataTemplate to add templates as objects, arrays, or single key-value pairs. Retrieve templates using stash.getDataTemplate(path).

// Adding templates via object
stash.addDataTemplate({
  'User:NewUser': {
    'Name': 'Snow',
    'Age': 26,
    'Address': []
  }
});

// Adding templates via key-value pair
stash.addDataTemplate('USER:NEW', { name: 'john', age: 28 });

// Retrieving a template
const credentials = stash.getDataTemplate('CREDENTIALS');

The Logger plugin exposes several methods to emit logs at different severity levels. Logs are only emitted if the current log level is equal to or higher than the method's severity.

Available methods:

• trace(...msg)
• debug(...msg)
• info(...msg)
• warn(...msg)
• error(...msg)

Use flow(name: string) to return an instance of a Spec associated with a specific named flow. This is used to manage sequences of requests.

import { flow } from 'pactum';

const myFlow = flow('login-and-get-profile');

You can control the verbosity of PactumJS logs using setLogLevel. This is useful for reducing noise in CI environments or increasing detail during debugging.

Supported log levels are:

• 'VERBOSE'
• 'TRACE'
• 'DEBUG'
• 'INFO'
• 'WARN'
• 'ERROR'
• 'SILENT'

import { setLogLevel } from 'pactum';

setLogLevel('DEBUG');

Use these methods to retrieve the underlying keys used by the stash system:

• stash.getMapKey(key: string): string
• stash.getDataTemplate(path: string): object (Note: The interface also provides getFunctionKey(key: string): string)
• stash.getStoreKey(key: string): string