rspec-given 2.1.0.beta.4 → 2.1.0.beta.5

data/Gemfile

@@ -1,7 +1,3 @@
 source 'https://rubygems.org'
 gem 'rspec', '>= 2.0'
 gem 'rake', '>= 0.9.2.2'
-
-group :test do
-  gem 'flexmock'
-end

data/Gemfile.lock

@@ -2,7 +2,6 @@ GEM
   remote: https://rubygems.org/
   specs:
     diff-lcs (1.1.3)
-    flexmock (1.0.2)
     rake (0.9.2.2)
     rspec (2.11.0)
       rspec-core (~> 2.11.0)
@@ -17,6 +16,5 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  flexmock
   rake (>= 0.9.2.2)
   rspec (>= 2.0)

data/README

@@ -1,6 +1,6 @@
 = rspec-given
 
-Covering rspec-given, version 2.1.0.beta.4.
+Covering rspec-given, version 2.1.0.beta.5.
 
 rspec-given is an RSpec extension to allow Given/When/Then notation in
 RSpec specifications.  It is a natural extension of the experimental
@@ -23,68 +23,70 @@ _rspec-given_ is ready for production use.
 
 Here is a specification written in the rspec-given framework:
 
-    require 'rspec/given'
-    require 'spec_helper'
-    require 'stack'
-    
-    describe Stack do
-      def stack_with(initial_contents)
-        stack = Stack.new
-        initial_contents.each do |item| stack.push(item) end
-        stack
-      end
-    
-      Given(:stack) { stack_with(initial_contents) }
-      Invariant { stack.empty?.should == (stack.depth == 0) }
-    
-      context "when empty" do
-        Given(:initial_contents) { [] }
-        Then { stack.depth.should == 0 }
-    
-        context "when pushing" do
-          When { stack.push(:an_item) }
-    
-          Then { stack.depth.should == 1 }
-          Then { stack.top.should == :an_item }
-        end
-    
-        context "when popping" do
-          When(:result) { stack.pop }
-          Then { result.should have_failed(Stack::UnderflowError, /empty/) }
-        end
-      end
-    
-      context "with one item" do
-        Given(:initial_contents) { [:an_item] }
-    
-        context "when popping" do
-          When(:pop_result) { stack.pop }
-    
-          Then { pop_result.should == :an_item }
-          Then { stack.depth.should == 0 }
-        end
-      end
-    
-      context "with several items" do
-        Given(:initial_contents) { [:second_item, :top_item] }
-        Given!(:original_depth) { stack.depth }
-    
-        context "when pushing" do
-          When { stack.push(:new_item) }
-    
-          Then { stack.top.should == :new_item }
-          Then { stack.depth.should == original_depth + 1 }
-        end
-    
-        context "when popping" do
-          When(:pop_result) { stack.pop }
-    
-          Then { pop_result.should == :top_item }
-          Then { stack.top.should == :second_item }
-          Then { stack.depth.should == original_depth - 1 }
-        end
-      end
+```ruby
+require 'rspec/given'
+require 'spec_helper'
+require 'stack'
+
+describe Stack do
+  def stack_with(initial_contents)
+    stack = Stack.new
+    initial_contents.each do |item| stack.push(item) end
+    stack
+  end
+
+  Given(:stack) { stack_with(initial_contents) }
+  Invariant { stack.empty?.should == (stack.depth == 0) }
+
+  context "when empty" do
+    Given(:initial_contents) { [] }
+    Then { stack.depth.should == 0 }
+
+    context "when pushing" do
+      When { stack.push(:an_item) }
+
+      Then { stack.depth.should == 1 }
+      Then { stack.top.should == :an_item }
+    end
+
+    context "when popping" do
+      When(:result) { stack.pop }
+      Then { result.should have_failed(Stack::UnderflowError, /empty/) }
+    end
+  end
+
+  context "with one item" do
+    Given(:initial_contents) { [:an_item] }
+
+    context "when popping" do
+      When(:pop_result) { stack.pop }
+
+      Then { pop_result.should == :an_item }
+      Then { stack.depth.should == 0 }
     end
+  end
+
+  context "with several items" do
+    Given(:initial_contents) { [:second_item, :top_item] }
+    Given!(:original_depth) { stack.depth }
+
+    context "when pushing" do
+      When { stack.push(:new_item) }
+
+      Then { stack.top.should == :new_item }
+      Then { stack.depth.should == original_depth + 1 }
+    end
+
+    context "when popping" do
+      When(:pop_result) { stack.pop }
+
+      Then { pop_result.should == :top_item }
+      Then { stack.top.should == :second_item }
+      Then { stack.depth.should == original_depth - 1 }
+    end
+  end
+end
+```
 
 Let's talk about the individual statements used in the Given
 framework.
