@s-ui/test-contract

sui-test-contract

Useful tooling for defining contract tests (based on Pact) that will generate contract documents. It will also allow us to publish such documents into a defined Pact Broker.

Dependencies

This package depends on the API mocking tool MSW. That means all the mocking requests should be handled by such tool, and the recommendation is to share the mocks along your whole app, so they should be placed in a unique folder named mocks in the root of your project.

Environment

These kind of contract test are intended to be executed in a server side environment with Mocha and Chai. It's recommended to use the package @s-ui/test for executing them.

Using the setup function

In order to start using the contract tests in your app, you'll need to execute the setupContractTests function passing the needed parameters. It will allow you to create the interactions, test them and finally it will generate the contract documents (in the path: contract/documents by default).

It's important to know that YOU'LL NEED TO EXECUTE THIS FUNCTION IN A TEST FILE (e.g.: consumerSpec.js)

Here you have a detailed example:

// `mocks/apples/responses.js`
export const applesResponse = [
  {color: 'red', type: 'Fuji'},
  {color: 'green', type: 'Granny Smith'}
]

// `mocks/apples/handlers.js`
import {rest} from 'msw'
import {applesResponse} from './responses.js'

export const applesRequestHandler = rest.get(
  'http://localhost:8181/apples',
  (req, res, ctx) => res(ctx.status(200), ctx.json(applesResponse))
)

// `contract/test/apples/consumerSpec.js`
import {expect} from 'chai'
import {FetcherFactory} from '@s-ui/domain'
import {setupContractTests} from '@s-ui/test-contract'
import {applesResponse} from '../../../../mocks/apples/responses.js'
import {applesRequestHandler} from '../../../../mocks/apples/handlers.js'

const fetcher = FetcherFactory.httpFetcher({config: {}})
const consumer = 'test-consumer'

setupContractTests({
  apiUrl: 'http://localhost:8181',
  consumer,
  fetcher,
  providers: {
    'test-provider': [
      {
        apiUrl: 'https://mydomain.com',
        endpoint: '/apples',
        description: 'A request for getting some apples',
        state: 'I have some apples',
        handler: applesRequestHandler,
        response: applesResponse
      }
    ]
  }
})

Setup options

Parameter	Required	Type	Default	Description
apiUrl	Yes	string		Complete URL where ALL the requests should be done
consumer	Yes	string		Name of the API consumer
providers	Yes	object		Object of providers containing an array of interactions (see Provider interaction options)
fetcher	Yes	Fetcher		Instance of a fetcher class (e.g. Axios)
defaultOptions	No	object		Default options for the requests
excludeHeaders	No	array	['x-powered-by', 'accept', 'user-agent', 'cookie']	Headers to be excluded in the generated contracts
contractsDir	No	string	./contract/documents	Path to the directory that will contain the generated contracts

Provider interaction options

Parameter	Required	Type	Default	Description
description	Yes	string		Description for the interaction
state	Yes	string		State to be matched by the provider
apiUrl	No	string		Api url for current endpoint request
endpoint	Yes	string		Endpoint to be added in the contract document
query	No	object		Query params if needed in the request
body	No	See possibilities for Fetch API Body		Body to be sent in the request
method	No	string	get	Request method
handler	Yes	Request handler		Request handler used in the contract test
options	No	object	defaultOptions (from the setup configuration)	Request options
response	Yes	any		Response to be validated in the contract test
addMatchingRules	No	boolean		Flag to add Pact matching rules to check contracts by value type

Publishing the contracts

When you have your contract documents generated (e.g.: contract/documents/test-consumer-test-provider-123456789.json), you'll need to publish them to the Pact Broker, the place where providers (API Backend) will validate their own tests against the contracts.

You just need to run the following command:

sui-test-contract publish --broker-url "https://my-contract-tests-broker.com"