Skip to main content

Verification - Provider change

Provider verification tasks performed on provider commits​

Branches​

Configuring the branch when publishing pacts​

See here for full docs.

pact-broker publish ./pacts --consumer-app-version $GIT_COMMIT --branch $GIT_BRANCH

# or 

pact-broker publish ./pacts --auto-detect-version-properties

Configuring the branch when publishing verification results​

See here for full docs.

pact-provider-verifier  \
  --provider "Example API" \
  --provider-app-version $GIT_COMMIT \
  --provider-version-branch $GIT_BRANCH \
  ...

Consumer version selectors​

You can checkout code-snippets below, but here are some links to either documentation, or source code, from the respective languages, around their use of consumer version selectors. Ideally all languages should support raw json version selectors, to allow for extensiblity in the future.

Consumer version selectors - Code examples with branches​

Verifying the latest development, test and master pacts​

This is the most common use case.

  • We recommend using deployedOrReleased to return the pacts for all versions of the consumer that are currently deployed or released and currently supported in any environment, this allows the provider to not know that detail and let the Pact broker take care of it for you)
    • alternatively you can target just deployed or just released consumers across all environments , or consumers only in specified environments.
  • We recommend using mainBranch to return the pacts associated with any consumers configured mainBranch property (your consumer may have the branch main, master or develop, this allows the provider to not know that detail and let the Pact broker take care of it for you)
  • The shown selectors, will target for the provider
    • any pacts for the consumer associated with their configured mainBranch property
    • any pacts for the consumers, deployed to any environment
      • This if filtered by only pacts deployed or released to the test / production environments.
      • If this consumer/provider pair, has an additional environment staging, it would not be picked up, due to the named test / production environments. Removing these conditions, will return any pacts, deployed or released to any environment, which is the recommended setup for the majority of cases. (coupled with enabling pending pacts.)
const verificationOptions = {
  // ....
  consumerVersionSelectors: [
    {
      mainBranch: true, // (recommended) - Returns the pacts for consumers configured mainBranch property
    },
    {
      deployedOrReleased: true, // (recommended) - Returns the pacts for all versions of the consumer that are currently deployed or released and currently supported in any environment.
    },
    {
      environment: 'test', // Normally, this would not be needed, as it is recommended to verify the pacts for all currently deployed/currently supported released versions.
    },
    {
      environment: 'production', // Normally, this would not be needed, as it is recommended to verify the pacts for all currently deployed/currently supported released versions.
    },
  ],
};

Using a matching branch for coordinated branch development​

Dynamically determine the current branch of the provider, see if there is a matching pact for that branch.

const verificationOptions = {
  //...
  consumerVersionSelectors: [
    {
      matchingBranch: true, // Returns the pacts for providers configured branch property in the verification task. Normally covered by contract_requiring_verification_published event + corresponding webhook
    },
    {
      mainBranch: true, // (recommended) - Returns the pacts for consumers configured mainBranch property
    },
    {
      deployedOrReleased: true, // (recommended) - Returns the pacts for all versions of the consumer that are currently deployed or released and currently supported in any environment.
    },
  ],
};

Verifying pacts where the consumer is a mobile application​

Verify the pacts for the latest master and test versions, and all production versions of "my-mobile-consumer".

const verificationOptions = {
  // ....
  consumerVersionSelectors: [
    {
      mainBranch: true, // (recommended) - Returns the pacts for consumers configured mainBranch property
    },
    {
      deployed: 'test', // only the latest deployed version to test
    },
    {
      deployedOrReleased: 'production', // all deployed or released versions in production
    },
  ],
};

Verifying a pacts where one consumer is a mobile application​

Verify the latest production version of all consumers, and all production versions of "my-mobile-consumer". Note that the pacts are deduplicated, so despite being included by 2 selectors, the verification of the latest production pact for "my-mobile-consumer" will only run once.

const verificationOptions = {
  // ....
  consumerVersionSelectors: [
    {
      mainBranch: true, // (recommended) - Returns the pacts for consumers configured mainBranch property
    },
    {
      deployed: 'test', // Verify the latest deployed `test` version of all consumers
    },
    {
      deployed: 'production', // Verify the latest deployed `production` version of all consumers
    },
    {
      deployedOrReleased: 'production', // Verify all deployed or released `production` versions of my-mobile-consumer
      consumer: 'my-mobile-consumer'
    },
  ],
};

Verifying the overall latest pact for each consumer​

Verifying the overall latest pact for each consumer is syntactically possible, but not recommended, as pacts for different branches of the consumer may overwrite each other as the current latest.