@@ -121,68 +123,82 @@ preconditions running before inner preconditions.
 
 ==== Given examples:
 
-        Given(:stack) { Stack.new }
+```ruby
+    Given(:stack) { Stack.new }
+```
 
-The given block is lazily run if 'stack' is ever referenced in the
-test and the value of the block is bound to 'stack'.  The first
-reference to 'stack' in the specification will cause the code block to
-execute.  Futher references to 'stack' will reuse the previously
-generated value.
+The block for the given clause is lazily run if 'stack' is ever
+referenced in the test and the value of the block is bound to 'stack'.
+The first reference to 'stack' in the specification will cause the
+code block to execute. Futher references to 'stack' will reuse the
+previously generated value.
 
-        Given!(:original_size) { stack.size }
+```ruby
+    Given!(:original_size) { stack.size }
+```
 
 The code block is run unconditionally once before each test and the
 value of the block is bound to 'original_size'.  This form is useful
 when you want to record the value of something that might be affected
 by the When code.
 
-        Given { stack.clear }
+```ruby
+    Given { stack.clear }
+```
 
-The given block is run unconditionally once before each test.  This
-form of given is used for code that is executed for side effects.
+The block for the given clause is run unconditionally once before each
+test. This form of given is used for code that is executed for side
+effects.
 
 === When
 
-The _When_ block specifies the code to be tested ... oops, excuse me
+The _When_ clause specifies the code to be tested ... oops, excuse me
 ... specified.  After the preconditions in the given section are met,
 the when code block is run.
 
-There should only be one _When_ block for a given context. However, a
-_When_ in an outer context shoud be treated as a _Given_ in an inner
-context.  E.g.
-
-        context "outer context" do
-          When { code specified in the outer context }
-          Then { assert something about the outer context }
-    
-          context "inner context" do
-    
-            # At this point, the _When_ of the outer context
-            # should be treated as a _Given_ of the inner context
-    
-            When { code specified in the inner context }
-            Then { assert something about the inner context }
-          end
-        end
+There should not be more than one _When_ clause for a given direct
+context. However, a _When_ in an outer context shoud be treated as a
+_Given_ in an inner context. E.g.
+
+```ruby
+    context "outer context" do
+      When { code specified in the outer context }
+      Then { assert something about the outer context }
+
+      context "inner context" do
+
+        # At this point, the _When_ of the outer context
+        # should be treated as a _Given_ of the inner context
+
+        When { code specified in the inner context }
+        Then { assert something about the inner context }
+      end
+    end
+```
 
 ==== When examples:
 
-        When { stack.push(:item) }
+```ruby
+    When { stack.push(:item) }
+```
 
 The code block is executed once per test.  The effect of the _When{}_
 block is very similar to _Given{}_.  However, When is used to identify
 the particular code that is being specified in the current context or
 describe block.
 
-        When(:result) { stack.pop }
+```ruby
+    When(:result) { stack.pop }
+```
 
 The code block is executed once per test and the value of the code
 block is bound to 'result'.  Use this form when the code under test
 returns a value that you wish to interrogate in the _Then_ code.
 
-If an exception occurs during the execution of the When block, the
-exception is caught and a failure object is bound to 'result'. The
-failure can be checked in a then block with the 'have_failed' matcher.
+If an exception occurs during the execution of the block for the When
+clause, the exception is caught and a failure object is bound to
+'result'. The failure can be checked in a then block with the
+'have_failed' matcher.
 
 The failure object will rethrow the captured exception if anything
 other than have_failed matcher is used on the failure object.
