Skip to main content

· 5 min read

Welcome to the Pact Open Source August 2022 update!

I have some awesome updates for you this month!

‌As always, thanks to all of the contributors who have made this happen, if you haven’t been mentioned here but wish to appear in a later update, feel free to reach out to me on Slack.

Pact JS​

Pact JS 10.x.x is now live

Get it here 👉: https://github.com/pact-foundation/pact-js

Summary of the good stuff​

  • Speed! - It’s quick, blisteringly quick. You’ve probably heard people talk about just how good Rust is, they weren’t wrong.
  • Full support for binary payloads (both HTTP and Async) and multi-part uploads
  • For Async, the ability to specify and verify message metadata
  • XML support
  • Ability to create and verify both v2 and v3 specification pacts
  • Support for all v3 matchers and generators, and other v3 items (such as multiple provider states with parameters)
  • Improved support for Hypermedia APIs such as HAL and Siren through url and arrayContaining
  • Support for dynamic IDs in requests via provider state injected values (fromProviderState matcher)
  • arrayContaining and eachKeyLike matchers for improved array matching
  • Ability to modify request bodies and headers during verification (via requestFilter on the provider)

Docs​

Community corner – member shout outs​

Big props to the many who have helped make Pact-JS such a success, but we wanted to take a moment to give a shout out for a few whose contributions have really propelled adoption and the beta, into GA. We of course, can't forget Matt Fellows who is a machine that never sleeps, each contribution, helps Matt get 5 more minutes with the kids. Save a Matt, make a contribution.

Ron Holshausen​

Ron has been diligently plugging away at the Rust core, a Pact implementation written in Rust. It supports the V3 Pact specification and V4 Pact specification and provides shared libraries that can be used in other languages via foreign function interfaces (FFI).

It has now been adopted in Pact-JVM, Pact.Net, Pact-JS and Pact-Go, and although we are still ironing out issues, we are so grateful for the time Ron spends in trying to improve the landscape. I’ll let Ron explain some of the journey

One of the strengths of Pact is its specification, allowing anybody to create a new language binding in an interoperable way. Whilst this has been great at unifying compatibility, the sprawl of languages makes it hard to add significant new features/behaviour into the framework quickly (e.g. GraphQL or Protobuf support).

We have attempted to combat this time-to-market problem, by focussing on a shared implementation (the "shared core") in many of the languages. We initially bundled Ruby, because it was convenient, but have been slowly moving to our Rust core which solves many of the challenges that bundling Ruby presented.

The "shared core" approach can only take us so far, and we need another mechanism for extending behaviour outside of the responsibilities of this core. This is where I see a plugin approach working with our "shared core" model.

Tim Jones​

Pact-JS wouldn’t be half of what it is today, without Tim Jones. Outside of the Pactflow co-founders and myself, Tim has the most GitHub and Slack contributions of anyone in the Pact community, it really is staggering. He always delivers gems of well thought advice with a smile, and is an absolute delight to work with. He took a well earned break from being a full-time Pact maintainer earlier this year, but if you’ve had the time to visit the Pact Slack group, you’ve probably seen him armed with Tim’s Tech Tidbits, which we all need to encourage him to make into a YouTube series.

Aligntech​

What has the team at Aligntech been up to? Sponsoring some of the initial implementation and XML!

Much respect to Aligntech for sponsoring the initial implementation of Pact JS v3 and XML support, we are proud to show them on our website, along with other great companies and contributors who have helped Pact become as widely adopted as it is today.

Check out Aligntech and the great work they do.

Artur Neumann​

Thanks to Artur Neumann for driving beta adoption and usage (via owncloud) and providing an incredible amount of feedback on the Pact V3 release. One look at the pact-js issues and PR list shows Artur's energy in raising issues in the V3 beta, or dropping in helping contributions to the codebase.

This feedback is critical in helping us improve the tooling for all of our users, and is also highly rewarding, seeing something you’ve created or had a hand in, helping others, even if it's not quite right.

Become a contributor​

If you’re passionate about Open Source, Pact or a specific language, get involved as a maintainer. There’s no minimum time commitment and you can get involved on your own terms. One thing that does make the Pact OSS so great is regular, committer contributions.

