pact 1.1.0.rc2 → 1.1.0.rc3

data/.gitignore

@@ -6,7 +6,6 @@
 InstalledFiles
 _yardoc
 coverage
-doc/
 lib/bundler/man
 pkg
 rdoc

data/CHANGELOG.md

@@ -1,6 +1,51 @@
 Do this to generate your change history
 
-    git log --date=relative --pretty=format:'  * %h - %s (%an, %ad)'
+    git log --pretty=format:'  * %h - %s (%an, %ad)'
+
+### 1.1.0.rc3 (28 April 2014)
+
+    * 41fa409 - Cleaned up consumer after spec failure message (Beth, Sun Apr 27 22:18:03 2014 +1000)
+    * 8593fa9 - Updated zoo-app example (Beth, Sun Apr 27 20:54:51 2014 +1000)
+    * 716e3a8 - Added standalone consumer spec and spec for VerificationGet (Beth, Thu Apr 24 10:15:17 2014 +1000)
+    * c0f9bc6 - Copied RSpec::Expectations::Differ to Pact::Matchers::Differ - safer than trying to override behaviour (Beth, Thu Apr 24 09:17:58 2014 +
+    * 0eeb032 - Changing default diff_formatter to unix (Beth, Thu Apr 24 08:19:15 2014 +1000)
+    * ace5d4d - Update README.md (bethesque, Wed Apr 23 20:59:24 2014 +1000)
+    * 24efef6 - Update configuration.md (bethesque, Wed Apr 23 20:51:00 2014 +1000)
+    * 2d862b7 - Update best-practices.md (bethesque, Wed Apr 23 07:33:01 2014 +1000)
+    * ff8dfd2 - Updated doco (Beth, Tue Apr 22 21:45:17 2014 +1000)
+    * 88e4572 - Moving best practices into its own file (Beth, Tue Apr 22 21:28:36 2014 +1000)
+    * 5a3b92c - Moving provider state documentation out of main README into it's own file. (Beth, Tue Apr 22 19:59:48 2014 +1000)
+    * 1d568c4 - Updated configuration documentation (Beth, Tue Apr 22 13:06:47 2014 +1000)
+    * be1412e - Added configuration documentation (Beth, Tue Apr 22 13:04:33 2014 +1000)
+    * 9f9d178 - Added HAL raq (Beth, Tue Apr 22 12:51:42 2014 +1000)
+    * d9b6479 - Renamed ListOfPathsFormatter to ListDiffFormatter (Beth, Tue Apr 22 12:48:57 2014 +1000)
+    * 6b82402 - Renamed NestedJsonDiffFormatter to EmbeddedDiffFormatter (Beth, Tue Apr 22 12:45:50 2014 +1000)
+    * def8afd - Merge branch 'master' into release-1.1.0 (bethesque, Tue Apr 22 09:13:41 2014 +1000)
+    * 789a471 - Added generated docs to zoo-app (bethesque, Tue Apr 15 17:20:08 2014 +1000)
+    * f5da7ab - Improved header match failure message (bethesque, Tue Apr 15 09:39:12 2014 +1000)
+    * 1179489 - Stopped RSpec turning failure message lines that should be white to red (bethesque, Mon Apr 14 21:41:55 2014 +1000)
+    * ddad510 - Added type and regexp matching output to ListOfPathsFormatter (bethesque, Mon Apr 14 13:43:08 2014 +1000)
+    * b007248 - Added class based matching output to plus_and_minus diff formatter (bethesque, Sat Apr 12 21:20:43 2014 +1000)
+    * f7910a1 - Swapped colored for term-ansicolor, as the colored mixins clash with other gems (bethesque, Sat Apr 12 20:37:57 2014 +1000)
+    * 93bfbdb - Fixing failing tests caused by JRuby inserting a blank line between the braces of an empty hash. Moved ActiveSupportSupport into shared
+    * da16f95 - Added after hook to allow customisation of Doc::Generator (bethesque, Sat Apr 12 18:46:04 2014 +1000)
+    * 85a6fe3 - Breaking up configuration files into separate files (bethesque, Sat Apr 12 11:21:56 2014 +1000)
+    * 7515360 - Merge branch 'doc' into release-1.1.0 (bethesque, Sat Apr 12 10:37:51 2014 +1000)
+    * 1200481 - Removed pact_gem key from pact fixtures (bethesque, Wed Apr 9 22:19:02 2014 +1000)
+    * 72d791b - Ordered rendering of keys in markdown (bethesque, Wed Apr 9 22:15:01 2014 +1000)
+    * 000b223 - Hiding headers and body from docs when they are empty (bethesque, Wed Apr 9 21:46:02 2014 +1000)
+    * 7f6ed91 - Changing request key ordering so it makes more sense when reading it (bethesque, Wed Apr 9 21:45:31 2014 +1000)
+    * 65054a8 - Added index rendering (bethesque, Wed Apr 9 19:38:55 2014 +1000)
+    * 9426565 - Refactoring generation code. Fixed rendering of interaction in markdown when ActiveSupport is loaded (bethesque, Wed Apr 9 18:20:53 2014 +100
+    * 73d0dbf - WIP refactoring generator code (bethesque, Wed Apr 9 17:03:14 2014 +1000)
+    * 7d1d07b - WIP tests and refactor doc generator (bethesque, Wed Apr 9 13:36:46 2014 +1000)
+
+### 1.0.39 (8 April 2014)
+
+* a034ab6 - Oh ActiveSupport, why??? Fixing to_json for difference indicators (bethesque, Mon Apr 7 17:26:10 2014 +1000)
+  * 1c7fa0d - Update faq.md (bethesque, Thu Apr 3 09:58:02 2014 +1100)
+  * 8cf5b57 - Update README.md (bethesque, Thu Mar 27 13:38:13 2014 +1100)
+  * 1c5fde9 - Preloading app before suite in pact:verify Ensures consistent behaviour between the first before/after each hooks (bethesque, Thu Mar 27 10:0
 
 ### 1.0.38 (24 March 2014)
 

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    pact (1.1.0.rc2)
+    pact (1.1.0.rc3)
       awesome_print (~> 1.1)
-      colored
       find_a_port (~> 1.0.1)
       json
       rack-test (~> 0.6.2)
       randexp (~> 0.1.7)
       rspec (~> 2.12)
+      term-ansicolor (~> 1.0)
       thor
       webrick
 
@@ -25,7 +25,6 @@ GEM
     atomic (1.1.14)
     awesome_print (1.2.0)
     coderay (1.0.9)
-    colored (1.2)
     crack (0.4.1)
       safe_yaml (~> 0.9.0)
     diff-lcs (1.2.4)
@@ -58,9 +57,12 @@ GEM
     rspec-mocks (2.14.3)
     safe_yaml (0.9.5)
     slop (3.4.6)
-    thor (0.18.1)
+    term-ansicolor (1.3.0)
+      tins (~> 1.0)
+    thor (0.19.1)
     thread_safe (0.1.3)
       atomic
+    tins (1.1.0)
     tzinfo (0.3.38)
     webmock (1.9.3)
       addressable (>= 2.2.7)

data/README.md

@@ -14,10 +14,9 @@ Travis CI Status: [![travis-ci.org Build Status](https://travis-ci.org/realestat
 * A service is mocked using an actual process running on a specified port, so javascript clients can be tested as easily as backend clients.
 * "Provider states" (similar to fixtures) allow the same request to be made with a different expected response.
 * Consumers specify only the fields they are interested in, allowing a provider to return more fields without breaking the pact. This allows a provider to have a different pact with a different consumer, and know which fields each cares about in a given response.
-* Expected interactions are verified to have actually occurred in the consumer specs.
-* The mocked responses are verified to be valid by replaying the interactions against the provider codebase.
-* Rake verification tasks allow a pacts at one or more URIs to be checked against a given service provider codebase.
+* Rake tasks allow pacts to be verified against a service provider codebase.
 * Different versions of a consumer/provider pairs can be easily tested against each other, allowing confidence when deploying new versions of each (see the pact_broker and pact_broker-client gems).
+* Autogenerated API documentation - need we say more?
 
 ## How does it work?
 
@@ -28,14 +27,15 @@ Travis CI Status: [![travis-ci.org Build Status](https://travis-ci.org/realestat
 ## Why is developing and testing with pacts better than using integration tests?
 
 * Faster execution.
-* No need to manage starting and stopping multiple processes.
 * Reliable responses from mock service provider reduce likelihood of flakey tests.
 * Only one component is being tested at a time, making the causes of test failures easier to identify.
 * Design of service provider is improved by considering first how the data is actually going to be used, rather than how it is most easily retrieved and serialised.
+* No need to manage starting, stopping and fixture set up for multiple applications during a test run.
 
-## Google users group
+## Contact
 
-https://groups.google.com/forum/#!forum/pact-support
+* Twitter: [@pact_up](https://twitter.com/pact_up)
+* Google users group: https://groups.google.com/forum/#!forum/pact-support
 
 ## Installation
 
@@ -47,10 +47,10 @@ Put it in your Gemfile. You know how.
 
 #### 1. Start with you model
 
-Imagine a model class that looks something like this. The attributes for a SomethingModel live on a remote server, and will need to be retrieved by an HTTP call.
+Imagine a model class that looks something like this. The attributes for a Something live on a remote server, and will need to be retrieved by an HTTP call.
 
 ```ruby
-class SomethingModel
+class Something
   attr_reader :name
 
   def initialize name
@@ -58,7 +58,7 @@ class SomethingModel
   end
 
   def == other
-    other.is_a?(SomethingModel) && other.name == name
+    other.is_a?(Something) && other.name == name
   end
 end
 ```
@@ -68,7 +68,6 @@ end
 Imagine a service provider client class that looks something like this.
 
 ```ruby
-
 class MyServiceProviderClient
   include HTTParty
   base_uri 'http://my-service'
@@ -77,7 +76,6 @@ class MyServiceProviderClient
     # Yet to be implemented because we're doing Test First Development...
   end
 end
-
 ```
 #### 3. Configure the mock server
 
@@ -114,26 +112,23 @@ describe MyServiceProviderClient, :pact => true do
   subject { MyServiceProviderClient.new }
 
   describe "get_something" do
+
     before do
-      my_service_provider.
-        .given("something exists")
-        .upon_receiving("a request for something")
-        .with( method: :get, path: '/something' )
-        .will_respond_with(
+      my_service_provider.given("something exists").
+        upon_receiving("a request for something").with(method: :get, path: '/something').
+        will_respond_with(
           status: 200,
-          headers: { 'Content-Type' => 'application/json' },
-          body: {name: 'A small something'}
-        )
+          headers: {'Content-Type' => 'application/json'},
+          body: {name: 'A small something'} )
     end
 
     it "returns a Something" do
-      expect(subject.get_something).to eq(SomethingModel.new('A small something'))
+      expect(subject.get_something).to eq(Something.new('A small something'))
     end
 
   end
 
 end
-
 ```
 
 #### 5. Run the specs
@@ -146,39 +141,45 @@ Of course, the above specs will fail because the client method is not implemente
 #### 6. Implement the client methods
 
 ```ruby
-
 class MyServiceProviderClient
   include HTTParty
   base_uri 'http://my-service'
 
   def get_something
     name = JSON.parse(self.class.get("/something").body)['name']
-    SomethingModel.new(name)
+    Something.new(name)
   end
 end
-
 ```
 
 #### 7. Run the specs again.
 
 Green! You now have a pact file that can be used to verify your expectations in the provider project.
-Now, rinse and repeat for ALL the likely status codes that may be returned (recommend 400, 404, 500 and 401/403 if there is authorisation.)
+Now, rinse and repeat for ALL the likely status codes that may be returned (we recommend 404, 500 and 401/403 if there is authorisation.)
 
 ### Service Provider project
 
 #### 1. Create the skeleton API classes
 
-Create your API class using the framework of your choice (e.g. Sinatra, Grape) - leave the methods unimplemented, we're doing Test First Develoment, remember?
+Create your API class using the framework of your choice - leave the methods unimplemented, we're doing Test First Develoment, remember?
 
 #### 2. Tell your provider that it needs to honour the pact file you made earlier
 
+Require "pact/tasks" in your Rakefile.
+
+```ruby
+# In Rakefile
+require 'pact/tasks'
+```
+
 Create a `pact_helper.rb` in your service provider project. The file must be called pact_helper.rb, however there is some flexibility in where it can be stored. The recommended place is `specs/service_consumers/pact_helper.rb`.
 
+See the [Provider](/documentation.md#provider) section of the Configuration documentation for more information.
+
 ```ruby
+# In specs/service_consumers/pact_helper.rb
+
 require 'pact/provider/rspec'
-# If you wish to use the same spec_helper file as your unit tests, require it here.
-# Otherwise, you can set up a separate RSpec configuration in this file just for pact:verify.
-require './spec_helper'
 
 Pact.service_provider "My Service Provider" do
 
@@ -193,14 +194,6 @@ Pact.service_provider "My Service Provider" do
     pact_uri '../path-to-your-consumer-project/specs/pacts/my_consumer-my_provider.json'
   end
 end
-
-```
-Require "pact/tasks" in your Rakefile. If the pact gem is in the test/development section of your Gemfile, you may want to put an env check around this so it doesn't load the pact tasks in prod.
-
-```ruby
-# In Rakefile
-
-require 'pact/tasks'
 ```
 
 #### 3. Run your failing specs
@@ -209,11 +202,13 @@ require 'pact/tasks'
 
 Congratulations! You now have a failing spec to develop against.
 
-#### 4. Implement your service provider
+At this 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"
 
-At this stage, you'll probably want to be able to run your specs one at a time while you implement. Define the environment variables PACT_DESCRIPTION and/or PACT_PROVIDER_STATE as so:
+#### 4. Implement enough to make your first interaction spec pass
 
-    $ PACT_DESCRIPTION="a request for something" PACT_PROVIDER_STATE="something exists" rake pact:verify
+Rinse and repeat.
 
 #### 5. Keep going til you're green
 
@@ -221,102 +216,9 @@ Yay! Your provider now honours the pact it has with your consumer. You can now h
 
 ### Using provider states
 
-Provider states allow different fixtures to be loaded on the provider to allow you to test the same request with different expected responses.
+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.
 
-For example, some code that creates the pact in a consumer project might look like this:
-
-```ruby
-my_service.
-   given("a thing exists").
-     upon_receiving("a request for a thing").
-        with(method: 'get', path: '/thing').
-          will_respond_with(status: 200, :body => {thing: "yay!"} )
-
-...
-
-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)
-
-        ...
-
-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, :body => {message: "An error occurred"}, :headers => { 'Content-Type' => 'application/json'} )
-```
-
-
-
-To define service provider states that create the right data for "a thing exists" and "a thing does not exist", 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 factory of choice
-    end
-
-    tear_down do
-      # Any tear down steps to clean up your code (or use RSpec.after(:each))
-    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
-
-  provider_state "an error occurs while retrieving a thing" do
-    set_up do
-      ThingRepository.stub(:find).and_raise("An error occurred!")
-    end
-  end
-end
-
-```
-
-```ruby
-# In /spec/service_consumers/pact_helper.rb
-
-require_relative 'provider_states_for_my_service_consumer.rb'
-```
-
-To define code that should run before/after each interaction, regardless of whether a provider state is specified or not:
-
-```ruby
-
-  Pact.provider_states_for 'My Service Consumer' do
-
-    set_up do
-      # eg. create API user, start database cleaner transaction
-    end
-
-    tear_down do
-      # eg. clean database
-    end
-  end
-
-```
-
-Or for global set up/tear down for all consumers:
-
-```ruby
-Pact.set_up do
-  # eg. start database cleaner transaction
-  # Avoid using the global set up for creating data as it will make your tests brittle.
-  # You don't want changes to one consumer pact to affect another one.
-end
-
-Pact.tear_down do
-  # eg. clean database
-end
-```
+Read more about provider states [here](/documentation/provider-states.md).
 
 ### Verifying pacts
 
@@ -338,64 +240,18 @@ Pact::VerificationTask.new(:dev) do | pact |
 end
 ```
 
-### Configuration
+## Configuration
 
-```ruby
-Pact.configure do | config |
-  config.pact_dir = "???" # Optional, default is ./spec/pacts
-  config.log_dir = "???" # Optional, default is ./log
-  config.logger = "??" # Optional, defaults to a file logger to the configured log_dir.
-  config.logger.level = Logger::DEBUG #By default this is INFO, bump this up to debug for more detailed logs
-  config.pactfile_write_mode = :ovewrite / :update / :smart # Optional. The default pactfile_write_mode is :overwrite. See notes in Advanced section for further information.
-end
-```
+See the [Configuration](/documentation/configuration.md) section of the documentation for options relating to thing like logging, diff formatting, and documentation generation.
 
 ## Pact best practices
 
-### In your consumer project
-
-#### Publish your pacts as artifacts on your CI machine
-
-This makes the pact available via URL, which your provider build can then use when it runs pact:verify.
-
-#### 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
-
-#### Use the pact artifact published by your consumer's CI build to verify the provider
-
-Configure the pact_uri in the Pact.service_provider block with the pact artifact URL of your last successful build. This way you're only verifying green builds. No point verifying a broken one.
-(Watch this space - pact-broker coming soon, so we don't have to use messy build box artifact URLs)
-
-#### 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.
-
-#### Stub calls to downstream systems
-
-Consider making a separate pact with the downstream system and using shared fixtures.
-
-#### Consider carefully whether to use the real database or stub calls
-
-You may choose not stub your database calls for pact:verify. This can be a good time for you to test your database integration if you have a simple application, however, for a complex one, you might want to carefully choose a point at which to stub calls.
+As in all things, there are good ways to implement Pacts, and there are not so good ways. Check out the [Best practices](/documentation/best-practices.md) section of the documentation to make sure you're not Pacting it Wrong.
 
 ## 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.
 
-## Advanced
-
-### Filtering the pact:verify specs
-
-To execute a subset of the specs when running any of the pact verification tasks, define the environment variables PACT_DESCRIPTION and/or PACT_PROVIDER_STATE.
-
-    $ PACT_DESCRIPTION="a request for something" PACT_PROVIDER_STATE="something exists" rake pact:verify
 
 See [Frequently Asked Questions](https://github.com/realestate-com-au/pact/blob/master/documentation/faq.md) and [Rarely Asked Questions](https://github.com/realestate-com-au/pact/blob/master/documentation/raq.md) and [Terminology](https://github.com/realestate-com-au/pact/blob/master/documentation/terminology.md) for more information.
 
@@ -413,13 +269,11 @@ See [Frequently Asked Questions](https://github.com/realestate-com-au/pact/blob/
 ## TODO
 
 Short term:
-- FIX EXAMPLE!!!
 - Support hash of query params
 
 Long term:
 - Provide more flexible matching (eg the keys should match, and the classes of the values should match, but the values of each key do not need to be equal). This is to make the pact verification less brittle.
 - Add XML support
-- Improve display of interaction diffs
 - Decouple Rspec from Pact and make rspec-pact gem for easy integration
 
 ## Contributing