@@ -191,8 +207,10 @@ For example, if the stack is empty when it is popped, then it is
 reasonable for pop to raise an UnderflowError. This is how you might
 specify that behavior:
 
-        When(:result) { stack.pop }
-        Then { result.should have_failed(UnderflowError, /empty/) }
+```ruby
+    When(:result) { stack.pop }
+    Then { result.should have_failed(UnderflowError, /empty/) }
+```
 
 Note that the arguments to the 'have_failed' matcher are the same as
 those given to the standard RSpec matcher 'raise_error'.
@@ -204,7 +222,13 @@ then conditions must be true after the code under test (the _When_
 clause) is run.
 
 The code in the block of a _Then_ clause should be a single _should_
-assertion. Code in _Then_ blocks should not have any side effects.
+assertion. Code in _Then_ clauses should not have any side effects.
+
+Let me repeat that: <b>_Then_ clauses should not have any side
+effects!</b> _Then_ clauses with side effects are erroneous. _Then_
+clauses need to be idempotent, so that running them once, twice, a
+hundred times, or never does not change the state of the program. (The
+same is true of _And_ clauses).
 
 In RSpec terms, a _Then_ clause forms a RSpec Example that runs in the
 context of an Example Group (defined by a describe or context clause).
@@ -214,23 +238,28 @@ there will be no examples to be run for that group. If all the
 assertions in an example group are done via Invariants, then the group
 should use an empty _Then_ clause, like this:
 
-        Then { }
+```ruby
+    Then { }
+```
 
 ==== Then examples:
 
-        Then { stack.should be_empty }
+```ruby
+    Then { stack.should be_empty }
+```
 
-After the related _When_ block is run, the stack should be empty.  If
-it is not empty, the test will fail.
+After the related block for the _When_ clause is run, the stack should
+be empty. If it is not empty, the test will fail.
 
 === And
 
-The _And_ clause is similar to _Then_, but do not form their own RSpec
-examples. This means that _And_ clauses reuse the setup from the
+The _And_ clause is similar to _Then_, but does not form its own RSpec
+example. This means that _And_ clauses reuse the setup from a sibling
 _Then_ clause. Using a single _Then_ an multiple _And_ clauses in an
 example group means the setup for that group is run only once (for the
-_Then_ clause). This can be a significant speed savings where the
-setup for an example group is expensive.
+_Then_ clause) and reused for all the _And_s. This can be a
+significant speed savings where the setup for an example group is
+expensive.
 
 Some things to keep in mind about _And_ clauses:
 
@@ -239,7 +268,7 @@ Some things to keep in mind about _And_ clauses:
    is an error.
 
 1. The code in the _And_ clause is run immediately after the first
-   _Then_ of an example group.
+   (executed) _Then_ of an example group.
 
 1. And assertion failures in a _Then_ clause or a _And_ clause will
    cause all the subsequent _And_ clauses to be skipped.
@@ -250,6 +279,10 @@ Some things to keep in mind about _And_ clauses:
    appear in the documentation, html or textmate formats (options
    -fhtml, -fdoc, or -ftextmate).
 
+1. Like _Then_ clauses, _And_ clauses must be idempotent. That means
+   they should not execute any code that changes global program state.
+   (See the section on the _Then_ clause).
+
 The choice to use an _And_ clause is primarily a speed consideration.
 If an example group has expensive setup and there are a lot of _Then_
 clauses, then choosing to make some of the _Then_ clauses into _And_
@@ -258,24 +291,27 @@ stick with _Then_ clauses.
 
 ==== Then/And examples:
 
-      Then { pop_result.should == :top_item }           # Required
-      And  { stack.top.should == :second_item }         # No Setup rerun
-      And  { stack.depth.should == original_depth - 1 } # ... for these
+```ruby
+  Then { pop_result.should == :top_item }           # Required
+  And  { stack.top.should == :second_item }         # No Setup rerun
+  And  { stack.depth.should == original_depth - 1 } # ... for these
+```
 
 === Invariant
 