Read our Contributing page to find out many of the different ways you can get involved in Open Source, no matter what role, or skillset you hold.

That's all for now, catch you next month!

  • Yousaf Nabi — Developer Advocate at Pactflow and Community Shepherd at Pact.

· 5 min read

Welcome to the Pact Open Source July 2022 update!

Hope you have all been enjoying the sun whenever you are in the world, unless like our Pact core team, you live in Australia. Sweaters at the ready.

This month has seen a flurry of activity across the open source space, with many new contributors helping in a multitude of ways, so we will call out some notable mentions.

‌Thanks to all of the contributors who have made this happen, if you haven’t been mentioned here but wish to appear in a later update, feel free to reach out to me on Slack.

Specific language updates​

Golang​

Attention Golang users - the latest 2.x.x is out (2.0.0-beta.13)! 🚀This is quite a big change from the past release, namely we’ve been thinking about the API design with the introduction of V4 and plugins.

Summary:

A word from our Pactflow co-founder & pact-go maintainer Matt Fellows

Because the API is more complex, we’ve used a type state builder pattern to force which options can be used at any point in time, and ensure that pre-requisite methods are called in sequence. We are still not 100% happy with the HTTP package layout (and requiring V2/V3/V4 prefixes on a number of types), so there might be another refactor in that space, but mainly we think it would just be the names of types and packages that could change. We will tidy up the documentation over the next few days, but look to the examples folder in the short term if you’re wondering what’s changed. Our core maintainer found refactoring the existing examples fairly straightforward, so we hope you do too.

Chat with us in: #pact-go

Node JS​

Pact-JS - Pact specification V3 beta now supports modifying the request body in the verifier which has been a long standing issue and more work is progressing on stabilizing for General release: https://github.com/pact-foundation/pact-js/tree/feat/v3.0.0/ (v10.0.0-beta.60). Follow the roadmap progress.

Chat with us in: #pact-js

Rust​

Pact FFI 0.3.3 was released https://github.com/pact-foundation/pact-reference/releases/tag/libpact_ffi-v0.3.3 which brought in add retries to the provider state change calls along with some bug fixes

Chat with us in: #pact-rust

.Net​

PactNet 4.1.0 is now released and pushed which allows publishing verification results for URI sources

See the upgrade guide for details of the rewrite and how to upgrade from 3.x to 4.x

Chat with us in: #pact-net

Community Corner​

You lot were busy this month, despite the sunny climes, don’t forget to nip outdoors!

Just look at all the merged Pull Requests that have come in from the community.

You are all awesome

Pull Requests – Features/Fixes​

Big call out to Dave Clissold who performed the first two PR’s in this list, which resolved one of the most active outstanding issues in Pact-JS and indeed across the pact-foundation. It was 3 years old, and shows how difficult it can be to get changes in, with ever-changing demands, but you can get involved, and help deliver the features you want now, and we can help guide you along

Pull Requests – Docs​

Much respect to Eduardo Lopez for adding illustrations to our docs, to help guide people around the OSS Broker UI, it’s not all about the code, and there is always a need to keep our documentation up to date and consistent. Found a snag, patch it up with a new PR and get some committer kudos. It can be as easy as adding screenshots, and it will make a massive difference

Pull Requests – Maintenance Stuff​

Shout out to Artur Neumann, for being a pivotal member in supporting the pact-js beta rollout and helping make Matt’s life a little easier.

Community Spotlight – Mike Geeves​

We haven’t spoken enough about Mike Geeves from Bearly Compiling :chef kiss: - He has been working on Pact on and off, over the last couple of years, and has been thoroughly confused enough by our examples at times, to want to do something about it!! Mike has helped me during my time joining the Pactflow team and has been great for the occasional rant, and productive conversations that always end up in more work. I don’t think we’ve quite cracked pomodoro.

So why did Mike start tickling Pact?

I tend to try and come up with ideas, which I can at least PoC enough to demonstrate what I mean, and then see if there's any uptake of the idea to progress, if not bin it, which has led to the slightly bizarre situation where my first ever open source contribution was in Rust for pact-rust, and I cannot code in Rust 😂

