pact 1.3.0 → 1.3.1

checksums.yaml

@@ -1,7 +0,0 @@
----
-SHA1:
-  metadata.gz: 344262ac8b4cc83241621231547e801f20ee20b7
-  data.tar.gz: 0f66fdec5c968b3711a2b1c2ea701ddcc189d7e6
-SHA512:
-  metadata.gz: 64836e31b92b54c0d9f1edf75ada165b57fa646d45467872b6561721c4fd963176d52c7dab8474bd0490a2b33de418a57b82292fcb8adcf72fb64dade0c7ff2b
-  data.tar.gz: 6877c4151371466b579ad644866b96a88cfd24acc416583cf47ff45ad173f90de629f677b655e5d2f20594bf91f0bb68642ca706b385ebb58138cc77b02b4359

data/documentation/best-practices.md

@@ -1,33 +0,0 @@
-# Pact best practices
-
-## In your consumer project
-
-#### Publish your pacts as artifacts on your CI machine or use a [Pact Broker](https://github.com/bethesque/pact_broker)
-
-Either of these techniques makes the pact available via URL, which your provider build can then use when it runs pact:verify. This means your provider will always be verified against the latest pact from your consumer.
-
-#### Ensure all calls to the provider go through your provider client class
-
-Do not hand create any HTTP requests in your consumer app or specs. Testing through your provider client class gives you the assurance that your consumer app will be creating exactly the HTTP requests that you think it should.
-
-#### Use factories to create your expected models
-
-Sure, you've checked that your client deserialises the HTTP response into the object you expect, but then you need to make sure in your other tests where you stub your client that you're stubbing it with a valid object. The best way to do this is to use factories for all your tests.
-
-## In your provider project
-
-#### Retrieve pacts from the [Pact Broker](https://github.com/bethesque/pact_broker) or use the pact artifact published by your consumer's CI build
-
-Configure the pact_uri in the Pact.service_provider block with the pact URL of your last successful build, whether that's from the pact broker, or your CI build. This way you're only verifying green builds. No point verifying a broken one.
-
-#### Add pact:verify to your default rake task
-
-It should run with all your other tests. If an integration is broken, you want to know about it *before* you check in.
-
-#### In pact:verify on the provider, only stub layers beneath where contents of the request body are extracted
-
-If you don't _have_ to stub anything in the provider when running pact:verify, then don't. If you do need to stub something, make sure that you only stub the code that gets executed _after_ the contents of the request body have been extracted and/or validated, otherwise, there is no verification that what is included in the body of a request matches what is actually expected.
-
-#### Stub calls to downstream systems
-
-Consider making a separate pact with the downstream system and using shared fixtures.

data/documentation/development-workflow.md

@@ -1,22 +0,0 @@
-# Development Workflow
-
-Using consumer driven contracts enables you to reverse the "normal" order of development, allowing you to build your consumer, in its entirety if need be, before you build your provider.
-
-The development process will be different for every organisation, but this is one that has worked for the pact authors.
-
-## Initial development
-1. Write consumer tests with pact
-1. Implement consumer 
-1. Add `pact:publish` task to consumer build or publish pact as CI artifact
-1. Create provider project
-1. Configure pact:verify task to point to latest published pact
-1. Implement provider until `pact:verify` passes
-
-## New features
-
-1. Add new feature, with pact specs, to consumer project on a new feature branch.
-1. In the provider project, use `rake pact:verify:at[/path/to/pact/on/branch]` to verify the new pact.
-1. Commit/release new provider feature.
-1. Merge consumer branch into main development branch.
-
-This may seem complex, but it is actually sufacing the underlying reality, that you cannot add new functionality to the consumer before it can be supported by the provider, and that the functionality that the provider supports should still be driven by the needs of the consumer.

data/documentation/faq.md