-The _Invariant_ block is a new idea that doesn't have an analog in
-RSpec or Test::Unit.  The invariant allows you specify things that
-must always be true.  In the stack example, <tt>empty?</tt> is defined
-in term of <tt>size</tt>.  Whenever <tt>size</tt> is 0,
-<tt>empty?</tt> should be true.  Whenever <tt>size</tt> is non-zero,
-<tt>empty?</tt> should be false.
+The _Invariant_ clause is a new idea that doesn't have an analog in
+RSpec or Test::Unit. The invariant allows you specify things that must
+always be true (or at least always be true in the scope of the
+invariant). In the stack example, <tt>empty?</tt> is defined in term
+of <tt>size</tt>. Whenever <tt>size</tt> is 0, <tt>empty?</tt> should
+be true. Whenever <tt>size</tt> is non-zero, <tt>empty?</tt> should be
+false.
 
-You can conceptually think of an _Invariant_ block as a _Then_ block
+You can conceptually think of an _Invariant_ clause as a _Then_ block
 that automatically gets added to every _Then_ within its scope.
 
-Invariants nested within a context only apply to the _Then_ blocks in
-that context.
+Invariants nested within a context only apply to the _Then_ clauses
+that are in the scope of that context.
 
 Invariants that reference a _Given_ precondition accessor must only be
 used in contexts that define that accessor.
@@ -297,7 +333,9 @@ the examples to produce better looking output. If you don't care about
 the pretty output and wish to disable source code caching
 unconditionally, then add the following line to your spec helper file:
 
-        RSpec::Given.source_caching_disabled = true
+```ruby
+    RSpec::Given.source_caching_disabled = true
+```
 
 = Future Directions
 
@@ -305,14 +343,18 @@ I really like the way the Given framework is working out.  I feel my
 tests are much more like specifications when I use it.  However, I'm
 not entirely happy with it.
 
-I would like to remove the need for the ".should" in all the
-_Then_ blocks.  In other words, instead of saying:
+I would like to remove the need for the ".should" in all the _Then_
+clauses. In other words, instead of saying:
 
+```ruby
     Then { x.should == y }
+```
 
 we could say:
 