So what are Mike and I up to now? We are looking at our examples with a particular focus on our support for Message Pacts across the different libraries and building up a compatibility matrix with documentation driven from examples. Want to join us on the adventure? Get involved in #documentation over at slack.pact.io

That's all for now, catch you next month!

  • Yousaf Nabi — Developer Advocate at Pactflow and Community Shepherd at Pact.

· 8 min read

Welcome to the Pact Open Source June 2022 update!

This month has seen a flurry of activity across the open source space, with many new contributors helping in a multitude of ways, so we will call out some notable mentions.

‌Thanks to all of the contributors who have made this happen, if you haven’t been mentioned here but wish to appear in a later update, feel free to reach out to me on Slack.

Specific language updates​

.Net​

PactNet 4.0.0 is now released and pushed, have a look.

See the upgrade guide for details of the rewrite and how to upgrade from 3.x to 4.x

Some words from our amazing maintainer Adam Rodger:

Release Announcement Now that we've been in beta for a good while I think we're ready for a proper release of PactNet 4.0.0. I think we've ironed out any teething issues now, so thank you to all those that have participated in the beta and raised issues for me to fix. I've got the current latest beta running in production at my employer and everything appears to be working OK. Of course there will be more features and things to add in the future, but I think the core functionality is all there and the API can be considered stable. Adam released PactNet 4.0.0 on 6 June and is now enjoying a well-deserved holiday. Thank you, Adam.

Chat with us in: #pact-net

NestJS + Pact = <3​

Omer Morad, our friend in, Tel Aviv, Israel, is a backend-oriented developer, OOP flavored, in a distributed systems world and also a Web artisan, TypeScripter, open-source enthusiast, and guitar player.

He recently brought in https://github.com/pact-foundation/nestjs-pact to the pact-foundation and we would love to get it featured on the awesome-nestjs repo.

Are you using NestJS + Pact? Want to help build out an example? Chat with us in: #pact-nestjs

Pull Requests​

  1. Pact-Reference - Allow BrokerWithDynamicConfiguration to publish results by Kageru

  2. Pact-JVM – Support for providerVersionBranch option to replace providerVersionTag with thanks to Ben Pilgrim & Praveen Erode Mohanasundaram

  3. Pact-JVM – Rejeeshg for updating builds to resolve vulnerabilities. Dependabot or similar would be great here to save the manual effort! PR’s welcome :)

  4. Pact-PHP / Pact-Ruby / All the things – Shout out to Lewis Cowles and Jonathon Padfield.

Lewis has been working hard on improving alpine support, fixing the pact-php build after a URL change and created a number of issues against the pact-php repo to help the maintainer. Lewis said:

This one introduces scheduled builds so that if a maintainer gets "life happen" then you can still as an org know if that package is failing, and get visibility before a customer comes to you. It's a thing I use if I want to show something so that I know it should always be build-able.

And thanks Jonathon for updating pact-ruby-standalone to use travelling ruby 2.4, we are testing this out now and hope to roll this out across all the libraries soon.

Bi-Directional Adapters​

WireMock & .Net​

Using WireMock & .Net and want to benefit from Bi-Directional Contract Testing?

🔥 Now you can generate Pact 🔗 contracts from your WireMock Server, check it out here.

Thanks Stef Heyenrath 😍 for the his work in the community!

Pact-MSW Adapter​

Pact-MSW-Adapter now has new features and a quick start guide, an international effort with contributors from the UK, Argentina, Spain and Canada. Shouts go out to:

  1. Kiko Ruiz Llorret for request query support
  2. Nicholas Simons for post request support
  3. And we cannot forget Juan Cruz for being an early trailblazer and improving the developer experience vastly

Create your own adapters to use in Bi-Directional Contract Testing!​

Inspired by our list of tools, but don’t see your favourite? Create your own! Here's how:

  1. Convert your mock format to a supported Pact specification format - we recommend v2 at the moment - see a jsonschema to test against
  2. Create an example - see our existing supported tools and demos
  3. Submit a PR to to get listed

Our awesome community​

Developer Relations at Pact-Foundation now has a new home @ https://github.com/pact-foundation/devrel

