pact 1.1.0.rc2 → 1.1.0.rc3

data/Rakefile

@@ -5,5 +5,5 @@ Dir.glob('lib/tasks/**/*.rake').each { |task| load task }
 Dir.glob('tasks/**/*.rake').each { |task| load task }
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => [:spec, :spec_with_active_support, 'pact:tests']
+task :default => [:spec, :spec_with_active_support, 'spec:standalone:pass', 'pact:tests']
 

data/documentation/README.md

@@ -0,0 +1,10 @@
+### Pact Documentation
+
+* Step by step instructions for getting started with pacts can be found in the project [README.md](/README.md#usage)
+* [Terminology](terminology.md)
+* [Configuration](configuration.md)
+* [Provider States](provider-states.md)
+* [Frequently asked questions](faq.md)
+* [Rarely asked questions](raq.md)
+* [Best practices](best-practices.md)
+* [Testing with pact diagram](Testing with pact.png)

data/documentation/best-practices.md

@@ -0,0 +1,33 @@
+# 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/configuration.md

@@ -0,0 +1,166 @@
+# Configuration
+
+## Menu
+
+#### Consumer and Provider configuration options
+* [diff_formatter](#diff_formatter)
+* [log_dir](#log_dir)
+* [logger](#logger)
+* [logger.level](#loggerlevel)
+
+#### Consumer only configuration options
+* [pact_dir](#pact_dir)
+* [doc_dir](#doc_dir)
+* [doc_generator](#doc_generator)
+* [pactfile_write_mode](#pactfile_write_mode)
+
+#### Provider only configuration options
+* [include](#include)
+
+## Consumer and Provider
+
+### log_dir
+
+```ruby
+Pact.configure do | config |
+  config.log_dir = './log'
+end
+```
+
+Default value: `./log`
+
+### logger
+
+```ruby
+Pact.configure do | config |
+  config.logger = Logger.new
+end
+```
+
+Default value: file logger to the configured log_dir.
+
+### logger.level
+
+```ruby
+Pact.configure do | config |
+  config.logger.level = Logger::INFO
+end
+```
+
+Default value: `Logger::DEBUG`
+
+### diff_formatter
+
+```ruby
+Pact.configure do | config |
+  config.diff_formatter = :list
+end
+```
+
+Default value: [:list](#list)
+
+Options: [:unix](#unix), [:list](#list), [:embedded](#embedded), [Custom Diff Formatter](#custom-diff-formatter)
+
+
+#### :unix
+<img src="diff_formatter_unix.png" width="700">
+
+#### :list
+
+<img src="diff_formatter_list.png" width="700">
+
+#### :embedded
+
+<img src="diff_formatter_embedded.png" width="700">
+
+
+#### Custom Diff Formatter
+
+Any object can be used that responds to `call`, accepting the argument `diff`.
+
+```ruby
+class MyCustomDiffFormatter
+
+  def self.call diff
+    ### Do stuff here
+  end
+
+end
+
+Pact.configure do | config |
+  config.diff_formatter = MyCustomDiffFormatter
+end
+```
+
+
+## Consumer
+
+### pact_dir
+
+```ruby
+Pact.configure do | config |
+  config.pact_dir = `./spec/pacts`
+end
+```
+
+Default value: `./spec/pacts`
+
+### doc_generator
+
+```ruby
+Pact.configure do | config |
+  config.doc_generator = :markdown
+end
+```
+
+Default value: none
+
+Options: [:markdown](#markdown), [Custom Doc Generator](#custom-doc-generator)
+
+#### :markdown
+
+Generates Markdown documentation based on the contents of the pact files created in this consumer. Files are created in `${Pact.configuration.doc_dir}/markdown`.
+
+#### Custom Doc Generator
+
+Any object can be used that responds to `call`, accepting the arguments `pact_dir` and `doc_dir`.
+
+```ruby
+Pact.configure do | config |
+  config.doc_generator = lambda{ | pact_dir, doc_dir | generate_some_docs(pact_dir, doc_dir) }
+end
+
+```
+
+#### doc_dir
+
+```ruby
+Pact.configure do | config |
+  config.doc_dir = './doc'
+end
+```
+
+Default value: `./doc`
+
+
+### pactfile_write_mode
+
+Default value: `:overwrite`
+Options: `:overwrite`, `:update`, `:smart`
+
+By default, the pact file will be overwritten (started from scratch) every time any rspec runs any spec using pacts. This means that if there are interactions that haven't been executed in the most recent rspec run, they are effectively removed from the pact file. If you have long running pact specs (e.g. they are generated using the browser with Capybara) and you are developing both consumer and provider in parallel, or trying to fix a broken interaction, it can be tedious to run all the specs at once. In this scenario, you can set the pactfile_write_mode to :update. This will keep all existing interactions, and update only the changed ones, identified by description and provider state. The down side of this is that if either of those fields change, the old interactions will not be removed from the pact file. As a middle path, you can set pactfile_write_mode to :smart. This will use :overwrite mode when running rake (as determined by a call to system using 'ps') and :update when running an individual spec.
+
+## Provider
+
+Pact uses RSpec and Rack::Test to create dynamic specs based on the pact files. RSpec configuration can be used to modify test behaviour if there is not an appropriate Pact feature. If you wish to use the same spec_helper.rb file as your unit tests, require it in the pact_helper.rb, but remember that the RSpec configurations for your unit tests may or may not be what you want for your pact verification tests.
+
+### include
+
+```ruby
+Pact.configure do | config |
+  config.include RSpec::Mocks::ExampleMethods
+end
+```
+
+To make modules available in the provider state set_up and tear_down blocks, include them in the configuration as shown below. One common use of this is to include RSpec::Mocks::ExampleMethods to make the `allow()` method available.
+

data/documentation/faq.md

@@ -1,6 +1,24 @@
 # Frequently asked questions
 
-## How can I verify a pact against a non-ruby provider?
+### 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 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).
 
@@ -12,13 +30,20 @@ Become famous, and write a pact-consumer library yourself! Then let us know abou
 
 ### How can I specify hooks to be executed before/after all examples for pact:verify?
 
-The pact:verify RSpec examples have the metadata `{:pact => :verify}` defined. You can add RSpec hooks using a filter as shown here:
+Use the set_up and tear_down hooks in the provider state definition:
 
 ```ruby
-RSpec.configure do | config |
-  config.before :each, :pact => :verify do
-    # Your code here
+
+Pact.provider_states_for "Some Consumer" do
+
+  set_up do
+    # Set up code here 
+  end
+
+  tear_down do
+    # tear down code here
   end
+
 end
 ```
 
@@ -41,5 +66,10 @@ This is a hotly debated issue.
 
 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. If you do, remember to add your own "verification" of your stubbed methods - write another test that will break if the behaviour of the stubbed methods changes.
+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. Make sure, when you stub, that you don't stub the code that actually parses the requests, because otherwise the consumer could be sending absolute rubbish, and you won't be checking it.
+
+### Why are the pacts generated and not hand coded?
+
+* 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 more than once, with different expected responses, allowing you to properly test all your code paths.

data/documentation/provider-states.md

@@ -0,0 +1,173 @@
+# 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.
+
+### 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
+
+To use RSpec's `allow()` syntax, include `RSpec::Mocks::ExampleMethods` in the configuration.
+
+```ruby
+Pact.configure do | config |
+  config.include RSpec::Mocks::ExampleMethods
+end
+```
+
+Any modules included this way will be available in the set_up and tear_down blocks eg. test data helper methods.
+
+```ruby
+Pact.configure do | config |
+  config.include MyFactoryMethods
+end
+```