+```ruby
     Then { x == y }
+```
 
 I think the [wrong assertion library](http://rubygems.org/gems/wrong)
 has laid some groundwork in this area.

data/README.md

@@ -1,6 +1,6 @@
 # rspec-given
 
-Covering rspec-given, version 2.1.0.beta.4.
+Covering rspec-given, version 2.1.0.beta.5.
 
 rspec-given is an RSpec extension to allow Given/When/Then notation in
 RSpec specifications.  It is a natural extension of the experimental
@@ -23,7 +23,7 @@ _rspec-given_ is ready for production use.
 
 Here is a specification written in the rspec-given framework:
 
-<pre>
+```ruby
 require 'rspec/given'
 require 'spec_helper'
 require 'stack'
@@ -86,7 +86,7 @@ describe Stack do
     end
   end
 end
-</pre>
+```
 
 Let's talk about the individual statements used in the Given
 framework.
@@ -123,43 +123,44 @@ preconditions running before inner preconditions.
 
 #### Given examples:
 
-<pre>
+```ruby
     Given(:stack) { Stack.new }
-</pre>
+```
 
-The given block is lazily run if 'stack' is ever referenced in the
-test and the value of the block is bound to 'stack'.  The first
-reference to 'stack' in the specification will cause the code block to
-execute.  Futher references to 'stack' will reuse the previously
-generated value.
+The block for the given clause is lazily run if 'stack' is ever
+referenced in the test and the value of the block is bound to 'stack'.
+The first reference to 'stack' in the specification will cause the
+code block to execute. Futher references to 'stack' will reuse the
+previously generated value.
 
-<pre>
+```ruby
     Given!(:original_size) { stack.size }
-</pre>
+```
 
 The code block is run unconditionally once before each test and the
 value of the block is bound to 'original_size'.  This form is useful
 when you want to record the value of something that might be affected
 by the When code.
 
-<pre>
+```ruby
     Given { stack.clear }
-</pre>
+```
 
-The given block is run unconditionally once before each test.  This
-form of given is used for code that is executed for side effects.
+The block for the given clause is run unconditionally once before each
+test. This form of given is used for code that is executed for side
+effects.
 
 ### When
 
-The _When_ block specifies the code to be tested ... oops, excuse me
+The _When_ clause specifies the code to be tested ... oops, excuse me
 ... specified.  After the preconditions in the given section are met,
 the when code block is run.
 
-There should only be one _When_ block for a given context. However, a
-_When_ in an outer context shoud be treated as a _Given_ in an inner
-context.  E.g.
+There should not be more than one _When_ clause for a given direct
+context. However, a _When_ in an outer context shoud be treated as a
+_Given_ in an inner context. E.g.
 
-<pre>
+```ruby
     context "outer context" do
       When { code specified in the outer context }
       Then { assert something about the outer context }
@@ -173,30 +174,31 @@ context.  E.g.
         Then { assert something about the inner context }
       end
     end
-</pre>
+```
 
 #### When examples:
 
-<pre>
+```ruby
     When { stack.push(:item) }
-</pre>
+```
 
 The code block is executed once per test.  The effect of the _When{}_
 block is very similar to _Given{}_.  However, When is used to identify
 the particular code that is being specified in the current context or
 describe block.
 
-<pre>
+```ruby
     When(:result) { stack.pop }
-</pre>
+```
 
 The code block is executed once per test and the value of the code
 block is bound to 'result'.  Use this form when the code under test
 returns a value that you wish to interrogate in the _Then_ code.
 
-If an exception occurs during the execution of the When block, the
-exception is caught and a failure object is bound to 'result'. The
-failure can be checked in a then block with the 'have_failed' matcher.
+If an exception occurs during the execution of the block for the When
+clause, the exception is caught and a failure object is bound to
+'result'. The failure can be checked in a then block with the
+'have_failed' matcher.
 
 The failure object will rethrow the captured exception if anything
 other than have_failed matcher is used on the failure object.
@@ -205,10 +207,10 @@ For example, if the stack is empty when it is popped, then it is
 reasonable for pop to raise an UnderflowError. This is how you might
 specify that behavior:
 
-<pre>
+```ruby
     When(:result) { stack.pop }
     Then { result.should have_failed(UnderflowError, /empty/) }
-</pre>
+```
 
 Note that the arguments to the 'have_failed' matcher are the same as
 those given to the standard RSpec matcher 'raise_error'.
@@ -220,7 +222,13 @@ then conditions must be true after the code under test (the _When_
 clause) is run.
 
 The code in the block of a _Then_ clause should be a single _should_
-assertion. Code in _Then_ blocks should not have any side effects.
+assertion. Code in _Then_ clauses should not have any side effects.
+
+Let me repeat that: <b>_Then_ clauses should not have any side
+effects!</b> _Then_ clauses with side effects are erroneous. _Then_
+clauses need to be idempotent, so that running them once, twice, a
+hundred times, or never does not change the state of the program. (The
+same is true of _And_ clauses).
 
 In RSpec terms, a _Then_ clause forms a RSpec Example that runs in the
 context of an Example Group (defined by a describe or context clause).
@@ -230,27 +238,28 @@ there will be no examples to be run for that group. If all the
 assertions in an example group are done via Invariants, then the group
 should use an empty _Then_ clause, like this:
 
-<pre>
+```ruby
     Then { }
-</pre>
+```
 
 #### Then examples:
 
-<pre>
+```ruby
     Then { stack.should be_empty }
-</pre>
+```
 
-After the related _When_ block is run, the stack should be empty.  If
-it is not empty, the test will fail.
+After the related block for the _When_ clause is run, the stack should
+be empty. If it is not empty, the test will fail.
 
 ### And
 
-The _And_ clause is similar to _Then_, but do not form their own RSpec
-examples. This means that _And_ clauses reuse the setup from the
+The _And_ clause is similar to _Then_, but does not form its own RSpec
+example. This means that _And_ clauses reuse the setup from a sibling
 _Then_ clause. Using a single _Then_ an multiple _And_ clauses in an
 example group means the setup for that group is run only once (for the
-_Then_ clause). This can be a significant speed savings where the
-setup for an example group is expensive.
+_Then_ clause) and reused for all the _And_s. This can be a
+significant speed savings where the setup for an example group is
+expensive.
 
 Some things to keep in mind about _And_ clauses:
 