We recently hooked up Orbit.love, to give us a bit of a glance across our open source estate, and we were able to pull out well over 2k different contributions from just the top 15 in the leaderboard excluding Pactflow’s co-founders!

Particular shout-out to Timothy Jones, who has been on an epic crusade to empower those around him with words of contract testing wisdom and delightful development life-hacks. The Pact world wouldn’t be the same without you all, and we appreciate every contribution big or small.

Pact contributors

Pact contributors

Community is everything for us. And that’s why we have big plans to dive into the various initiatives and determine how we can acknowledge and support members and the community as a whole for their time and dedication. Without each of you ❤️ Pact would not be the leading open source cross-language distributed contract testing framework! Like us, you should be so proud that you’re helping free the world from the burden of microservice spawl and deployment headaches.

Other ways to get involved with Pact​

The Pact ecosystem is vast, I will be sharing some posts over the upcoming months, showing the size of the estate, and looking to gain insight from you, the community, as to how we can reduce the signal-to-noise and help reduce the cognitive load required to navigate the path the Pact Nirvana in your own organisation.

There are a multitude of ways, and you don't need to be a code wizard to start:

  • 📙 Docs - Our documentation is the primary way to communicate to our users, you can help out with small changes like a typo, help rewrite larger pieces, or add new content. Think of it as a open source contract testing wiki, and you are all the curators.
  • 🚀 Code - We have implementations across multiple languages, and not all of them are at feature parity. Sometimes you might need that feature, or you've found a bug. Every pact-foundation repository is open-source, and contains a contributing guide to help you get started. Maybe you are building your own Pact tooling, let us know, we would love to shout about it.
  • Roadmap / Feature Requests - The Pact roadmap is available on Canny, where you can see some of the teams current and upcoming priorities in the OSS space. You can request new features, or browse the list and vote/comment on ones you would love to see. See one that particularly resonates? You could help work on it, reach out via Slack and we can help guide you through your contribution.
  • Recipes - The community use our tools in a variety of different ways, and solve various challenges that others could benefit. Got something to share? Why not add a new recipe to the site?
  • Workshops - We created a number of workshops, across several languages. Is there a language implementation not covered in the workshop? Maybe you've created or seen some amazing workshops out there in the wild? Add it to the list, or if you are the author, you can discuss bringing your workshop under the Pact-foundation, if you feel all Pact users could benefit
  • Blogs, Videos & Articles - Articles about contract testing are appearing left, right and centre, I can't keep up. Make sure our reading list doesn't get dry, by adding your favourite content to the list
  • Events - Meetups, in person, it feels like a distant memory, but as the doors start opening again, and dinner is provided, people are beginning to flock outdoors. Have you got a meetup or event planned? Already had one and recorded it? You can add them to the list, and let us and the community know about it on Slack.
  • Helping those in the community - We know many of you in the community love sharing your contract testing knowledge with others, you can see the various places our users land for help, sometimes in GitHub issues, Stack overflow, or Slack. You are welcome to help them out whether you are new to Pact, or a seasoned pro, all questions, opinions and thoughts are welcome.
  • Pact champions - Are you like our co-founder Beth Skurrie, who decided that Pact idea was the best thing since sliced bread, and she hasn't stopped yacking on about it since. Want to share your knowledge, and build your social profile in the world of tech with a global platform? Please get in touch with me on Slack, we want to support the amazing work you do! If you love Pact, and want to help the world worry less about micro-service deployment, why not join us on our journey. Who knows where it might lead.

That's all for now, catch you next month!

  • Yousaf Nabi — Developer Advocate at Pactflow and Community Shepherd at Pact.

· 6 min read

Welcome to the inaugural Pact Open Source update!

This month Pactflow officially joins the SmartBear family, and with this, the Pact OSS community will be supported by SmartBear. We're excited to join SmartBear and together, expand contract testing to more developers and testers. Read more about what this means for you.

The contributor community has been hard at work uplifting key languages to integrate our Rust shared core, enabling support for the latest features in the specification, plugins and more.‌ ‌‌ ‌Thanks to all of the contributors who have made this happen.‌

Specific language updates​

.NET​

