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

NPM:

1npm i -D @pactflow/pact-cypress-adapter

yarn:

1yarn add -D @pactflow/pact-cypress-adapter

Setup for Cypress 10

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

1const pactCypressPlugin = require('@pactflow/pact-cypress-adapter/dist/plugin')
2const fs = require('fs')
3
4module.exports = (on, config) => {
5  pactCypressPlugin(on, config, fs)
6}

Finally, update cypress/support/e2e.js file to include cypress-pact commands via adding:

1import '@pactflow/pact-cypress-adapter'

Setup for Cypress 9.x and below

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

1const pactCypressPlugin = require('@pactflow/pact-cypress-adapter/dist/plugin')
2const fs = require('fs')
3
4module.exports = (on, config) => {
5  pactCypressPlugin(on, config, fs)
6}

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

1import '@pactflow/pact-cypress-adapter'

Configuration

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

Add more headers to blocklist for Cypress 10

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

1{
2    ...otherCypressConfig,
3    "env": {
4        "headersBlocklist": ["ignore-me-globally"]
5    }
6}

Add more headers to blocklist for Cypress 9.x and below

To exclude other headers in your pact, add them as a list of strings in cypress.json under key env.headersBlocklist. Eg. in your cypress.json

1{
2    ...otherCypressConfig,
3    "env": {
4        "headersBlocklist": ["ignore-me-globally"]
5    }
6}

Note: Header blocklist can be set up at test level. Check command cy.setupPactHeaderBlocklist

Ignore cypress auto-generated header blocklist

To stop cypress auto-generated HTTP headers being omitted by the plugin, set env.ignoreDefaultBlocklist in your cypress.json. Eg. in your cypress.json

1{
2    ...otherCypressConfig,
3    "env": {
4        "headersBlocklist": ["ignore-me-globally"],
5        "ignoreDefaultBlocklist": true
6
7    }
8}

Commands

cy.setupPact(consumerName:string, providerName: string)

Configure your consumer and provider name

Example

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

cy.usePactWait([alias] | alias)

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

Example

1before(() => {
2    cy.setupPact('ui-consumer', 'api-provider')
3    cy.intercept('GET', '/users').as('getAllUsers')
4})
5
6//... cypress test
7
8after(() => {
9    cy.usePactWait(['getAllUsers'])
10})
11

cy.setupPactHeaderBlocklist([headers])

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

Example

1before(() => {
2    cy.setupPact('ui-consumer', 'api-provider')
3    cy.intercept('GET', '/users', headers: {'ignore-me': 'ignore me please'}).as('getAllUsers')
4    cy.setupPactHeaderBlocklist(['ignore-me'])
5})
6
7//... cypress test
8
9after(() => {
10    cy.usePactWait(['getAllUsers'])
11})

cy.usePactRequest(option, alias) and cy.usePactGet([alias] | alias)

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

1
2before(() => {
3    cy.setupPact('ui-consumer', 'api-provider')
4    cy.usePactRequest(
5      {
6        method: 'GET',
7        url: '/users',
8      },
9      'getAllUsers'
10    )
11})
12
13//... cypress test
14
15after(() => {
16    cy.usePactGet(['getAllUsers'])
17})
18

Example Project

Check out simple react app example projects at /example/todo-example. Example contains examples for Cypress 10.x and Cypress 9.x.