pact 1.0.38 → 1.0.39

data/CHANGELOG.md

@@ -1,6 +1,13 @@
 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.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,7 +1,7 @@
 PATH
   remote: .
   specs:
-    pact (1.0.38)
+    pact (1.0.39)
       awesome_print (~> 1.1)
       colored
       find_a_port (~> 1.0.1)
@@ -58,7 +58,7 @@ GEM
     rspec-mocks (2.14.3)
     safe_yaml (0.9.5)
     slop (3.4.6)
-    thor (0.18.1)
+    thor (0.19.1)
     thread_safe (0.1.3)
       atomic
     tzinfo (0.3.38)

data/README.md

@@ -28,14 +28,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
 
@@ -172,13 +173,22 @@ Create your API class using the framework of your choice (e.g. Sinatra, Grape) -
 
 #### 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`.
 
 ```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.
+# If you wish to use the same spec_helper file as your unit tests, require it here, but remember that the RSpec
 # 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
 
@@ -195,13 +205,7 @@ Pact.service_provider "My Service Provider" do
 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 +213,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:
 
-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:
+    $ rake pact:verify PACT_DESCRIPTION="a request for something" PACT_PROVIDER_STATE="something exists" 
 
-    $ PACT_DESCRIPTION="a request for something" PACT_PROVIDER_STATE="something exists" rake pact:verify
+#### 4. Implement enough to make your first interaction spec pass
+
+Rinse and repeat.
 
 #### 5. Keep going til you're green
 
@@ -249,8 +255,6 @@ my_service.
         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.)
 
 
@@ -274,6 +278,7 @@ 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
@@ -377,13 +382,13 @@ Configure the pact_uri in the Pact.service_provider block with the pact artifact
 
 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
+#### In pact:verify on the provider, only stub layers beneath where contents of the request body are extracted
 
-Consider making a separate pact with the downstream system and using shared fixtures.
+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.
 
-#### Consider carefully whether to use the real database or stub calls
+#### Stub calls to downstream systems
 
-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.
+Consider making a separate pact with the downstream system and using shared fixtures.
 
 ## Gotchas
 

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/lib/pact/consumer_contract/active_support_support.rb

@@ -43,5 +43,9 @@ module Pact
       end
     end
 
+    def remove_unicode json
+      json.gsub(/\\u([0-9A-Za-z]{4})/) {|s| [$1.to_i(16)].pack("U")}
+    end
+
   end
 end

data/lib/pact/matchers/difference_indicator.rb

@@ -0,0 +1,26 @@
+require 'pact/consumer_contract/active_support_support'
+
+module Pact
+  class DifferenceIndicator
+
+    include ActiveSupportSupport
+
+    def == other
+      other.is_a? self.class
+    end
+
+    def eql? other
+      self == other
+    end
+
+    def to_json options = {}
+      remove_unicode as_json.to_json(options)
+    end
+
+    def as_json options = {}
+      to_s
+    end
+
+  end
+
+end

data/lib/pact/matchers/index_not_found.rb

@@ -1,21 +1,12 @@
+require 'pact/matchers/difference_indicator'
+
 module Pact
-  class IndexNotFound
-    def == other
-      other.is_a? IndexNotFound
-    end
+  class IndexNotFound < Pact::DifferenceIndicator
 
     def to_s
       "<index not found>"
     end
 
-    def to_json options = {}
-      as_json.to_json options
-    end
-
-    def as_json options = {}
-      to_s
-    end
-
     def empty?
       true
     end

data/lib/pact/matchers/unexpected_index.rb

@@ -1,21 +1,11 @@
-module Pact
-  class UnexpectedIndex
+require 'pact/matchers/difference_indicator'
 
-    def == other
-      other.is_a? UnexpectedIndex
-    end
+module Pact
+  class UnexpectedIndex < Pact::DifferenceIndicator
 
     def to_s
       '<index not to exist>'
     end
 
-    def as_json options = {}
-      to_s
-    end
-
-    def to_json opts = {}
-      as_json.to_json options
-    end
-
   end
 end

data/lib/pact/matchers/unexpected_key.rb

@@ -1,20 +1,11 @@
-module Pact
-  class UnexpectedKey
+require 'pact/matchers/difference_indicator'
 
-    def == other
-      other.is_a? UnexpectedKey
-    end
+module Pact
+  class UnexpectedKey < Pact::DifferenceIndicator
 
     def to_s
       '<key not to exist>'
     end
 
-    def as_json options = {}
-      to_s
-    end
-
-    def to_json opts = {}
-      as_json.to_json options
-    end
   end
 end

data/lib/pact/provider/pact_spec_runner.rb

@@ -90,6 +90,14 @@ module Pact
         config.add_formatter Pact::Provider::RSpec::Formatter
         config.add_formatter Pact::Provider::RSpec::SilentJsonFormatter
 
+        config.before(:suite) do
+          # Preload app before suite so the classes loaded in memory are consistent for
+          # before :each and after :each hooks.
+          # Otherwise the app and all its dependencies are loaded between the first before :each
+          # and the first after :each, leading to inconsistent behaviour
+          # (eg. with database_cleaner transactions)
+          Pact.configuration.provider.app
+        end
       end
 
       def run_specs

data/lib/pact/shared/key_not_found.rb

@@ -1,25 +1,12 @@
-module Pact
-  class KeyNotFound
-    def == other
-      other.is_a? KeyNotFound
-    end
+require 'pact/matchers/difference_indicator'
 
-    def eql? other
-      self == other
-    end
+module Pact
+  class KeyNotFound < Pact::DifferenceIndicator
 
     def to_s
       "<key not found>"
     end
 
-    def as_json options={}
-      to_s
-    end
-
-    def to_json options = {}
-      as_json.to_json options
-    end
-
     def empty?
       true
     end

data/lib/pact/version.rb

@@ -1,3 +1,3 @@
 module Pact
-  VERSION = "1.0.38"
+  VERSION = "1.0.39"
 end

data/spec/lib/pact/matchers/index_not_found_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+require 'pact/matchers/index_not_found'
+
+module Pact
+  describe IndexNotFound do
+
+    describe "#as_json" do
+      it "returns a string representation of the object" do
+        expect(subject.as_json).to eq subject.to_s
+      end
+    end
+
+    describe "#to_json" do
+      it "serialises the object to JSON" do
+        expect(subject.to_json).to eq "\"#{subject.to_s}\""
+      end
+    end
+
+  end
+
+end

data/spec/lib/pact/matchers/unexpected_index_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+require 'pact/matchers/unexpected_index'
+
+module Pact
+  describe UnexpectedIndex do
+
+    describe "#as_json" do
+      it "returns a string representation of the object" do
+        expect(subject.as_json).to eq subject.to_s
+      end
+    end
+
+    describe "#to_json" do
+      it "serialises the object to JSON" do
+        expect(subject.to_json).to eq "\"#{subject.to_s}\""
+      end
+    end
+
+  end
+end

data/spec/lib/pact/matchers/unexpected_key_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+require 'pact/matchers/unexpected_key'
+
+module Pact
+  describe UnexpectedKey do
+
+    describe "#as_json" do
+      it "returns a string representation of the object" do
+        expect(subject.as_json).to eq subject.to_s
+      end
+    end
+
+    describe "#to_json" do
+      it "serialises the object to JSON" do
+        expect(subject.to_json).to eq "\"#{subject.to_s}\""
+      end
+    end
+
+  end
+end

data/spec/lib/pact/shared/key_not_found_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+require 'pact/shared/key_not_found'
+
+module Pact
+  describe KeyNotFound do
+
+    describe "#as_json" do
+      it "returns a string representation of the object" do
+        expect(subject.as_json).to eq subject.to_s
+      end
+    end
+
+    describe "#to_json" do
+      it "serialises the object to JSON" do
+        expect(subject.to_json).to eq "\"#{subject.to_s}\""
+      end
+    end
+
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pact
 version: !ruby/object:Gem::Version
-  version: 1.0.38
+  version: 1.0.39
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-23 00:00:00.000000000 Z
+date: 2014-04-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: randexp
@@ -361,6 +361,7 @@ files:
 - lib/pact/logging.rb
 - lib/pact/matchers.rb
 - lib/pact/matchers/diff_decorator.rb
+- lib/pact/matchers/difference_indicator.rb
 - lib/pact/matchers/index_not_found.rb
 - lib/pact/matchers/matchers.rb
 - lib/pact/matchers/unexpected_index.rb
@@ -425,7 +426,10 @@ files:
 - spec/lib/pact/consumer_contract/interaction_spec.rb
 - spec/lib/pact/consumer_contract/request_spec.rb
 - spec/lib/pact/matchers/diff_decorator_spec.rb
+- spec/lib/pact/matchers/index_not_found_spec.rb
 - spec/lib/pact/matchers/matchers_spec.rb
+- spec/lib/pact/matchers/unexpected_index_spec.rb
+- spec/lib/pact/matchers/unexpected_key_spec.rb
 - spec/lib/pact/provider/configuration_spec.rb
 - spec/lib/pact/provider/pact_helper_locator_spec.rb
 - spec/lib/pact/provider/pact_spec_runner_spec.rb
@@ -438,6 +442,7 @@ files:
 - spec/lib/pact/provider/world_spec.rb
 - spec/lib/pact/reification_spec.rb
 - spec/lib/pact/shared/dsl_spec.rb
+- spec/lib/pact/shared/key_not_found_spec.rb
 - spec/lib/pact/something_like_spec.rb
 - spec/lib/pact/tasks/task_helper_spec.rb
 - spec/lib/pact/term_spec.rb
@@ -474,7 +479,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1671674810832384181
+      hash: 780584884635013301
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -483,7 +488,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1671674810832384181
+      hash: 780584884635013301
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -518,7 +523,10 @@ test_files:
 - spec/lib/pact/consumer_contract/interaction_spec.rb
 - spec/lib/pact/consumer_contract/request_spec.rb
 - spec/lib/pact/matchers/diff_decorator_spec.rb
+- spec/lib/pact/matchers/index_not_found_spec.rb
 - spec/lib/pact/matchers/matchers_spec.rb
+- spec/lib/pact/matchers/unexpected_index_spec.rb
+- spec/lib/pact/matchers/unexpected_key_spec.rb
 - spec/lib/pact/provider/configuration_spec.rb
 - spec/lib/pact/provider/pact_helper_locator_spec.rb
 - spec/lib/pact/provider/pact_spec_runner_spec.rb
@@ -531,6 +539,7 @@ test_files:
 - spec/lib/pact/provider/world_spec.rb
 - spec/lib/pact/reification_spec.rb
 - spec/lib/pact/shared/dsl_spec.rb
+- spec/lib/pact/shared/key_not_found_spec.rb
 - spec/lib/pact/something_like_spec.rb
 - spec/lib/pact/tasks/task_helper_spec.rb
 - spec/lib/pact/term_spec.rb