Pact Cypress Adapter

Generate Pact contracts from your existing Cypress tests.

Accelerate your entry into contract testing with the Cypress development experience you know and love. — With Pact Cypress Adapter you can get the extra layer of testing safety, easily using existing mocks you’ve created with Cypress.

Read our blog post to find out more, otherwise dive-right in.

Installation

Use your favourite Node package manager:

npm i -D @pactflow/pact-cypress-adapter
yarn add -D @pactflow/pact-cypress-adapter
pnpm add -D @pactflow/pact-cypress-adapter

Setup

Configure the Pact plugin in your cypress.config.{js,ts} file using the setupNodeEvents function:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      const pactCypressPlugin = require('@pactflow/pact-cypress-adapter/dist/plugin')
      const fs = require('fs')
      pactCypressPlugin(on, config, fs)
      return config
    }
  }
})

Then, update your cypress/support/e2e.js file to include the Pact Cypress commands:

import '@pactflow/pact-cypress-adapter'

Legacy Setup (Cypress 9.x and below)

[!NOTE]

This setup is for legacy Cypress versions. If you're using a recent version of Cypress, use the setup above.

Setup your cypress plugin at cypress/plugins/index.js:

const pactCypressPlugin = require('@pactflow/pact-cypress-adapter/dist/plugin')
const fs = require('fs')

module.exports = (on, config) => {
  pactCypressPlugin(on, config, fs)
}

Finally, update cypress/support/index.js file to include cypress-pact commands:

import '@pactflow/pact-cypress-adapter'

Configuration

By default, this plugin omits most Cypress auto-generated HTTP headers.

Add more headers to blocklist

To exclude other headers in your pact, add them as a list of strings in your cypress.config.{js,ts} file under the env.headersBlocklist key:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  env: {
    headersBlocklist: ['ignore-me-globally']
  },
  e2e: {
    setupNodeEvents(on, config) {
      // ... plugin setup
    }
  }
})

Note: Header blocklist can also be set up at test level. See cy.setupPactHeaderBlocklist

Ignore cypress auto-generated header blocklist

To stop Cypress auto-generated HTTP headers from being omitted by the plugin, set env.ignoreDefaultBlocklist to true:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  env: {
    headersBlocklist: ['ignore-me-globally'],
    ignoreDefaultBlocklist: true
  },
  e2e: {
    setupNodeEvents(on, config) {
      // ... plugin setup
    }
  }
})

Legacy Configuration (Cypress 9.x and below)

To exclude headers in your pact with legacy Cypress versions, add them as a list of strings in cypress.json:

{
    ...otherCypressConfig,
    "env": {
        "headersBlocklist": ["ignore-me-globally"],
        "ignoreDefaultBlocklist": true
    }
}

Commands

cy.setupPact

Configure your consumer and provider name

before(() => {
  cy.setupPact('ui-consumer', 'api-provider')
})

cy.usePactWait

Listen to aliased cy.intercept network call(s), record network request and response to a pact file. Usage and example about cy.intercept

before(() => {
  cy.setupPact('ui-consumer', 'api-provider')
  cy.intercept('GET', '/users').as('getAllUsers')
})

//... cypress test

after(() => {
  cy.usePactWait(['getAllUsers'])
})

cy.setupPactHeaderBlocklist

Add a list of headers that will be excluded in a pact at test case level

before(() => {
    cy.setupPact('ui-consumer', 'api-provider')
    cy.intercept('GET', '/users', headers: {'ignore-me': 'ignore me please'}).as('getAllUsers')
    cy.setupPactHeaderBlocklist(['ignore-me'])
})

//... cypress test

after(() => {
    cy.usePactWait(['getAllUsers'])
})

cy.usePactRequest and cy.usePactGet

Use cy.usePactRequest to initiate network calls and use cy.usePactGet to record network request and response to a pact file.

Convenience wrapper for cy.request(options).as(alias)

• Accepts a valid Cypress request options argument Cypress request options argument

Example

before(() => {
  cy.setupPact('ui-consumer', 'api-provider')
  cy.usePactRequest(
    {
      method: 'GET',
      url: '/users'
    },
    'getAllUsers'
  )
})

//... cypress test

after(() => {
  cy.usePactGet(['getAllUsers'])
})

Example Project

Check out a comprehensive React app example demonstrating Pact Cypress Adapter at example/todo-example/.

The example showcases:

• Modern Cypress configuration using cypress.config.js
• Two testing patterns: cy.intercept() for mocked responses and cy.usePactRequest() for real API calls
• Custom commands to reduce boilerplate
• Best practices for test isolation and contract testing