Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/pactflow/example-bi-directional-provider-dredd

bi-directional contracts provider example with OAS, using a BYO testing tool (Dredd)
https://github.com/pactflow/example-bi-directional-provider-dredd

example

Last synced: 10 months ago
JSON representation

bi-directional contracts provider example with OAS, using a BYO testing tool (Dredd)

Awesome Lists containing this project

README 

          
# Example NodeJS Provider - Dredd



[![Build Status](https://github.com/pactflow/example-bi-directional-provider-dredd/actions/workflows/build.yml/badge.svg)](https://github.com/pactflow/example-bi-directional-provider-dredd/actions)



[![Can I deploy Status](https://testdemo.pactflow.io/pacticipants/pactflow-example-bi-directional-provider-dredd/branches/master/latest-version/can-i-deploy/to-environment/production/badge)](https://testdemo.pactflow.io/pacticipants/pactflow-example-bi-directional-provider-dredd/branches/master/latest-version/can-i-deploy/to-environment/production/badge)



- [Example NodeJS Provider - Dredd](#example-nodejs-provider---dredd)

  - [Overview of Example](#overview-of-example)

    - [Key points](#key-points)

  - [Overview of Part of Bi-Directional Contract Testing Flow](#overview-of-part-of-bi-directional-contract-testing-flow)

  - [Compatibile with Consumers](#compatibile-with-consumers)

  - [Pre-requisites](#pre-requisites)

    - [Environment variables](#environment-variables)

  - [Usage](#usage)

    - [Steps](#steps)

  - [OS/Platform specific considerations](#osplatform-specific-considerations)

    - [Windows](#windows)

  - [Caveats](#caveats)

  - [Related topics / posts / discussions](#related-topics--posts--discussions)

  - [Other examples of how to do this form of testing](#other-examples-of-how-to-do-this-form-of-testing)

  - [Found an issue?](#found-an-issue)



## Overview of Example



This is an example of a NodeJS "Product" API Provider that uses Dredd, Pact, [PactFlow](https://pactflow.io) and GitHub Actions to generate and publish Pact provider contracts.



It performs pre-deployment cross-compatability checks to ensure that it is compatible with specified consumers using the Bi-Directional contract capability of PactFlow.



See the full [PactFlow Bi-Directional Workshop](https://docs.pactflow.io/docs/workshops/bi-directional-contract-testing) for which this can be substituted in as the "provider".



### Key points



It:



- Is an API written in Express JS

- Has OAS 3.0 spec documenting the API

- Uses Dredd for API testing to check spec compliance



What is uploaded to PactFlow is an OpenAPI specification that represents what you actually tested with Dredd, to give us confidence it is compatible with a Pact consumer.



## Overview of Part of Bi-Directional Contract Testing Flow



In the following diagram, you can see how the provider testing process works.



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



![Provider Test](docs/provider-scope.png "Provider Test")



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 to check spec compliance with openAPI spec

  - Publish provider contract (openAPI spec + results) to PactFlow

  - 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 master)

  - Deploy app to Production

  - Record the Production deployment in the Pact Broker



![Provider Pipeline](docs/provider-pipeline.png "Provider Pipeline")



## Compatibile with Consumers



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



- [pactflow-example-bi-directional-consumer-nock](https://github.com/pactflow/example-bi-directional-consumer-nock)

- [pactflow-example-bi-directional-consumer-msw](https://github.com/pactflow/example-bi-directional-consumer-msw)

- [pactflow-example-bi-directional-consumer-wiremock](https://github.com/pactflow/example-bi-directional-consumer-wiremock)

- [pactflow-example-bi-directional-consumer-mountebank](https://github.com/pactflow/example-bi-directional-consumer-mountebank)



See [Environment variables](#environment-variables) on how to set these up



## Pre-requisites



**Software**:



- Tools listed at: https://docs.pactflow.io/docs/workshops/ci-cd/set-up-ci/prerequisites/

- A pactflow.io account with an valid [API token](https://docs.pactflow.io/docs/getting-started/#configuring-your-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](https://docs.pactflow.io/docs/getting-started/#configuring-your-api-token) for PactFlow

- `PACT_BROKER_BASE_URL`: a fully qualified domain name with protocol to your pact broker e.g. 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



- `make test` - run the tests locally

- `make fake_ci` - run the CI process, but locally



## OS/Platform specific considerations



The makefile is configured to run on Unix based systems such as you would find in most common CI/CD pipelines.



They can be run locally on Unix/Mac, or on Windows via [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install).



### Windows



You can still try this example locally on Windows using powershell and running commands manually.



  Click to see windows specific instructions here



These will be the same commands that are used in the makefile with a few manual tweaks.



1. Make sure you have set all of the environment variables, in powershell they can be set like so.



   ```

    $env:BRANCH="main"

   ```



1. Now that the Swagger doc is generated and verified the contract can be published to PactFlow. The easiest way to do this via windows is using our standalone tools. See [here](https://docs.pactflow.io/docs/bi-directional-contract-testing/contracts/oas#publishing-the-provider-contract--results-to-pactflow) for cross platform instructions.



1. Check can-i-deploy to see if your provider is compatible with your pact.



   ```

   docker run --rm -v : -e PACT_BROKER_BASE_URL -e PACT_BROKER_TOKEN pactfoundation/pact-cli  broker can-i-deploy --pacticipant pactflow-example-bi-directional-consumer-dotnet --version $env:VERSION --to-environment production  --retry-while-unknown 0 --retry-interval 10

   ```



1. Have a look at what other commands are available in the Makefile. All of them can be ran locally from Powershell by changing the windows paths to UNIX and replacing the environment variable references. Any variable referenced as `${VARIABLE}` can be changed to `$env:VARIABLE` to reference environment variables in Powershell.



## Caveats



- [OAS considerations](https://docs.pactflow.io/docs/bi-directional-contract-testing/contracts/oas#considerations)

- you are responsible for ensuring sufficient OAS coverage. To highlight this point, in our example, we do _not_ test the 404 case on the provider, but the consumer has a pact for it and it's tests still pass! _NOTE: We plan to address this problem in the future_

- _implementing_ a spec is not the same as being _compatible_ with a spec. Most tools only tell you that what you’re doing is _not incompatible_ with the spec. _NOTE: We plan to address this problem in the future_



## Related topics / posts / discussions



- [Consumer Side Bi-Directional Contract Testing Guide](https://docs.pactflow.io/docs/bi-directional-contract-testing/consumer)

- [Provider Side Bi-Directional Contract Testing Guide](https://docs.pactflow.io/docs/bi-directional-contract-testing/provider)



## Other examples of how to do this form of testing



- TBC



## Found an issue?



Reach out via a GitHub Issue, or reach us over in the [Pact foundation Slack](https://slack.pact.io)