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

data/README

@@ -0,0 +1,325 @@
+= rspec-given
+
+Covering rspec-given, version 2.1.0.beta.4.
+
+rspec-given is an RSpec extension to allow Given/When/Then notation in
+RSpec specifications.  It is a natural extension of the experimental
+work done on the Given framework.  It turns out that 90% of the Given
+framework can be trivially implemented on top of RSpec.
+
+= Why Given/When/Then
+
+RSpec has done a great job of making specifications more readable for
+humans.  However, I really like the given / when / then nature of
+Cucumber stories and would like to follow the same structure in my
+unit tests.  rspec-given allows a simple given/when/then structure
+RSpec specifications.
+
+== Status
+
+_rspec-given_ is ready for production use.
+
+== Example
+
+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
+    end
+
+Let's talk about the individual statements used in the Given
+framework.
+
+=== Given
+
+The _Given_ section specifies a starting point, a set of preconditions
+that must be true before the code under test is allowed to be run.  In
+standard test frameworks the preconditions are established with a
+combination of setup methods (or :before actions in RSpec) and code in
+the test.
+
+In the example code above the preconditions are started with _Given_
+statements.  A top level _Given_ (that applies to the entire describe
+block) says that one of the preconditions is that there is a stack
+with some initial contents.
+
+Note that initial contents are not specified in the top level describe
+block, but are given in each of the nested contexts.  By pushing the
+definition of "initial_contents" into the nested contexts, we can vary
+them as needed for that particular context.
+
+A precondition in the form "Given(:var) {...}" creates an accessor
+method named "var".  The accessor is lazily initialized by the code
+block.  If you want a non-lazy given, use "Given!(:var) {...}".
+
+A precondition in the form "Given {...}" just executes the code block
+for side effects.  Since there is no accessor, the code block is
+executed immediately (i.e. no lazy evaluation).
+
+The preconditions are run in order of definition.  Nested contexts
+will inherit the preconditions from the enclosing context, with out
+preconditions running before inner preconditions.
+
+==== Given examples:
+
+        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.
+
+        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 }
+
+The given block 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
+... 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
+
+==== When examples:
+
+        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 }
+
+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.
+
+The failure object will rethrow the captured exception if anything
+other than have_failed matcher is used on the failure object.
+
+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/) }
+
+Note that the arguments to the 'have_failed' matcher are the same as
+those given to the standard RSpec matcher 'raise_error'.
+
+=== Then
+
+The _Then_ clauses are the postconditions of the specification. These
+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.
+
+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).
+
+Each Example Group must have at least one _Then_ clause, otherwise
+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 { }
+
+==== Then examples:
+
+        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.
+
+=== 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
+_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.
+
+Some things to keep in mind about _And_ clauses:
+
+1. There must be at least one _Then_ in the example group and it must
+   be declared before the _And_ clauses. Forgetting the _Then_ clause
+   is an error.
+
+1. The code in the _And_ clause is run immediately after the first
+   _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.
+
+1. Since _And_ clauses do not form their own RSpec examples, they are
+   not represented in the formatted output of RSpec. That means _And_
+   clauses do not produce dots in the Progress format, nor do they
+   appear in the documentation, html or textmate formats (options
+   -fhtml, -fdoc, or -ftextmate).
+
+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_
+clause will speed up the spec. Otherwise it is probably better to
+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
+
+=== 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.
+
+You can conceptually think of an _Invariant_ block 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 that reference a _Given_ precondition accessor must only be
+used in contexts that define that accessor.
+
+Notes:
+
+1. Since Invariants do not form their own RSpec example, they are not
+   represented in the RSpec formatted output (e.g. the '--format html'
+   option).
+
+== Configuration
+
+Just require 'rspec/given' in the spec helper of your project and it
+is ready to go.
+
+If the RSpec format option document, html or textmate are chosen,
+RSpec/Given will automatically add addition source code information to
+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
+
+= Future Directions
+
+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:
+
+    Then { x.should == y }
+
+we could say:
+
+    Then { x == y }
+
+I think the [wrong assertion library](http://rubygems.org/gems/wrong)
+has laid some groundwork in this area.
+
+= Links
+
+* Github: [https://github.com/jimweirich/rspec-given](https://github.com/jimweirich/rspec-given)
+* Clone URL: git://github.com/jimweirich/rspec-given.git
+* Bug/Issue Reporting: [https://github.com/jimweirich/rspec-given/issues](https://github.com/jimweirich/rspec-given/issues)
+* Continuous Integration: [http://travis-ci.org/#!/jimweirich/rspec-given](http://travis-ci.org/#!/jimweirich/rspec-given)

data/README.md

@@ -1,6 +1,6 @@
 # rspec-given
 
-Covering rspec-given, version 2.1.0.beta.1.
+Covering rspec-given, version 2.1.0.beta.4.
 
 rspec-given is an RSpec extension to allow Given/When/Then notation in
 RSpec specifications.  It is a natural extension of the experimental
@@ -46,7 +46,7 @@ describe Stack do
       When { stack.push(:an_item) }
 
       Then { stack.depth.should == 1 }
-      Also { stack.top.should == :an_item }
+      Then { stack.top.should == :an_item }
     end
 
     context "when popping" do
@@ -62,7 +62,7 @@ describe Stack do
       When(:pop_result) { stack.pop }
 
       Then { pop_result.should == :an_item }
-      Also { stack.depth.should == 0 }
+      Then { stack.depth.should == 0 }
     end
   end
 
@@ -215,13 +215,25 @@ those given to the standard RSpec matcher 'raise_error'.
 
 ### Then
 
-The _Then_ sections are the postconditions of the specification. These
+The _Then_ clauses are the postconditions of the specification. These
 then conditions must be true after the code under test (the _When_
-block) is run.
+clause) is run.
 
-The code in the _Then_ block should be a single _should_
+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.
 
+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).
+
+Each Example Group must have at least one _Then_ clause, otherwise
+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>
+    Then { }
+</pre>
+
 #### Then examples:
 
 <pre>
@@ -231,6 +243,47 @@ assertion. Code in _Then_ blocks should not have any side effects.
 After the related _When_ block 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
+_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.
+
+Some things to keep in mind about _And_ clauses:
+
+1. There must be at least one _Then_ in the example group and it must
+   be declared before the _And_ clauses. Forgetting the _Then_ clause
+   is an error.
+
+1. The code in the _And_ clause is run immediately after the first
+   _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.
+
+1. Since _And_ clauses do not form their own RSpec examples, they are
+   not represented in the formatted output of RSpec. That means _And_
+   clauses do not produce dots in the Progress format, nor do they
+   appear in the documentation, html or textmate formats (options
+   -fhtml, -fdoc, or -ftextmate).
+
+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_
+clause will speed up the spec. Otherwise it is probably better to
+stick with _Then_ clauses.
+
+#### Then/And examples:
+
+<pre>
+  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
@@ -249,6 +302,27 @@ that context.
 Invariants that reference a _Given_ precondition accessor must only be
 used in contexts that define that accessor.
 
+Notes:
+
+1. Since Invariants do not form their own RSpec example, they are not
+   represented in the RSpec formatted output (e.g. the '--format html'
+   option).
+
+## Configuration
+
+Just require 'rspec/given' in the spec helper of your project and it
+is ready to go.
+
+If the RSpec format option document, html or textmate are chosen,
+RSpec/Given will automatically add addition source code information to
+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>
+    RSpec::Given.source_caching_disabled = true
+</pre>
+
 # Future Directions
 
 I really like the way the Given framework is working out.  I feel my

data/README.old

@@ -0,0 +1,349 @@
+# rspec-given
+
+Covering rspec-given, version 2.1.0.beta.3.
+
+rspec-given is an RSpec extension to allow Given/When/Then notation in
+RSpec specifications.  It is a natural extension of the experimental
+work done on the Given framework.  It turns out that 90% of the Given
+framework can be trivially implemented on top of RSpec.
+
+# Why Given/When/Then
+
+RSpec has done a great job of making specifications more readable for
+humans.  However, I really like the given / when / then nature of
+Cucumber stories and would like to follow the same structure in my
+unit tests.  rspec-given allows a simple given/when/then structure
+RSpec specifications.
+
+## Status
+
+_rspec-given_ is ready for production use.
+
+## Example
+
+Here is a specification written in the rspec-given framework:
+
+<pre>
+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 }
+      And  { 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 }
+      And  { 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 }
+      And  { stack.top.should == :second_item }
+      And  { stack.depth.should == original_depth - 1 }
+    end
+  end
+end
+</pre>
+
+Let's talk about the individual statements used in the Given
+framework.
+
+### Given
+
+The _Given_ section specifies a starting point, a set of preconditions
+that must be true before the code under test is allowed to be run.  In
+standard test frameworks the preconditions are established with a
+combination of setup methods (or :before actions in RSpec) and code in
+the test.
+
+In the example code above the preconditions are started with _Given_
+statements.  A top level _Given_ (that applies to the entire describe
+block) says that one of the preconditions is that there is a stack
+with some initial contents.
+
+Note that initial contents are not specified in the top level describe
+block, but are given in each of the nested contexts.  By pushing the
+definition of "initial_contents" into the nested contexts, we can vary
+them as needed for that particular context.
+
+A precondition in the form "Given(:var) {...}" creates an accessor
+method named "var".  The accessor is lazily initialized by the code
+block.  If you want a non-lazy given, use "Given!(:var) {...}".
+
+A precondition in the form "Given {...}" just executes the code block
+for side effects.  Since there is no accessor, the code block is
+executed immediately (i.e. no lazy evaluation).
+
+The preconditions are run in order of definition.  Nested contexts
+will inherit the preconditions from the enclosing context, with out
+preconditions running before inner preconditions.
+
+#### Given examples:
+
+<pre>
+    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.
+
+<pre>
+    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>
+    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.
+
+### When
+
+The _When_ block 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.
+
+<pre>
+    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
+</pre>
+
+#### When examples:
+
+<pre>
+    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>
+    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.
+
+The failure object will rethrow the captured exception if anything
+other than have_failed matcher is used on the failure object.
+
+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>
+    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'.
+
+### Then
+
+The _Then_ clauses are the postconditions of the specification. These
+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.
+
+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).
+
+Each Example Group must have at least one _Then_ clause, otherwise
+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>
+    Then { }
+</pre>
+
+#### Then examples:
+
+<pre>
+    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.
+
+### 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
+_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.
+
+Some things to keep in mind about _And_ clauses:
+
+1. There must be at least one _Then_ in the example group and it must
+   be declared before the _And_ clauses. Forgetting the _Then_ clause
+   is an error.
+
+1. The code in the _And_ clause is run immediately after the first
+   _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.
+
+1. Since _And_ clauses do not form their own RSpec examples, they are
+   not represented in the formatted output of RSpec. That means _And_
+   clauses do not produce dots in the Progress format, nor do they
+   appear in the documentation, html or textmate formats (options
+   -fhtml, -fdoc, or -ftextmate).
+
+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_
+clause will speed up the spec. Otherwise it is probably better to
+stick with _Then_ clauses.
+
+#### Then/And examples:
+
+<pre>
+  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.
+
+You can conceptually think of an _Invariant_ block 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 that reference a _Given_ precondition accessor must only be
+used in contexts that define that accessor.
+
+Notes:
+
+1. Since Invariants do not form their own RSpec example, they are not
+   represented in the RSpec formatted output (e.g. the '--format html'
+   option).
+
+## Configuration
+
+Just require 'rspec/given' in the spec helper of your project and it
+is ready to go.
+
+If the RSpec format option document, html or textmate are chosen,
+RSpec/Given will automatically add addition source code information to
+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>
+    RSpec::Given.source_caching_disabled = true
+</pre>
+
+# Future Directions
+
+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:
+
+    Then { x.should == y }
+
+we could say:
+
+    Then { x == y }
+
+I think the [wrong assertion library](http://rubygems.org/gems/wrong)
+has laid some groundwork in this area.
+
+# Links
+
+* Github: [https://github.com/jimweirich/rspec-given](https://github.com/jimweirich/rspec-given)
+* Clone URL: git://github.com/jimweirich/rspec-given.git
+* Bug/Issue Reporting: [https://github.com/jimweirich/rspec-given/issues](https://github.com/jimweirich/rspec-given/issues)
+* Continuous Integration: [http://travis-ci.org/#!/jimweirich/rspec-given](http://travis-ci.org/#!/jimweirich/rspec-given)

data/examples/integration/and_spec.rb

@@ -0,0 +1,48 @@
+require 'rspec/given'
+require 'spec_helper'
+
+describe "And" do
+  Given(:info) { [] }
+  Given(:mock) { flexmock("mock") }
+
+  describe "And is called after Then" do
+    Given { mock.should_receive(:and_ran).once }
+    Then { info << "T" }
+    And {
+      info.should == ["T"]
+      mock.and_ran
+    }
+  end
+
+  describe "And is called only once with multiple Thens" do
+    Then { info << "T" }
+    Then { info << "T2" }
+    And { info.should == ["T"] }
+  end
+
+  describe "Inherited Ands are not run" do
+    Then { info << "T-OUTER" }
+    And { info << "A-OUTER" }
+    And { info.should == ["T-OUTER", "A-OUTER"] }
+
+    context "inner" do
+      Then { info << "T-INNER" }
+      And { info << "A-INNER" }
+      And { info.should == ["T-INNER", "A-INNER"] }
+    end
+  end
+
+  describe "Ands require a Then" do
+    begin
+      And { }
+    rescue StandardError => ex
+      @message = ex.message
+    end
+
+    it "should define a message" do
+      message = self.class.instance_eval { @message }
+      message.should =~ /and.*without.*then/i
+    end
+  end
+
+end

data/examples/stack/stack_spec.rb

@@ -20,7 +20,7 @@ describe Stack do
       When { stack.push(:an_item) }
 
       Then { stack.depth.should == 1 }
-      Also { stack.top.should == :an_item }
+      Then { stack.top.should == :an_item }
     end
 
     context "when popping" do
@@ -36,7 +36,7 @@ describe Stack do
       When(:pop_result) { stack.pop }
 
       Then { pop_result.should == :an_item }
-      Also { stack.depth.should == 0 }
+      Then { stack.depth.should == 0 }
     end
   end
 

data/lib/rspec/given.rb

@@ -13,6 +13,8 @@ if RSpec::Given.using_old_rspec?
   require 'rspec/given/rspec1_given'
 else
   require 'rspec/given/version'
+  require 'rspec/given/module_methods'
+  require 'rspec/given/line_cache'
   require 'rspec/given/extensions'
   require 'rspec/given/configure'
   require 'rspec/given/failure'

data/lib/rspec/given/configure.rb

@@ -1,9 +1,12 @@
 require 'rspec'
 require 'rspec/given/extensions'
 require 'rspec/given/have_failed'
+require 'rspec/given/module_methods'
 
 RSpec.configure do |c|
   c.extend(RSpec::Given::ClassExtensions)
   c.include(RSpec::Given::InstanceExtensions)
   c.include(RSpec::Given::HaveFailed)
+
+  RSpec::Given.detect_formatters(c)
 end

data/lib/rspec/given/extensions.rb

@@ -1,4 +1,5 @@
 require 'rspec/given/failure'
+require 'rspec/given/module_methods'
 
 module RSpec
   module Given
@@ -31,12 +32,12 @@ module RSpec
         end
       end
 
-      def _rg_check_alsos  # :nodoc:
-        return if self.class._rg_context_info[:also_ran]
-        self.class._rg_alsos.each do |block|
+      def _rg_check_ands  # :nodoc:
+        return if self.class._rg_context_info[:and_ran]
+        self.class._rg_and_blocks.each do |block|
           instance_eval(&block)
         end
-        self.class._rg_context_info[:also_ran] = true
+        self.class._rg_context_info[:and_ran] = true
       end
 
       # Implement the run-time semantics of the Then clause.
@@ -44,7 +45,7 @@ module RSpec
         _rg_establish_givens
         _rg_check_invariants
         instance_eval(&block)
-        _rg_check_alsos
+        _rg_check_ands
       end
     end
 
@@ -62,14 +63,18 @@ module RSpec
         @_rg_invariants ||= []
       end
 
-      def _rg_alsos
-        @_rg_alsos ||= []
+      def _rg_and_blocks
+        @_rg_and_blocks ||= []
       end
 
       def _rg_context_info
         @_rg_contet_info ||= {}
       end
 
+      def _rg_cache
+        @_rg_cache ||= LineCache.new
+      end
+
       # Trigger the evaluation of a Given! block by referencing its
       # name.
       def _rg_trigger_given(name) # :nodoc:
@@ -161,7 +166,13 @@ module RSpec
         b = block.binding
         file = eval "__FILE__", b
         line = eval "__LINE__", b
-        eval %{specify do _rg_then(&block) end}, binding, file, line
+        description = _rg_cache.line(file, line) unless RSpec::Given.source_caching_disabled
+        if description
+          cmd = "it(description)"
+        else
+          cmd = "specify"
+        end
+        eval %{#{cmd} do _rg_then(&block) end}, binding, file, line
         _rg_context_info[:then_defined] = true
       end
 
@@ -171,9 +182,9 @@ module RSpec
         _rg_invariants << block
       end
 
-      def Also(&block)
-        fail "Also defined without a Then" unless _rg_context_info[:then_defined]
-        _rg_alsos << block
+      def And(&block)
+        fail "And defined without a Then" unless _rg_context_info[:then_defined]
+        _rg_and_blocks << block
       end
     end
   end

data/lib/rspec/given/line_cache.rb

@@ -0,0 +1,34 @@
+module RSpec
+  module Given
+    class LineCache
+      def initialize
+        @lines = {}
+      end
+
+      def line(file_name, line)
+        lines = get_lines(file_name)
+        extract_lines_from(lines, line-1)
+      end
+
+      private
+
+      def extract_lines_from(lines, index)
+        result = lines[index]
+        if result =~ /\{ *$/
+          result =~ /^( *)[^ ]/
+          leading_spaces = $1
+          indent = leading_spaces.size
+          begin
+            index += 1
+            result << lines[index]
+          end while lines[index] =~ /^#{leading_spaces} /
+        end
+        result
+      end
+
+      def get_lines(file_name)
+        @lines[file_name] ||= open(file_name) { |f| f.readlines }
+      end
+    end
+  end
+end

data/lib/rspec/given/module_methods.rb

@@ -0,0 +1,16 @@
+module RSpec
+  module Given
+    def self.source_caching_disabled
+      @_rg_source_caching_disabled
+    end
+
+    def self.source_caching_disabled=(value)
+      @_rg_source_caching_disabled = value
+    end
+
+    def self.detect_formatters(c)
+      format_active = c.formatters.any? { |f| f.class.name !~ /ProgressFormatter/ }
+      RSpec::Given.source_caching_disabled = ! format_active
+    end
+  end
+end

data/lib/rspec/given/version.rb

@@ -5,7 +5,7 @@ module RSpec
       VERSION_MINOR = 1,
       VERSION_BUILD = 0,
       VERSION_BETA  = 'beta',
-      VERSION_BETANUM = '1'
+      VERSION_BETANUM = '4'
     ]
     VERSION = VERSION_NUMBERS.join(".")
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-given
 version: !ruby/object:Gem::Version
-  version: 2.1.0.beta.1
+  version: 2.1.0.beta.4
   prerelease: 6
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-12 00:00:00.000000000 Z
+date: 2012-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70227316783380 !ruby/object:Gem::Requirement
+  requirement: &70145913512260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>'
@@ -21,10 +21,10 @@ dependencies:
         version: 1.2.8
   type: :runtime
   prerelease: false
-  version_requirements: *70227316783380
+  version_requirements: *70145913512260
 - !ruby/object:Gem::Dependency
   name: bluecloth
-  requirement: &70227316782580 !ruby/object:Gem::Requirement
+  requirement: &70145913511800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70227316782580
+  version_requirements: *70145913511800
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &70227316781360 !ruby/object:Gem::Requirement
+  requirement: &70145913511100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>'
@@ -43,7 +43,7 @@ dependencies:
         version: 2.4.2
   type: :development
   prerelease: false
-  version_requirements: *70227316781360
+  version_requirements: *70145913511100
 description: ! 'Given is an RSpec extension that allows explicit definition of the
 
   pre and post-conditions for code under test.
@@ -58,16 +58,20 @@ files:
 - Gemfile.lock
 - MIT-LICENSE
 - Rakefile
+- README
 - README.md
+- README.old
 - lib/rspec-given.rb
 - lib/rspec/given/configure.rb
 - lib/rspec/given/extensions.rb
 - lib/rspec/given/failure.rb
 - lib/rspec/given/have_failed.rb
+- lib/rspec/given/line_cache.rb
+- lib/rspec/given/module_methods.rb
 - lib/rspec/given/rspec1_given.rb
 - lib/rspec/given/version.rb
 - lib/rspec/given.rb
-- examples/integration/also_spec.rb
+- examples/integration/and_spec.rb
 - examples/integration/focused_line_spec.rb
 - examples/integration/given_spec.rb
 - examples/integration/invariant_spec.rb

data/examples/integration/also_spec.rb

@@ -1,48 +0,0 @@
-require 'rspec/given'
-require 'spec_helper'
-
-describe "Also" do
-  Given(:info) { [] }
-  Given(:mock) { flexmock("mock") }
-
-  describe "Also is called after Then" do
-    Given { mock.should_receive(:also_ran).once }
-    Then { info << "T" }
-    Also {
-      info.should == ["T"]
-      mock.also_ran
-    }
-  end
-
-  describe "Also is called only once with multiple Thens" do
-    Then { info << "T" }
-    Then { info << "T2" }
-    Also { info.should == ["T"] }
-  end
-
-  describe "Inherited Alsos are not run" do
-    Then { info << "T-OUTER" }
-    Also { info << "A-OUTER" }
-    Also { info.should == ["T-OUTER", "A-OUTER"] }
-
-    context "inner" do
-      Then { info << "T-INNER" }
-      Also { info << "A-INNER" }
-      Also { info.should == ["T-INNER", "A-INNER"] }
-    end
-  end
-
-  describe "Alsos require a Then" do
-    begin
-      Also { }
-    rescue StandardError => ex
-      @message = ex.message
-    end
-
-    it "should define a message" do
-      message = self.class.instance_eval { @message }
-      message.should =~ /also.*without.*then/i
-    end
-  end
-
-end