DOCSEARCHbyAlgolia
Submit Docs

PactumJS Documentation

website·Indexed 29 days ago

https://pactumjs.github.io/

A Node.js API testing library available as an npm package. It provides a builder-style and BDD-style API for REST and GraphQL testing, featuring a built-in mock server, data management, and support for end-to-end, integration, contract, and fuzz testing.

Tokens
86.5K
Snippets
552
Records
657
Agent score
73%

What's inside PactumJS

  1. Overview of PactumJS Contract Testing

    PactumJS implements a bi-directional contract testing framework that combines consumer-driven and provider-driven patterns. It allows developers to convert existing unit or component tests into contract tests. The process involves two primary steps: the Provider publishes 'Actual Behavior' and the Consumer publishes 'Assumed Behavior'. These are then compared via the PactumJS Flow Server to determine compatibility.

  2. Overview of Pactum matching mechanisms

    Pactum provides matching mechanisms to handle dynamic data (like timestamps and generated IDs) in request and response validation. Matching is primarily used in three scenarios:

    1. Mock server interactions (request matching).
    2. Contract testing (both request and response matching).
    3. Response validation using expectJsonMatch and expectJsonMatchStrict.

  3. Overview of PactumJS for REST API Testing

    PactumJS is a free and open-source REST API automation testing tool designed for developers, QA engineers, and SDETs. It is language-agnostic regarding the backend server and is specifically suited for micro-services architectures. It supports multiple testing levels within the Test Pyramid, including:

    • API Testing
    • Component Testing
    • Contract Testing
    • Integration Testing
    • E2E Testing
    • Mock Server implementation

  4. Overview of PactumJS for REST API Automation

    PactumJS is a free and open-source REST API automation testing tool designed for developers, QA engineers, and SDETs. It is language-agnostic regarding the backend server, meaning it can test APIs regardless of the programming language used to build them. It is particularly suited for micro-services architectures and supports multiple testing levels within the Test Pyramid, including:

    • API Testing
    • Component Testing
    • Contract Testing
    • Integration Testing
    • E2E Testing
    • Mock Server implementation

  5. Overview of PactumJS Contract Testing

    PactumJS implements a bi-directional contract testing framework (a mix of consumer-driven and provider-driven). It converts existing unit or component tests into contract tests by capturing interactions between a Consumer (the application requesting data) and a Provider (the service providing the API). The process involves publishing 'Actual Behavior' from the provider and 'Assumed Behavior' from the consumer to the PactumJS Flow Server, which then compares them to determine compatibility.

  6. Define mock server behavior using Interactions

    An interaction in PactumJS defines how the mock server should behave when it receives a specific request. It consists of request matching criteria (to identify the incoming call) and response details (to determine what the server returns).

  7. Define mock server behavior using Interactions

    An interaction in PactumJS defines how the mock server should match an incoming request and what response it should return. It allows for strict matching, request validation, custom response logic, and data storage from requests.

  8. Understand PactumJS HTTP client and supported API types

    PactumJS uses the phin.js library under the hood for handling http/https requests. It currently supports REST and GraphQL API testing over http(s).

  9. PactumJS supported API types and HTTP client

    PactumJS supports REST and GraphQL API testing over http(s). It uses the phin.js library under the hood to handle http/https requests.

  10. Perform snapshot testing with expectJsonSnapshot

    Snapshot testing in PactumJS compares an API response body against a reference snapshot file stored in the .pactum/snapshots directory. If the test is run for the first time, Pactum saves the response body as a reference. In subsequent runs, the test fails if the actual response differs from the reference file.

    Crucially, every snapshot requires a unique name. This name can be provided via the .name() method in the spec chain or as the first argument to expectJsonSnapshot().

    Important Considerations:

    • Snapshot files must be committed to version control to maintain a consistent reference across environments.
    • For responses containing dynamic data (e.g., IDs, timestamps), use matchers to prevent tests from failing on every run.

  11. Use Data Templates to reuse request payloads

    Data Templates provide a standard format for a resource that can be reused across multiple tests. When a template is referenced, PactumJS replaces the current JSON object with the template's value. Templates can also reference other templates, though circular dependencies should be avoided.
    const { stash, spec } = require('pactum');

// Define a template
stash.addDataTemplate({
  'User': {
    "name": "morpheus",
    "job": "leader"
  }
});

// Use the template in a request
await spec()
  .post('https://reqres.in/api/users')
  .withJson({
    '@DATA:TEMPLATE@': 'User',
  });

  12. Retry an HTTP request in PactumJS

    The retry() method allows you to repeat an HTTP request until certain conditions are met. It can be used with simple counts, delays, or complex strategies based on response status codes or custom handler functions.
    // Basic retry on expectations
await spec()
  .get('/api/users')
  .expectStatus(200)
  .retry();