@@ -259,7 +268,7 @@ Some things to keep in mind about _And_ clauses:
    is an error.
 
 1. The code in the _And_ clause is run immediately after the first
-   _Then_ of an example group.
+   (executed) _Then_ of an example group.
 
 1. And assertion failures in a _Then_ clause or a _And_ clause will
    cause all the subsequent _And_ clauses to be skipped.
@@ -270,6 +279,10 @@ Some things to keep in mind about _And_ clauses:
    appear in the documentation, html or textmate formats (options
    -fhtml, -fdoc, or -ftextmate).
 
+1. Like _Then_ clauses, _And_ clauses must be idempotent. That means
+   they should not execute any code that changes global program state.
+   (See the section on the _Then_ clause).
+
 The choice to use an _And_ clause is primarily a speed consideration.
 If an example group has expensive setup and there are a lot of _Then_
 clauses, then choosing to make some of the _Then_ clauses into _And_
@@ -278,26 +291,27 @@ stick with _Then_ clauses.
 
 #### Then/And examples:
 
-<pre>
+```ruby
   Then { pop_result.should == :top_item }           # Required
   And  { stack.top.should == :second_item }         # No Setup rerun
   And  { stack.depth.should == original_depth - 1 } # ... for these
-</pre>
+```
 
 ### Invariant
 
-The _Invariant_ block is a new idea that doesn't have an analog in
-RSpec or Test::Unit.  The invariant allows you specify things that
-must always be true.  In the stack example, <tt>empty?</tt> is defined
-in term of <tt>size</tt>.  Whenever <tt>size</tt> is 0,
-<tt>empty?</tt> should be true.  Whenever <tt>size</tt> is non-zero,
-<tt>empty?</tt> should be false.
+The _Invariant_ clause is a new idea that doesn't have an analog in
+RSpec or Test::Unit. The invariant allows you specify things that must
+always be true (or at least always be true in the scope of the
+invariant). In the stack example, <tt>empty?</tt> is defined in term
+of <tt>size</tt>. Whenever <tt>size</tt> is 0, <tt>empty?</tt> should
+be true. Whenever <tt>size</tt> is non-zero, <tt>empty?</tt> should be
+false.
 
-You can conceptually think of an _Invariant_ block as a _Then_ block
+You can conceptually think of an _Invariant_ clause as a _Then_ block
 that automatically gets added to every _Then_ within its scope.
 
-Invariants nested within a context only apply to the _Then_ blocks in
-that context.
+Invariants nested within a context only apply to the _Then_ clauses
+that are in the scope of that context.
 
 Invariants that reference a _Given_ precondition accessor must only be
 used in contexts that define that accessor.
@@ -319,9 +333,9 @@ the examples to produce better looking output. If you don't care about
 the pretty output and wish to disable source code caching
 unconditionally, then add the following line to your spec helper file:
 
-<pre>
+```ruby
     RSpec::Given.source_caching_disabled = true
-</pre>
+```
 
 # Future Directions
 
@@ -329,14 +343,18 @@ I really like the way the Given framework is working out.  I feel my
 tests are much more like specifications when I use it.  However, I'm
 not entirely happy with it.
 
-I would like to remove the need for the ".should" in all the
-_Then_ blocks.  In other words, instead of saying:
+I would like to remove the need for the ".should" in all the _Then_
+clauses. In other words, instead of saying:
 
+```ruby
     Then { x.should == y }
+```
 
 we could say:
 
+```ruby
     Then { x == y }
+```
 
 I think the [wrong assertion library](http://rubygems.org/gems/wrong)
 has laid some groundwork in this area.