contractinator 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 82f22e805bf00d746ae493dcc5883c3b45ebca24
-  data.tar.gz: 26d67acb7d34eb94747b4c29e61540d8c40b4a64
+  metadata.gz: 69be59e1842cf4087e1ee9456c6d141d9852ef0d
+  data.tar.gz: 468e293c29177cdec380a0263726eff3b8f2b8a0
 SHA512:
-  metadata.gz: dd252cb859d7fd464cce2beac517242a8e3cdb0a9218bb0fece97d2062e4812005483718d75e58f90f54f3e03bfd96b01151a8599e6c6e949076e1e7a4f3af1a
-  data.tar.gz: 829da3795a63aa5c3417b701bd94c67f20ea2e43b216d2feeff7ad51b6a3c212c41ab97c18cdca1ca0fb8ce39ec1d5ffbfb8e9046d88aa646033d0919f6ffbb2
+  metadata.gz: 3666016479f67cf80c348b634ce2bf35ae44c1a2a6008594d204fc260ad7dd524b685a950c970584cef5fb2d542564c5277570e5d97a2bed0ab56eeae6e3e135
+  data.tar.gz: 1dfa070f7b1799d6cf9fd24d8be034751a4d8b16f8206db4f7ac2630108a615d4cd463675b458c000b77c497fd835c77ad12ab18c84135d37f1da2170db25136

data/README.md

@@ -1,9 +1,5 @@
 # Contractinator
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/contractinator`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -19,10 +15,100 @@ And then execute:
 Or install it yourself as:
 
     $ gem install contractinator
+    
+Then inform RSpec that you'd like to use contractinator by adding something like the following to your spec_helper.rb
+
+```
+require 'contractinator'
+
+RSpec.configure do |config|
+  config.include Contractinator::ContractHelpers
+
+  # By default contractinator extends rspec's test doubles.
+  # You don't have to use rspec's doubles TODO: explain how
+  # to use other mocks.
+  config.mock_with :rspec
+  
+  # After the suite is done, warn the user about all the
+  # unbalanced contracts. 
+  config.after(:suite) do
+    puts
+    puts Contractinator::Contract.messages
+    puts
+    puts "#{Contractinator::Contract.fulfilled_set.count} fulfilled contracts"
+  end
+end
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+### Creating a Contract
+There are several ways to document a provider's behavior. The easiest is to use the `stipulate` and `agree` matchers.
+
+In the spec for a consumer, for example a rails controller, you might have
+
+```
+it 'assigns a new entry' do
+  stipulate(Entry).must receive(:new).and_return(entry)
+  get :new
+  expect(response).to be_success
+  expect(assigns[:entry]).to eq(entry)
+end
+```
+
+This sets the expectation that Entry.new will be called, and stubs it out to return `entry`. Now you should get a warning in your rspec output that looks like this:
+
+```
+unfulfilled contract 'Entry.new -> entry'
+   at spec/controllers/entries_controller_spec.rb:45:in `block (3 levels) in <top (required)>'
+```
+
+The next step is to make sure that contract is fulfilled by something. So we'll switch over to the model spec
+
+```
+describe '.new' do
+  it { agree(Entry, :new).will be_a(Entry) }
+end
+```
+
+This calls new on Entry and asserts that it is_a Entry, and fulfills a contract of the form `Entry.new -> entry`. Since this matches the one from above, your spec output won't show the unmatched on anymore, but will increment the fulfilled contracts message.
+
+### Less straight-forward contracts
+Not every contract in an application is so easy to specify. For example, a view spec which assigns a local variable has an agreement with a controller to assign that variable. Some other matchers available:
+
+```
+assign_contract('entries#new', :entry, entry)
+flash_contract('entries#create', :notice, 'Great Success!') if flash_enabled
+```
+
+In these two cases, the method both does the side effect (assigning a variable for a view spec or setting a flash message), and also creates a matching contract. There isn't a corresponding fulfillment matcher for anything else yet, so you have to fulfill them manually. I do this like so, in my controller spec:
+
+```
+describe 'get :new' do
+  it { fulfills 'entries#new assign @entry'   }
+  it do 
+  	# actual test which reflects this fulfillment
+  end
+end
+```
+
+### Free-form contracts
+Sometimes I think of things that need a contract that I have no matchers for, and all I really want is a smart comment. I'm using this for a routing contract relationship now. In that case, you can do this:
+
+```
+ # this is a contract that might be created
+ # by a link in a view spec for example
+ Contractinator::Contract.require("get / routes")
+
+```
+
+And fulfill it with
+
+```
+it { fulfills('get / routes') }
+```
+
+All that matters for the contract to be fulfilled is that the string matches, so in this case contractinator is almost acting as merely a smart comment.
 
 ## Development
 

data/lib/contractinator/contract_helpers.rb

@@ -8,6 +8,10 @@ module Contractinator
       ContractAdapter.new(dbl, self)
     end
 
+    def contract(string)
+      Contractinator::Contract.require(string)
+    end
+
     def inject_contract(controller, name, dbl)
       dbl_name = fmt_dbl(dbl).to_s.classify
       Contractinator::Contract.require(

data/lib/contractinator/version.rb

@@ -1,3 +1,3 @@
 module Contractinator
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: contractinator
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Ehren Murdick