PactumJS

REST API Testing Tool for all levels in a Test Pyramid

TestingTesting framework
pactumjs/pactumpactumjs.github.iopactum

README

PactumJS


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.

- ⚡ 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
- Mock Server

Need Help


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

Installation


  1. ```shell
  2. # install pactum as a dev dependency
  3. npm install --save-dev pactum

  5. # install a test runner to run pactum tests
  6. # mocha / jest / cucumber
  7. npm install --save-dev mocha
  8. ```

or you can simply use

  1. ```bash
  2. npx pactum-init
  3. ```

----------

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 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.

  1. ```js
  2. const { spec } = require('pactum');

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

  10. it('should save a new user', async () => {
  11.   await spec()
  12.     .post('https://jsonplaceholder.typicode.com/users')
  13.     .withHeaders('Authorization', 'Basic xxxx')
  14.     .withJson({
  15.       name: 'bolt',
  16.       email: 'bolt@swift.run'
  17.     })
  18.     .expectStatus(200);
  19. });
  20. ```

  1. ```shell
  2. # mocha is a test framework to execute test cases
  3. mocha /path/to/test
  4. ```

Using Cucumber


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

  1. ```gherkin
  2. Scenario: Check Tea Pot
  3.   Given I make a GET request to "http://httpbin.org/status/418"
  4.   When I receive a response
  5.   Then response should have a status 418
  6. ```

  1. ```js
  2. // steps.js
  3. const pactum = require('pactum');
  4. const { Given, When, Then, Before } = require('@cucumber/cucumber');

  6. let spec = pactum.spec();

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

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

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

  18. Then('response should have a status {int}', async function (code) {
  19.   spec.response().should.have.status(code);
  20. });
  21. ```

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.

  1. ```js
  2. const { mock } = require('pactum');

  4. mock.addInteraction({
  5.   request: {
  6.     method: 'GET',
  7.     path: '/api/projects'
  8.   },
  9.   response: {
  10.     status: 200,
  11.     body: [
  12.       {
  13.         id: 'project-id',
  14.         name: 'project-name'
  15.       }
  16.     ]
  17.   }
  18. });

  20. mock.start(3000);
  21. ```

----------

Notes


Inspired from frisby and pact.

Support


Like this project! Star it on Github and follow on Twitter. 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.