Example NodeJS/React Consumer - Cypress (BYO Adapter)

Source Code

https://github.com/pactflow/example-bi-directional-consumer-cypress

: https://github.com/pactflow/example-bi-directional-consumer-cypress/actions/workflows/build.yml

: https://testdemo.pactflow.io/pacticipants/pactflow-example-bi-directional-provider-readyapi/branches/master/latest-version/can-i-deploy/to-environment/production/badge

Overview of Example

This is an example of a React "Product" API consumer that uses Cypress, pact-cypress-adapter, API Hub for Contract Testing and GitHub Actions to generate and publish Pact consumer contracts.

It performs pre-deployment cross-compatibility checks to ensure that it is compatible with specified providers using the Bi-Directional contract capability of API Hub for Contract Testing.

See the full API Hub for Contract Testing Bi-Directional Workshop for which this can be substituted in as the "consumer".

Key points with Cypress

It:

It a React app implementing a "Product" website created with Create React App
It utilises Cypress to functionally test the website
It utilises pact-cypress-adapter to transform cypress mocks into Pact consumer contracts.

Overview of Part of Bi-Directional Contract Testing Flow

In the following diagram, You can see how the consumer testing process works - it's the same as the current Pact process.

When we call "can-i-deploy" the cross-contract validation process kicks off on API Hub for Contract Testing, to ensure any consumer consumes a valid subset of the OAS for the provider.

The project uses a Makefile to simulate a very simple build pipeline with two stages - test and deploy.

When you run the CI pipeline (see below for doing this), the pipeline should perform the following activities (simplified):

Test
- Run tests (including the pact tests that generate the contract)
- Publish pacts, tagging the consumer version with the name of the current branch
- Check if we are safe to deploy to Production with can-i-deploy (ie. has the cross-contract validation has been successfully performed)
Deploy (only from <main|master>)
- Deploy app to Production
- Record the Production deployment in the Pact Broker

Compatible with Providers

This project is currently compatible with the following provider(s):

See Environment variables on how to set these up.

Pre-requisites

Software:

Tools listed here
A pactflow.io account with an valid API token

Environment variables

To be able to run some of the commands locally, you will need to export the following environment variables into your shell:

PACT_BROKER_TOKEN: a valid API token for API Hub for Contract Testing
PACT_BROKER_BASE_URL: a fully qualified domain name with protocol to your pact broker e.g., http:// https://testdemo.pactflow.io

Set PACT_PROVIDER to one of the following:

PACT_PROVIDER=pactflow-example-bi-directional-provider-dredd: Dredd - (https://github.com/pactflow/example-bi-directional-provider-dredd)
PACT_PROVIDER=pactflow-example-bi-directional-provider-postman: Postman - (https://github.com/pactflow/example-bi-directional-provider-postman)
PACT_PROVIDER=pactflow-example-bi-directional-provider-restassured: Rest Assured - (https://github.com/pactflow/example-bi-directional-provider-restassured)

Usage

Steps

NOTE: Cypress tests are located in ./cypress/integration. See below for how to start cypress test, generate consumer contract and publish contract to pactflow.

make install - install project dependencies

Run each step separately

make test_and_publish - tests the provider and publishes provider contracts to API Hub for Contract Testing
This will perform the following 2 calls
- make test
- make publish_provider_contract
make can_i_deploy - runs can-i-deploy to check if its safe to deploy the provider
make deploy - deploys the app and records deployment

or run the whole lot in one go

make ci - run the CI process, but locally (uses Docker by default)

Installing alternate pact CLI tools.

If you don't have docker, you can use one of the ruby tools. The standalone, doesn't require that you install Ruby on your host machine.

make install-pact-ruby-cli - installs the pact ruby CLI tool
make install-pact-ruby-standalone - installs the pact standalone CLI depending on your platform
make uninstall-pact-ruby-standalone - uninstalls the pact standalone CLI

Using alternate pact CLI tools.

PACT_TOOL=docker make ci - run the CI process, using the pact Docker CLI tool
PACT_TOOL=ruby_standalone make ci - run the CI process, using the pact standalone CLI tool
PACT_TOOL=ruby_cli make ci - run the CI process, using the pact ruby CLI tool

How to use Cypress

Spin up the ui project by running npm run start
Define your pact provider and consumer name at cypress.json as cypress environment variables
You can stub your network request and response with cy.intercept, and record network call to a consumer driven contract with cy.usePactWait. Each request you want to add to the contract must call this method.
npm run cypress:headless:chrome - this will run cypress e2e test in headless mode, and write stubbed network calls a pact file
npm run cypress:run - this will run cypress e2e test with browser ui

OS/Platform specific considerations

The Makefile has been configured to run on Unix/Windows and MacOS based systems, and tested against Github Actions

They can be run locally on Unix/Windows and MacOS, or on Windows via WSL2 or a shell with bash.

Caveats

OAS considerations

Other examples of how to do this form of testing

Found an issue?

Reach out via a GitHub Issue, or reach us over in the Pact foundation Slack.

In this section: