🤝 PactumJS - introduction

19/02/2022

Introduction

One of the most popular tools for API testing is Postman 🚀 📮, and it is certainly a good choice when looking for a solution with its own GUI. An alternative to such a solution is tools that allow writing tests using Python (Requests) or JavaScript (PactumJS / SuperTest / Frisby.js / Chakram). Among them, PactumJS seems to be the most promising (see comparison -> API Testing Tools in JavaScript), and it is this library that I have focused my attention on.

Useful free websites for API testing:

Environment Setup

Prerequisite: node.js 📂 is installed on the local machine.

Installing PactumJS

npm install pactum

Installing the chosen test runner, either Mocha or Cucumber

npm install mocha
# or
npm install @cucumber/cucumber

Creating a Test

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

it("should yield HTTP status code 200", async () => {
    await spec()
        .get("http://jsonplaceholder.typicode.com/users/1")
        .expectStatus(200);
});

Running the Test in the Terminal

npx mocha pactumJSTest.js

Jest can also be used as the test runner.

Installing Jest:

npm install jest

basdijkstra/api-testing-js-pactum (Bas Dijkstra)

Preparing a POST-based test - Creating a new post (example source: )

// userdata.test.js
const pactum = require('pactum');

describe('Posting a new post item', () => {
    test('should yield HTTP status code 201', async () => {
        let new_post = {
            "title": "My awesome new post title",
            "body": "My awesome new post body",
            "userId": 1
        }

        await pactum.spec()
            .post('http://jsonplaceholder.typicode.com/posts')
            .withJson(new_post)
            .expectStatus(201)
    });
});

Running the test:

npx jest

Request Creation Methods

pactum.spec() - The basic method for making requests using PactumJS.

The basic methods for creating requests (GET/POST/PUT/DELETE/PATCH) are used by combining them with the main pactum.spec() method.

await pactum.spec().get('http://domain.com/user');
await pactum.spec().post('http://domain.com/user');
await pactum.spec().put('http://domain.com/user');
await pactum.spec().patch('http://domain.com/user');
await pactum.spec().delete('http://domain.com/user');

Additional Parameters

To pass additional parameters to the request, you can use the dedicated methods separately or chain them together.

Method	Description
`withMethod`	Sets the request method
`withPath`	Sets the request path
`withPathParams`	Sets the path parameters
`withQueryParams`	Sets the query parameters
`withHeaders`	Sets the request headers
`withCookies`	Sets the request cookies
`withBody`	Sets the request body
`withJson`	Sets the request body as JSON
`withAuth`	Sets the request authentication

Full list: pactumjs.github.io/#/request-making?id=spec

Path Params (example source: pactumjs.github.io)

await pactum.spec()
  .get('/api/project/{project}/repo/{repo}')  // dynamic url
  .withPathParams('project', 'project-name')  // key-value pair
  .withPathParams({
    'repo': 'repo-name'                       // object
  })
  .expectStatus(200);

// The above would result in a URL like - /api/project/project-name/repo/repo-name

Authentication (example source: pactumjs.github.io)

await pactum.spec()
  .get('some-url')
  .withAuth('my-username', 'super-secret-password')
  .expectStatus(200);

Request Validation

Command	Alias	Description
`expect`	-	basic assertion
`expectStatus`	status	checks the HTTP status
`expectHeader`	header	checks the HTTP header / key + value
`expectHeaderContains`	headerContains	checks the HTTP header / key + partial value
`expectBody`	body	checks the exact body content
`expectBodyContains`	-	bodyContains
`expectJson`	json	checks the exact JSON object content
`expectError`	error	checks for network errors/response errors

Full list: pactumjs.github.io/#/response-validation

Status & Headers & Response Time Source: pactumjs.github.io

await pactum.spec()
  .get('https://jsonplaceholder.typicode.com/posts/1')
  .expectStatus(200)
  .expectHeader('content-type', 'application/json; charset=utf-8')
  .expectHeader('connection', /\w+/)
  .expectHeaderContains('content-type', 'application/json')
  .expectResponseTime(100);

expectBody Source: pactumjs.github.io

await pactum.spec()
  .get('api/health')
  .expectStatus(200)
  .expectBody('OK');

Sources:

GH - pactumjs/pactum

pactumjs.github.io/pactum-slides/1

pactumjs/pactum-examples

https://pactumjs.github.io/#/

Writing API tests in JavaScript with Pactum by Bas Dijkstra

basdijkstra/api-testing-js-pactum (Bas Dijkstra)

API Integration Testing Made Easy

REST API test automation with PactumJS

JavaScript: REST API Automation with PactumJS — Basics

API Testing Tools in JavaScript

pactumJSjsapi testing

Author@kostyrko

Software Quality Assurance | Test Automation

GitHub