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 runExample, runRejectingExample, or runVerification. This is useful for overriding specifics for different tests (eg, for increasing the log level on one specific test).

You can view the options as a filter - if an option is not specified in the test run, it will look to the next layer. Here are the layers, from most to least important:

  1. Options specified in the test run (runExample, runRejectingExample, 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 runExample / runRejectingExample.

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 contract will be written. If you provide this, ContractCase will generate the filename for you (unless contractFilename is specified, in which case this setting is ignored).

ContractCase will not overwrite an existing file, so it's best to clear this directory at the start of a run.

contractFilename [string]​

Default: Generated by ContractCase during a run.

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

ContractCase will not overwrite an existing file, so it's best to remove this file at the start of a run.

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.

Contract Testing configuration options​

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

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 functions.

Internal options​

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.

testRunId [string]​

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

A unique identifier for this test. If you do not provide a contractFilename, ContractCase uses this field as part of the generated filename, to prevent multiple concurrent contract definitions from writing to the same file.