Pact-net: Next major release is not far away, with the Pact specification v3 beta stabilising: https://github.com/pact-foundation/pact-net/ (v4.0.0-beta.3).

Chat with us in: #pact-net

Golang​

Pact-go: Next major release is not far away, with the Pact specification v3 beta stabilising: https://github.com/pact-foundation/pact-go/tree/2.x.x (v2.0.0-beta.10).

Chat with us in: #pact-go

Node JS​

Pact-JS: Pact specification V3 beta now available: https://github.com/pact-foundation/pact-js/tree/feat/v3.0.0/ (v10.0.0-beta.59). Follow the roadmap progress.

Chat with us in: #pact-js

Swift​

Pact-Swift: Pact specification V3 support and provider side verification in Swift: https://github.com/surpher/PactSwift.

Chat with us in: #pact-swift

Scala​

Scala-Pact: 🚧 ITV Pact is moving to maintenance mode and will only support up to Pact specification V2.

pact4s: The future is pact4s, which is a Scala wrapper of Pact JVM and currently supports up to Pact specification V3.

Chat with us in: #pact4s

Python​

Pact-Python: Message support was added in 2021 to enable testing of asynchronous integrations such as RabbitMQ or Kafka (https://github.com/pact-foundation/pact-python/pull/194, https://github.com/pact-foundation/pact-python/pull/251).

Chat to us in: #pact-python

V4 Pact Specification​

Pact specification V4 is here! We worked hard on listening to the community, after the release of v3, 5 years ago. We consolidation many of the requests people made about things that haven't worked quite properly. One of the biggest changes is consolidation the file format to allow for HTTP and message interactions with a single file.

Plugins, Protobufs and gRPC (oh my!)​

Back in September 2021 Matt introduced us to The case for contract testing Protobufs, gRPC and Avro.

We are pleased to announced initial support for testing gRPC interactions via plugins has been added to Pact-JVM (for Junit5) and Pact-Rust including the shared core, enabling distribution to other client libraries.

We have released an official Pactflow Protobuf / gRPC plugin for Pact.

Join the Developer Preview Program for updates, or chat to us in #protobufs.

Pactman​

Hungry for docs, but don't want to move from your terminal? Type npx pactman for a treat 😲

🔍 pactman - search the pact docs from your terminal 👩‍💻

Pactman

Get involved!​

The Pact ecosystem is vast, I will be sharing some posts over the upcoming months, showing the size of the estate, and looking to gain insight from you, the community, as to how we can reduce the signal-to-noise and help reduce the cognitive load required to navigate the path the Pact Nirvana in your own organisation.

There are a multitude of ways, and you don't need to be a code wizard to start:

  • 📙 Docs - Our documentation is the primary way to communicate to our users, you can help out with small changes like a typo, help rewrite larger pieces, or add new content. Think of it as a open source contract testing wiki, and you are all the curators.
  • 🚀 Code - We have implementations across multiple languages, and not all of them are at feature parity. Sometimes you might need that feature, or you've found a bug. Every pact-foundation repository is open-source, and contains a contributing guide to help you get started. Maybe you are building your own Pact tooling, let us know, we would love to shout about it.
  • Roadmap / Feature Requests - The Pact roadmap is available on Canny, where you can see some of the teams current and upcoming priorities in the OSS space. You can request new features, or browse the list and vote/comment on ones you would love to see. See one that particularly resonates? You could help work on it, reach out via Slack and we can help guide you through your contribution.
  • Recipes - The community use our tools in a variety of different ways, and solve various challenges that others could benefit. Got something to share? Why not add a new recipe to the site?
  • Workshops - We created a number of workshops, across several languages. Is there a language implementation not covered in the workshop? Maybe you've created or seen some amazing workshops out there in the wild? Add it to the list, or if you are the author, you can discuss bringing your workshop under the Pact-foundation, if you feel all Pact users could benefit
  • Blogs, Videos & Articles - Articles about contract testing are appearing left, right and centre, I can't keep up. Make sure our reading list doesn't get dry, by adding your favourite content to the list
  • Events - Meetups, in person, it feels like a distant memory, but as the doors start opening again, and dinner is provided, people are beginning to flock outdoors. Have you got a meetup or event planned? Already had one and recorded it? You can add them to the list, and let us and the community know about it on Slack.
  • Helping those in the community - We know many of you in the community love sharing your contract testing knowledge with others, you can see the various places our users land for help, sometimes in GitHub issues, Stack overflow, or Slack. You are welcome to help them out whether you are new to Pact, or a seasoned pro, all questions, opinions and thoughts are welcome.
  • Pact champions - Are you like our co-founder Beth Skurrie, who decided that Pact idea was the best thing since sliced bread, and she hasn't stopped yacking on about it since. Want to share your knowledge, and build your social profile in the world of tech with a global platform? Please get in touch with me on Slack, we want to support the amazing work you do! If you love Pact, and want to help the world worry less about micro-service deployment, why not join us on our journey. Who knows where it might lead.

That's all for now, catch you next month!

  • Yousaf Nabi — Developer Advocate at Pactflow and Community Shepherd at Pact.

· One min read

Pactflow + Smartbear

Today, Beth, Ron and I have some exciting news to share with you. Pactflow has been acquired by SmartBear, a leading provider of software development and quality tools. We will join their API Developer Platform, helping to solve the complex challenges of testing microservices and API integrations that companies are facing as they accelerate cloud-native application development and digital initiatives.

We care so much for OSS and are so pleased that SmartBear has a strong and demonstrated commitment to OSS—as proven through the support and scale of Cucumber and Swagger. Through our partnership, we will be able to take contract testing to new heights and help deliver key milestones in Pact’s OSS roadmap.

We wanted to take the opportunity to thank you for your dedication and support. Pactflow is not just the product built by our immediate team, but a community of individuals who’ve brought us to this point today. We’ve shared many milestones together and we look forward to sharing many more.

Read the blog.

· 2 min read
tl;dr

The contract_requiring_verification_published webhook event is a new and improved version of the contract_content_changed event to use when triggering provider verification builds.

Webhooks in the Pact Broker can be triggered when certain predefined events occur. They are primarily used to obtain provider verification results for a pact when a new version is published with changed expectations. Historically, a webhook using the contract_content_changed event was used to trigger a build of the provider that verified just the changed pact, the URL of which would be passed through to the build using webhook template parameters.

A new and improved webhook event, contract_requiring_verification_published is now supported. It will be triggered if a pact is published with content that does not have a verification result from the main branch of the provider, or any of the deployed or released versions of the provider. The provider versions will be de-duplicated, and the webhook will then trigger once for each provider version. The provider version that needs to run the verification will be available in the webhook parameters as ${pactbroker.providerVersionNumber}. The triggered provider build must then check out the specified version of the provider codebase, and verify the changed pact, which will also be passed through via the ${pactbroker.pactUrl} parameter.

The contract_requiring_verification_published webhook has a number of advantages over the existing contract_content_changed webhook.

  • It makes it easy to obtain verification results from the test and production versions of your provider, allowing consumer versions with changed contracts that are already supported by the production provider to be deployed straight away.
  • It only triggers if there is a verification result missing for one of the critical provider versions, reducing the number of unnessary builds triggered.

Read more about the new event in the docs here to start using it.

· 7 min read
tl;dr

Tags that represent branches and environments are being replaced with first class support for branches, environments, deployments and releases.

"Tags" in the Pact Broker are simple string values that belong to application version resources (aka. "pacticipant versions") that are generally used to track the git branches and environments associated with an application version. They allow us to identify specific versions when testing backwards compatability and introducing new features, and when determining if an application is safe to deploy. Tags have the advantage of being flexible and generic enough to support any development workflow.

Tags have their disadvantages though. They are similar enough to Docker tags that users expect them to work the same way, but different enough that pages of documentation need to be written to explain how to use them. The main problem with tags though, is that no semantic information that can be inferred from them - that is, it's impossible for the Broker to know whether a tag represents a git branch, an environment, or something else entirely.

· One min read

When a Pact Broker instance has accumulated large amounts of data, its performance can start to degrade. A new feature has been released in the Pact Foundation's Pact Broker Docker image to allow old, unused data to be removed automatically from the Pact Broker at a configured schedule. The clean up can either run on a cron schedule from the Pact Broker application container, or it can be executed from an external location, independent of the running instance. Read more about the clean feature in the Maintenance section of our Pact Broker docs.

· 6 min read

tl;dr​

Changes to the contract made by the consumer teams can no longer break the provider builds. Hooray!

Read on for the longer version...

The problem

Pact is a consumer driven contract testing tool that allows you to test your integration points without dependencies. The consumer is tested with a mock provider, and a contract ("pact") is generated from the tests. The contract is taken over to the provider and then "verified" to make sure that the real provider and the mock provider behave the same way.

During the verification step, each request from the contract is replayed against a running test instance of the provider, and the responses are compared to the expected responses. If they match, the verification is successful. If they do not match, the verification has failed, and the provider build fails.

In the context of an existing contract, there are two reasons that the pact verification step can fail when it was previously passing.

  1. The provider has changed.
  2. The contract (consumer expectations) has changed.

In scenario 1, we actually want the provider build to fail, as this is the purpose of contract testing - it prevents breaking changes being made by the provider for existing consumers.

In scenario 2 however, when the contract has changed, the failure of the provider build is an undesirable consequence of the workflow. The contract may have changed due to the teams following the "consumer driven" nature of the process whereby the expectations come before the implementation (TDD for services); there may be an issue with the provider state data; or there may just be incorrect expectations about existing behaviour.

The fact that the provider build can be broken by new or incorrect expectations in the contract (which is effectively written by the consumer team) is one of the biggest problems people have with Pact. It leads to contention between teams, and in some cases, stops teams using Pact at all.

One solution could be to run all pact verification builds in such a way as to ignore any failures that might occur, but then we'd miss being alerted to potentially breaking changes by the provider, which defeats the purpose of using contracts in the first place.

What we want is a way to get feedback on changed contracts without breaking the provider build, but for the build to correctly identify and fail when a provider is making a breaking change.

The solution

The Pact team is extremely happy to introduce the new "pending pacts" feature.

Those familiar with automated testing frameworks have probably come across the term "pending" tests. These are tests that have a particular flag on them that causes them (depending on the framework) to either be skipped, or if executed, to not fail the build. In the case of Pact, we want the feedback we get from execution, so rather than a "pending pact" being one which will be skipped, it is one which can be verified without its failure causing the overall verification task to fail.

So how does the Pact verification tool know if a pact is in "pending" state or not? This is where the Pact Broker comes in. The Pact Broker is a service that sits between the consumer and provider builds, and allows the contracts and verification results to be exchanged between the consumer and provider teams. The Pact Broker can identify when a contract with new content has been published, and when it is retrieved for verification by the provider's Pact library, it flags it as "pending". The Pact library executes the verification, ensuring that the status of the overall task is not affected by any failures. At the end of the verification process, the outcome of the verification is published back to the Pact Broker. Once the pact has been successfully verified it ceases to be "pending". This means that any subsequent verification failures for a pact with identical content will cause the provider build to fail, as the failure can now only be due to a change in the provider code.

How do I start using pending pacts?

Head to https://docs.pact.io/pending for information on how to setup your Pact Broker to enable this feature (it is enabled by default on https://pactflow.io).

To start getting the benefit of this new and improved workflow, you will need to upgrade to the latest version of the Pact Broker and your Pact testing libraries. Consult the documentation for your language to find out how to enable the pending feature.

If you're on a consumer team, and have, until now, relied on the provider team to alert you to verification failures, you'll want to make sure that you're getting this information via another channel now. We recommend that you use can-i-deploy to make sure that you aren't deploying with a broken contract, and that you set up webhooks to ensure you're made aware of the verification outcomes of your contracts as soon as possible (eg. posting to a team's Slack channel, or updating a Github commit status.)