You can do this by setting latest: true, however as this is wholly unrecommended, we instead show the minimum ideal requirement, to cover the latest pacts for

  • any consumer that is registered with the provider
    • the latest pact for any environment the consumer is deployed to
    • the latest pact, for any environment in the consumer is released to
    • the latest pact, for the consumer configured mainBranch
const verificationOptions = {
  // ....
  consumerVersionSelectors: [
    {
      mainBranch: true, // (recommended) - Returns the pacts for consumers configured mainBranch property
    },
    {
      deployedOrReleased: true, // (recommended) - Returns the pacts for all versions of the consumer that are currently deployed or released and currently supported in any environment.
    },
  ],
};

Consumer version selectors - Code examples with tags​

Verifying the latest development, test and master pacts​

This is the most common use case.

const verificationOptions = {
  // ....
  consumerVersionSelectors: [
    {
      tag: "master",
      latest: true,
    },
    {
      tag: "test",
      latest: true,
    },
    {
      tag: "production",
      latest: true,
    },
  ],
};

Using a fallback tag for coordinated branch development​

Dynamically determine the current branch of the provider, see if there is a matching pact for that branch, fallback to the master pact if none exists. This approach is not longer recommended - see the note on the fallbackTag at the top of the page.

const verificationOptions = {
  //...
  consumerVersionSelectors: [
    {
      tag: process.env.GIT_BRANCH,
      fallbackTag: "master",
      latest: true,
    },
    {
      tag: "test",
      latest: true,
    },
    {
      tag: "production",
      latest: true,
    },
  ],
};

Verifying pacts where the consumer is a mobile application​

Verify the pacts for the latest master and test versions, and all production versions of "my-mobile-consumer".

const verificationOptions = {
  // ...
  consumerVersionSelectors: [
    {
      tag: "master",
      latest: true,
    },
    {
      tag: "test",
      latest: true,
    },
    {
      tag: "production",
    },
  ],
};

Verifying a pacts where one consumer is a mobile application​

Verify the latest production version of all consumers, and all production versions of "my-mobile-consumer". Note that the pacts are deduplicated, so despite being included by 2 selectors, the verification of the latest production pact for "my-mobile-consumer" will only run once.

const verificationOptions = {
  // ...
  consumerVersionSelectors: [
    {
      tag: "master",
      latest: true,
    },
    {
      tag: "test",
      latest: true,
    },
    {
      tag: "production",
      latest: true,
    },
    {
      tag: "production",
      consumer: "my-mobile-consumer",
    },
  ],
};

Verifying the overall latest pact for each consumer​

This is syntactically possible, but not recommended, as pacts for different branches of the consumer may overwrite each other as the current latest.

const verificationOptions = {
  // ...
  consumerVersionSelectors: [
    {
      latest: true,
    },
  ],
};

Verifying pacts​

Examples​

Using branches and environments

const verificationOptions = {
  // ....
  provider: "example-provider",
  pactBrokerUrl: "http://test.pactflow.io",
  consumerVersionSelectors: [
    {
      mainBranch: true
    },
    {
      matchingBranch: true
    },
    {
      deployedOrReleased: true
    }
  ],
  enablePending: true,
  ...(process.env.GIT_BRANCH === "main"
? {
    includeWipPactsSince: "2020-01-01",
  }
: {})

  // used when publishing verification results
  publishVerificationResult: process.env.CI === "true", //only publish from CI
  providerVersion: process.env.GIT_COMMIT, //use the appropriate env var from your CI system
  providerVersionBranch: process.env.GIT_BRANCH,  //use the appropriate env var from your CI system
}

Using tags (this approach is now superseded by branches and environments)

const verificationOptions = {
  // ....
  provider: "example-provider",
  pactBrokerUrl: "http://test.pactflow.io",
  consumerVersionSelectors: [
    {
      tag: "main",
      latest: true
    },
    {
      tag: process.env.GIT_BRANCH,
      latest: true
    },
    {
      tag: "test",
      latest: true
    },
    {
      tag: "production",
      latest: true
    }
  ],
  enablePending: true,
  includeWipPactsSince: process.env.GIT_BRANCH === "main" ? "2020-01-01" : undefined,

  // used when publishing verification results
  publishVerificationResult: process.env.CI === "true", //only publish from CI
  providerVersion: process.env.GIT_COMMIT, //use the appropriate env var from your CI system
  providerVersionTags: process.env.GIT_BRANCH ? [process.env.GIT_BRANCH] : [],
}