@@ -1,81 +0,0 @@
-# Frequently asked questions
-
-### How does Pact differ from VCR?
-
-Pact is like VCR in reverse. VCR records actual provider behaviour, and verifies that the consumer behaves as expected. Pact records consumer behaviour, and verifies that the provider behaves as expected. The advantages Pact provides are:
-
-* The ability to develop the consumer (eg. a Javascript rich client UI) before the provider (eg. the JSON backend API).
-* The ability to drive out the requirements for your provider first, meaning you implement exactly and only what you need in the provider.
-* Well documented use cases ("Given ... a request for ... will return ...") that show exactly how a provider is being used.
-* The ability to see exactly which fields each consumer is interested in, allowing unused fields to be removed, and new fields to be added in the provider API without impacting a consumer. 
-* The ability to immediately see which consumers will be broken if a change is made to the provider API.
-* When using the [Pact Broker](https://github.com/bethesque/pact_broker), the ability to map the relationships between your services.
-
-### How does Pact differ from Webmock?
-
-Unlike Webmock:
-
-* Pact provides verification that the responses that have been stubbed are actually the responses that will be returned in the given conditions.
-* Pact runs a mock server in an actual process, rather than intercepting requests within the Ruby code, allowing Javascript rich UI clients to be tested in a browser.
-
-### How can I handle versioning?
-
-Consumer driven contracts to some extent allows you to do away with versioning. As long as all your contract tests pass, you should be able to deploy changes without versioning the API. If you need to make a breaking change to a provider, you can do it in a multiple step process - add the new fields/endpoints to the provider and deploy. Update the consumers to use the new fields/endpoints, then deploy. Remove the old fields/endpoints from the provider and deploy. At each step of the process, all the contract tests remain green.
-
-Using a [Pact Broker](https://github.com/bethesque/pact_broker), you can tag the production version of a pact when you make a release of a consumer. Then, any changes that you make to the provider can be checked agains the production version of the pact, as well as the latest version, to ensure backward compatiblity.
-
-If you need to support multiple versions of the provider API concurrently, then you will probably be specifying which version your consumer uses by setting a header, or using a different URL component. As these are actually different requests, the interactions can be verified in the same pact without any problems.
-
-### How can I verify a pact against a non-ruby provider?
-
-You can verify a pact against any running server, regardless of language, using [pact-provider-proxy](https://github.com/bethesque/pact-provider-proxy).
-
-There is also a JVM version of pact under development. Have a look at [pact-jvm](https://github.com/DiUS/pact-jvm), the that contains the equivalent of pact/consumer and pact/provider.
-
-### How can I create a pact for a consumer that is not ruby or on the JVM?
-
-Become famous, and write a pact-consumer library yourself! Then let us know about it so we can put a link to it in the documentation.
-
-### How can I specify hooks to be executed before/after all examples for pact:verify?
-
-Use the set_up and tear_down hooks in the provider state definition:
-
-```ruby
-
-Pact.provider_states_for "Some Consumer" do
-
-  set_up do
-    # Set up code here 
-  end
-
-  tear_down do
-    # tear down code here
-  end
-
-end
-```
-
-See https://www.relishapp.com/rspec/rspec-core/docs/hooks/filters for more information.
-
-### How can I run my consumer UI during my consumer specs so I can execute the tests using a browser?
-
-Eg. for Capybara tests
-
-```ruby
-Pact.service_consumer "My Consumer" do
-  app <your rack app here>
-  port 4321
-end
-```
-
-### Should the database or any other part of the provider be stubbed?
-
-The pact authors' experience with using pacts to test microservices has been that using the set_up hooks to populate the database, and running pact:verify with all the real provider code has worked very well, and gives us full confidence that the end to end scenario will work in the deployed code.
-
-However, if you have a large and complex provider, you might decide to stub some of your application code. You will definitly need to stub calls to downstream systems or to set up error scenarios. Make sure, if you stub, that you don't stub the code that actually parses the request and pulls the expected data out, because otherwise the consumer could be sending absolute rubbish, and the pact:verify won't fail because that code won't get executed. If the validation happens when you insert a record into the datasource, either don't stub anything, or rethink your validation code.
-
-### Why are the pacts generated and not static?
-
-* Maintainability: Pact is "contract by example", and the examples may involve large quantities of JSON. Maintaining the JSON files by hand would be both time consuming and error prone. By dynamically creating the pacts, you have the option to keep your expectations in fixture files, or to generate them from your domain (the recommended approach, as it ensures your domain objects and their JSON representations in the pacts can never get out of sync).
-
-* Provider states: Dynamically setting expectations on the mock server allows the use of provider states, meaning you can make the same request in different tests, with different expected responses. This allows you to properly test all the code paths in your consumer (eg. with different response codes, or different states of the resource). If all the interactions were loaded at start up from a static file, the mock server wouldn't know which response to return. See this [gist](https://gist.github.com/bethesque/7fa8947c107f92ace9a4) as an example.

data/documentation/provider-states.md

@@ -1,178 +0,0 @@
-# Provider States
-
-Provider states allow you to set up data on the provider before the interaction is run, so that it can make a response that matches what the consumer expects. It also allows the consumer to make the same request with different expected responses.
-
-Keep in mind that a provider state is all about the state of the *provider* (eg. what data is there, how it is going to handle a given response), not about the state of the consumer, or about what is in the request.
-
-The text in the provider state should make sense when you read it as follows (this is how the autogenerated documentation reads):
-
-
-Given **an alligator with the name Mary exists** \*   
-Upon receiving **a request to retrieve an alligator by name** \*\* from Some Consumer  
-With {"method" : "get", "path" : "/alligators/Mary" }  
-Some Provider will respond with { "status" : 200, ...}  
-
-\* This is the provider state  
-\*\* This is the request description  
-
-### Consumer codebase
-
-For example, some code that creates a pact in a consumer project might look like this:
-
-```ruby
-describe MyServiceProviderClient do
-
-  subject { MyServiceProviderClient.new }
-
-  describe "get_something" do
-    context "when a thing exists" do
-      before do
-        my_service.given("a thing exists").
-          upon_receiving("a request for a thing").with(method: 'get', path: '/thing').
-          will_respond_with(status: 200,
-            headers: { 'Content-Type' => 'application/json' },
-            body: { name: 'A small something'} )
-      end
-
-      it "returns a thing" do
-        expect(subject.get_something).to eq(SomethingModel.new('A small something'))
-      end
-    end
-
-    context "when a thing does not exist" do
-      before do
-        my_service.given("a thing does not exist").
-          upon_receiving("a request for a thing").with(method: 'get', path: '/thing').
-          will_respond_with(status: 404)
-      end
-
-      it "returns nil" do
-        expect(subject.get_something).to be_nil
-      end
-    end
-  end
-end
-```
-
-### Provider codebase
-
-To define service provider states that create the right data for the provider states described above, write the following in the service provider project. (The consumer name here must match the name of the consumer configured in your consumer project for it to correctly find these provider states.)
-
-```ruby
-# In /spec/service_consumers/provider_states_for_my_service_consumer.rb
-
-Pact.provider_states_for 'My Service Consumer' do
-
-  provider_state "a thing exists" do
-    set_up do
-      # Create a thing here using your framework of choice
-      # eg. Sequel.sqlite[:somethings].insert(name: "A small something")
-    end
-
-    tear_down do
-      # Any tear down steps to clean up your code
-    end
-  end
-
-  provider_state "a thing does not exist" do
-    no_op # If there's nothing to do because the state name is more for documentation purposes,
-          # you can use no_op to imply this.
-  end
-
-end
-```
-Require your provider states file in the `pact_helper.rb`
-
-```ruby
-# In /spec/service_consumers/pact_helper.rb
-
-require './spec/service_consumers/provider_states_for_my_service_consumer.rb'
-```
-
-### Base state
-
-To define code that should run before/after each interaction for a given consumer, regardless of whether a provider state is specified or not, define set_up/tear_down blocks with no wrapping provider_state.
-
-```ruby
-Pact.provider_states_for 'My Service Consumer' do
-
-  set_up do
-    # This will run before the set_up for provider state specified for the interaction.
-    # eg. create API user, set the expected basic auth details
-  end
-
-  tear_down do
-    # ...
-    # This will run after the tear_down for the specified provider state.
-  end
-end
-```
-
-### Global state
-
-Global state will be set up before consumer specific base state. Avoid using the global set up for creating data as it will make your tests brittle when more than one consumer exists.
-
-```ruby
-Pact.set_up do
-  # eg. start database cleaner transaction
-end
-
-Pact.tear_down do
-  # eg. clean database
-end
-```
-
-### Testing error responses
-
-It is important to test how your client will handle error responses.
-
-```ruby
-# Consumer codebase
-
-describe MyServiceProviderClient do
-
-  subject { MyServiceProviderClient.new }
-
-  describe "get_something" do
-
-    context "when an error occurs retrieving a thing" do
-      before do
-        my_service.given("an error occurs while retrieving a thing").
-          upon_receiving("a request for a thing").with(method: 'get', path: '/thing').
-          will_respond_with(
-            status: 500,
-            headers: { 'Content-Type' => 'application/json' },
-            body: { message: "An error occurred!" } )
-      end
-
-      it "raises an error" do
-        expect{ subject.get_something }.to raise_error /An error occurred!/
-      end
-
-    end
-  end
-end
-```
-
-```ruby
-# Provider codebase
-
-Pact.provider_states_for 'My Service Consumer' do
-  provider_state "an error occurs while retrieving a thing" do
-    set_up do
-      # Stubbing is ususally the easiest way to generate an error with predictable error text.
-      ThingRepository.stub(:find).and_raise("An error occurred!")
-    end
-  end
-end
-```
-
-### Including modules for use in set_up and tear_down
-
-Any modules included this way will be available in the set_up and tear_down blocks. One common use of this to include factory methods for setting up data so that the provider states file doesn't get too bloated.
-
-```ruby
-Pact.configure do | config |
-  config.include MyTestHelperMethods
-end
-```

data/documentation/raq.md

@@ -1,39 +0,0 @@
-# Rarely asked questions
-
-### How can I run a standalone mock server?
-
-By default, a mock service will be started automatically by the pact gem when running the consumer tests. A standalone mock service can be run locally and is useful for debugging purposes.
-
-```ruby
-Pact.service_consumer "My Service Consumer" do
-  has_pact_with "My Service Provider" do
-    mock_service :my_service_provider do
-      port <port-num>
-      standalone true #Tell the pact gem not to automatically start the mock service
-    end
-  end
-end
-```
-    $ bundle exec pact service -p <port-num>
-
-The service prints messages it recieves to stdout which can be really useful
-when diagnosing issues with pacts.
-
-### Doesn't this break HAL?
-
-Yes.
-
-### How can I specify multiple headers with the same name?
-
-RFC 2616 states that two headers with the same name can interpreted as a single header with two comma-separated values. This is the safest way to specify multiple headers with the same name, as Rack will only pass the last value through when they are defined separately (see https://github.com/rack/rack/issues/436).
-
-```ruby
-my_service_provider.
-  .given("it is RFC 2616 compliant")
-  .upon_receiving("a request with a header with commas separated values")
-  .with( method: :get, path: '/', headers: {'X-Request-Multival' => "A, B"} )
-  .will_respond_with(
-    status: 200, headers: {'X-Response-Multival' => "C, D"}
-  )
-
-```

data/documentation/terminology.md

@@ -1,25 +0,0 @@
-# Terminology
-
-### Service Consumer
-
-A component that initiates a HTTP request to another component (the service provider). Note that this does not depend on the way the data flows - whether it is a GET or a PUT/POST/PATCH, the consumer is the initiator of the HTTP request.
-
-### Service Provider
-
-A server that responds to an HTTP request from another component (the service consumer).
-
-### Mock Service Provider
-
-Used by tests in the consumer project to mock out the actual service provider, meaning that integration-like tests can be run without requiring the actual service provider to be available.
-
-### Pact file
-
-A file containing the JSON serialised requests and responses that were defined in the consumer tests.
-
-### Pact verification
-
-To verify a pact, the requests contained in a pact file are replayed against the provider code, and the responses returned are checked to ensure they match those expected in the pact file.
-
-### Provider state
-
-A name describing a "state" (like a fixture) that the provider should be in when a given request is replayed against it. Eg. "there is an alligator called Mary" or "there are no alligators". A provider state name is specified when writing the consumer specs, then, when the pact verification is set up in the provider, the same name will be used to identify the set up code block that should be run before the request is executed.

data/documentation/troubleshooting.md

@@ -1,4 +0,0 @@
-## Gotchas
-
-* Be aware when using the app from the config.ru file is used (the default option) that the Rack::Builder.parse_file seems to require files even if they have already been required, so make sure your boot files are idempotent.
-

data/documentation/verifying-pacts.md

@@ -1,106 +0,0 @@
-# Verifying pacts
-
-"Verifying a pact" is the second step of the Pact testing process. Each request in the pact file is replayed against 
-the provider, and the response that is returned is compared with the expected response in the pact file, and if the two
-match, then we know the consumer and provider are compatible.
-
-To verify a pact, we must:
-
-1. Configure the location of the pact to be verified. This can be a HTTP URL, or a local file system path.
-
-2. Set up the data for the [provider states](/documentation/provider-states.md).
-
-## Using rake pact:verify
-
-Using the pact:verify task is the default way to verify pacts. It is made available by requiring `'pact/tasks'` in your Rakefile.
-
-```ruby
-# In Rakefile
-require 'pact/tasks'
-```
-
-The pacts that will be verified by the pact:verify task are configured in the pact_helper.rb file in your provider codebase.
-The file must be called pact_helper.rb, however there is some flexibility in where it can be stored.
-The recommended place is `spec/service_consumers/pact_helper.rb`.
-
-To ensure that the latest version of the consumer pact is used each time, it is recommended that you either use a [Pact Broker](https://github.com/bethesque/pact_broker)
-or that you publish the pacts of a successful consumer build as artefacts in your CI system.
-
-```ruby
-# In specs/service_consumers/pact_helper.rb
-
-require 'pact/provider/rspec'
-
-Pact.service_provider "My Service Provider" do
-
-  app { MyApp.new } # Optional, loads app from config.ru by default
-
-  honours_pact_with 'My Service Consumer' do
-
-    # This example points to a local file, however, on a real project with a continuous
-    # integration box, you would publish your pacts as artifacts,
-    # and point the pact_uri to the pact published by the last successful build.
-
-    pact_uri '../path-to-your-consumer-project/specs/pacts/my_consumer-my_provider.json'
-  end
-
-  # This block is repeated for every pact that this provider should be verified against.
-  honours_pact_with 'Some other Service Consumer' do
-    ...
-  end  
-  
-end
-```
-
-## Using rake pact:verify:at
-
-You can also verify a pact at any arbitrary local or remote URL using the `pact:verify:at` task.
-This is useful when you are writing the consumer and provider concurrently, and wish to 
-
-    $ rake pact:verify:at[../path-to-your-consumer-project/specs/pacts/my_consumer-my_provider.json]
-    $ rake pact:verify:at[http://build-box/MyConsumerBuild/latestSuccessful/artifacts/my_consumer-my_provider.json]
-
-
-## Using a custom pact:verify task
-
-To make a shortcut task for verifying a pact an arbitrary URL that you do not want to verify as part of your normal pact:verify task,
-(eg. when you are developing the consumer and provider side by side, and want a shorter feedback cycle than can be provided by
-by your CI box) add the following to your Rakefile. The pact.uri may be a local file system path or a remote URL.
-
-```ruby
-# In Rakefile or /tasks/pact.rake
-
-# This creates a rake task that can be executed by running
-# $ rake pact:verify:dev
-
-Pact::VerificationTask.new(:dev) do | task |
-  task.uri '../path-to-your-consumer-project/specs/pacts/my_consumer-my_provider.json'
-end
-```
-
-## Running one pact at a time
-
-At some stage, you'll want to be able to run your specs one at a time while you implement each feature. At the bottom of the failed pact:verify output you will see the commands to rerun each failed interaction individually. A command to run just one interaction will look like this:
-
-    $ rake pact:verify PACT_DESCRIPTION="a request for something" PACT_PROVIDER_STATE="something exists"
-
-## Configuring RSpec
-
-Pact uses dynamically created RSpec specs to verify pacts. If you want to modify the behaviour of the underlying RSpec execution, you can:
-
-1. Set `task.rspec_opts` in your custom rake VerificationTask, the same way you would with a normal RSpec rake task declaration.
-1. Configure RSpec in the pact_helper using the normal `RSpec.configure` code.
-
-For future proofing though, try to use the provider state set_up/tear_down blocks where you can, because we may swap out RSpec for custom verification code in the future.
-
-## Pact Helper location
-
-The search paths for the pact_helper are:
-
-```ruby
-[
-  "spec/**/*service*consumer*/pact_helper.rb",
-  "spec/**/*consumer*/pact_helper.rb",
-  "spec/**/pact_helper.rb",
-  "**/pact_helper.rb"]
-```