A note for advanced Pact Broker users​

If you're not using tags in the Pact Broker you can skip this section! But take the time you've saved reading the next paragraph, and spend it reading up on tags because if you're not using them, you're probably not getting the full benefit out of your Pact Broker.

Tag users - the "pending" status is calculated using the provider version tag(s) that will be published with your verification results. The provider tags are sent to the Pact Broker when retriving the list of pacts to verify, and are used to determine the pending status for each pact returned. For example, once you have successfully verified a pact with a version of the provider tagged as feat-x, then pacts with the same content will be non-pending for any subsequent verifications by a feat-x version. However, the same pact could still be in "pending" state for the master.

Why is this important? It means that if you're using a feature branch tagged feat-x on your provider to implement a new interaction, the pact will remain pending on your master branch even after it passes verification on the feat-x branch. It will only become non-pending on master once the feature branch has been merged in, and the pact has passed verification on the merged code.

Conclusion

We're pretty excited about this new workflow, and we hope it will help make your experience testing with Pact a smoother and happier one. Let us know how you find it on the Pact Foundation Slack (join here).

· 4 min read

When following the "consumer driven" workflow, often the contract will change to express the desired functionality before the implementation exists in the provider. This means that when the changed pact is verified against the provider, the verification step fails, and until recently, this meant that the provider's build would also fail. (This has been fixed with the release of the pending pacts feature.) The recommended approach to avoid breaking the provider's build is to use "tags" to distinguish between the "safe" contracts and the changed contracts (tags are metadata that get applied to the application version resource in the Pact Broker that can be used to identify which branch or stage the version belongs to eg. master, feat/foo or prod). By making changes to the pact on a branch of the consumer (eg feat/foo) and publishing it with a matching tag, a provider that was configured to verify master pacts would not have its build broken.

