Skip to main content

Configuring ContractCase

ContractCase accepts configuration parameters in the defineContract and verifyContract DSL functions.

This config can be overridden per-test or per-verification, by passing an optional partial config object as the last parameter to runInteraction, runRejectingInteraction, or runVerification. This is useful for overriding specifics for different tests (eg, for increasing the log level on one specific test).

There are multiple places you can supply configuration. In general, the closer an option is to the runInteraction interaction, the higher precedence it has. Here are the places configuration can be specified, where the top of the list has the most precedence.

  1. Options specified in the test run (runInteraction, runRejectingInteraction, or runVerification).
  2. Options specified at contract creation time (defineContract or verifyContract)
  3. Environment variables (any option that can be a string or a boolean can be set with the environment variable CASE_${optionName}, for example export CASE_logLevel=debug or export CASE_publish=false)
  4. Default options

Required options​

consumerName [string]​

Default: None

This is the name of the service that defined (or is defining) the contract. Required by defineContract, not required by verifyContract. If you specify it during verifyContract, then only contracts from that consuming service will be verified.

note

It is an error to specify a different value of consumerName in defineContract and runInteraction / runRejectingInteraction.

providerName [string]​

Default: None

This is the name of the service that will verify the contract (or is verifying the contract). Required by both defineContract and verifyContract

During verifyContract, the provider name must match the name that was used when the consumer defined the contract.

Reporting options​

logLevel ["none" | "error" | "warn" | "debug" | "maintainerDebug"]​

Default: "warn"

Controls the level of logging to standard out that ContractCase does during your tests. Each setting also includes the logs from the level above it - for example, setting it to debug will also print any warnings and errors.

  • "none" - Print no logs (although results may still be printed - see printResults)
  • "error" - Something has gone wrong during the execution of the test framework
  • "warn" - It seems likely that there is a misconfiguration. For best-practice use of ContractCase, there should be no warnings.
  • "debug" - Information to help users find out what is happening during their tests. Use this if you want to know why your tests are failing.
  • "maintainerDebug" - debugging information for ContractCase maintainers. Most users probably won't need these, but it's helpful to provide logs at this level in a bug report.
  • "deepMaintainerDebug" - like maintainerDebug but with much more verbose logging of matching and requests.
WARNING

Both maintainer debugging levels might print user secrets. Additionally, debug does not do this by default, but it does log the contents of your contract. Please make sure you sanitise any output from debug and below before posting publicly (such as in a bug report).

printResults [boolean]​

Default: true

Controls whether or not ContractCase should print the test results to standard out during a run. Set to false if you prefer a quiet test run.

Contract output options​

contractDir [string]​

Default: ${WORKING_DIRECTORY}/case-contracts/

The directory where the contracts will be written.

ContractCase stores contracts in subdirectories for each provider, so that it's easy to find all contracts for a particular provider.

Additionally, the filename is generated by a hash of the contract contents, meaning that no new files are written if your contract hasn't changed. This makes it easy to store contracts in the repository. The format is:

${CONTRACT_DIR}/${PROVIDER_NAME}/${CONSUMER_NAME}-${HASH}.case.json

We recommend using contractDir

contractFilename [string]​

Default: Not set.

The filename where the contract will be written. If you provide this, contractDir is ignored.

This is provided mostly for debugging purposes, or if you have a custom workflow. It is generally recommended to use contractDir instead.

When contractFilename is set, ContractCase will not overwrite an existing file.

Broker options​

These options control how ContractCase contacts the contract broker.

brokerBaseUrl [string]​

Default: None

The base URL for the contract broker. Required if publish is set to true, required in CI if publish is set to ONLY_IN_CI.

brokerBasicAuth [{ username: string, password: string }]​

Default: None

The basic auth to use when contacting the contract broker. If you're using a brokerCiAccessToken, this option is ignored. Expects an object with the following structure:

{
  /**
   * The username for basic auth
   */
  username: string;
  /**
   * The password for basic auth
   */
  password: string;
}

brokerCiAccessToken [string]​

Default: None

The access token to use for the contract broker. To publish contracts and verification results, the token must have CI scope. Additionally, your broker must support access tokens (currently, pactflow is the only broker that supports access tokens).

If this is specified along with brokerBasicAuth, the basic auth is ignored.

publish [true | false | "ONLY_IN_CI" | "NEVER" | "ALWAYS"]​

Default: "ONLY_IN_CI"

Whether to publish contracts or verification results to the broker. When set to:

  • "ONLY_IN_CI" - ContractCase determines whether or not it is running inside a continuous integration build process, according to ci-info.
  • "NEVER" | false - ContractCase does not publish any contracts or verification results to the broker.
  • "ALWAYS" | true - ContractCase publishes contracts and verification results to the broker.

If publish is set, you must provide credentials and brokerBaseUrl. See above.

General configuration​

autoVersionFrom ["TAG" | "GIT_SHA"]​

Default: "TAG"

How to determine the version for the service under test. It's important that each change to your service has a unique version, so ContractCase uses your git repository to determine the version.

  • TAG (default) This setting will generate a human-friendly version from using absolute-version. Most useful if use
  • GIT_SHA get the version from the full git sha

If there is no git repository, versioning will fail. Support for non-git repositories will be added in the future. If this is something you need prioritised, please open an issue.

stateHandlers [various, depending on language]​

State setup and teardown handlers for any states this test requires. How these are specified depends on the language you're using, see the relevant contract definition and contract verification guides for details.

triggers / trigger / testResponse / testErrorResponse [various, depending on language]​

Defines the trigger and test functions for multiple interactions under test.

  • triggers: Used to define multiple trigger and test functions, useful during verification that needs triggers.
  • trigger: Defines a single trigger. This is only valid on individual interactions
  • testResponse / testErrorResponse: Used to verify the response object from the trigger

See the relevant contract definition and contract verification guides for language-specific examples of triggers and test response functions.

Internal configuration options​

These options modify the behaviour of the contract testing engine. In general, you should not need to change these from the default, unless your use case is unusual.

Most users probably won't need these, but they're documented here in case you are extending ContractCase or building tools on top of it.

If you're using these, it might be worth opening an issue to discuss your use-case and whether it should be better supported.

throwOnFail [boolean];​

Default: true during contract definition, false during contract verification.

Whether or not the test should throw an error if the matching fails.

During contract definition, the default is true to make sure that the test suite fails. This is because a failure during contract definition means that the service either didn't send the request that was defined in the test, or didn't understand the response.

During contract verification, the default is false, because a contract violation doesn't mean that the service doesn't work - it means that it is not compatible with the consumer that wrote the contract. To get deployment confidence from ContractCase, you will need to use Can-I-Deploy checks - see the section on deployment checks

NOTE

Any configuration errors will still fail the suite regardless of this setting. This includes exceptions thrown during trigger functions, but does not include exceptions thrown by testResponse / testErrorResponse functions.

testRunId [string]​

Default: None (or provided by your test wrapper, eg Jest)

A unique identifier for this test. Mostly useful for debugging.