For the consumer to get a verification result for the feat/foo pact, however, manual action was required from the provider team. They would need to add the feat/foo pact to the list of pacts to verify, generally on a feature branch of their own to avoid breaking the master build. There was no automated workflow to include the newly changed pacts in the provider's list of pacts to verify.

The solution

To solve this problem, we've introduced the concept of "WIP" (work in progress) pacts. "WIP pacts" is built on top of the recently released pending pacts feature which allows changed pacts to be verified without failing the build. Previously, during a verification step, only the pacts for the configured tags (eg master and prod) would be verified. With the WIP pacts feature enabled, all pacts that are the latest for their tag that have not yet been successfully verified will now also be automatically verified - in pending mode. This allows consumers to get feedback on whether or not their changed pacts are valid, without the provider team having to take action, and without breaking the provider build.

Let's walk through an example. Imagine FooApp and BarAPI have a pact. BarAPI is configured to verify the master and prod pacts for FooApp during its verification step. When it publishes the verification results, its own application version is tagged with the branch name. We'll just consider the builds that run on the BarAPI master branch for now.

FooApp creates a branch called feat/x, makes a change to the contract, and then publishes it with the feat/x tag. When the BarAPI build executes, it runs the verification task for the configured master and prod pacts as normal, but it also now verifies the feat/x pact in pending mode, and publishes the results back to the broker. Publishing the failed results allows the consumer team gets the feedback for feat/x pact, and the fact that it runs in pending mode means that even though the feat/x pact fails verification, the BarAPI build remains green.

A few days later, the BarAPI team implements the changes required for the feat/x pact. During the BarAPI CI build, master, prod and feat/x pacts are verified and the results published, but this time, the verification of the feat/x pact passes. The Pact Broker now knows that the master branch of the provider supports the feat/x contract, and from then on it ceases to be a WIP pact for master BarAPI versions. The next time the BarAPI build runs, it will not include the feat/x pact.

Now the action is on the consumer team to merge the feat/x branch into their own master branch. Using webhooks that update the Git commit status or posting to a Slack channel is a good way to notify the consumer team that their pact is now green.

A note for advanced Pact Broker users

As noted in the blog on the pending pacts feature, the pending status is calculated based on the tags that will be applied to the provider version when the verification results are published. This means that a pact that has been successfully verified by the feat/bar branch of your provider, but not master, will still be included in the "work in progress" pacts for master builds, but not for feat/bar builds.

How do I start using WIP pacts?

Head to https://docs.pact.io/wip for information on how to setup your Pact Broker (it is enabled by default on https://pactflow.io)

To start getting the benefit of this new and improved workflow, you will need to upgrade to the latest version of the Pact Broker and your Pact testing libraries. Consult the documentation for your language to find out how to enable the WIP pacts feature.