rspec-given 1.3.0 → 1.3.1

data/README.md

@@ -15,51 +15,31 @@ RSpec specifications.
 
 ## Status
 
-rspec-given is quite usable at the moment, although is is lacking
-several features.
+_rspec-given_ is ready for production use.
 
-* Invariants are not supported yet.
-* Then assertions without _should_ are not supported yet.
+## Example
 
-## Example Zero
-
-Here's the spec that I've been playing with.  Its gone through
-mulitple revisions and several prototype implementations.  And this is
-probably not the final form.
-
-With all that in mind, here's a specification in my imaginary
-framework:
+Here is a specification written in the rspec-given framework:
 
 <pre>
+require 'rspec/given'
 require 'spec_helper'
 require 'stack'
 
 describe Stack do
-  # NOTE: Invariants are not yet supported in rspec-given
-  # Invariant { stack.depth >= 0 }
-  # Invariant { stack.empty? == (stack.depth == 0) }
-
-  Given(:an_empty_stack) { Stack.new }
-
-  Given(:a_stack_with_one_item) do
-    Stack.new.tap do |s|
-      s.push(:an_item)
-    end
+  def stack_with(initial_contents)
+    stack = Stack.new
+    initial_contents.each do |item| stack.push(item) end
+    stack
   end
 
-  Given(:a_stack_with_several_items) do
-    Stack.new.tap do |s|
-      s.push(:second_item)
-      s.push(:top_item)
-    end
-  end
-
-  context "an empty stack" do
-    Given(:stack) { an_empty_stack }
+  Given(:stack) { stack_with(initial_contents) }
 
+  context "when empty" do
+    Given(:initial_contents) { [] }
     Then { stack.depth.should == 0 }
 
-    context "Pushing onto an empty stack" do
+    context "when pushing" do
       When { stack.push(:an_item) }
 
       Then { stack.depth.should == 1 }
@@ -67,10 +47,10 @@ describe Stack do
     end
   end
 
-  context "a stack with one item do" do
-    Given(:stack) { a_stack_with_one_item }
+  context "with one item" do
+    Given(:initial_contents) { [:an_item] }
 
-    context "popping an item empties the stack" do
+    context "when popping" do
       When(:pop_result) { stack.pop }
 
       Then { pop_result.should == :an_item }
@@ -78,18 +58,18 @@ describe Stack do
     end
   end
 
-  context "a stack with several items" do
-    Given(:stack) { a_stack_with_several_items }
+  context "with several items" do
+    Given(:initial_contents) { [:second_item, :top_item] }
     Given!(:original_depth) { stack.depth }
 
-    context "pushing a new item adds a new top" do
+    context "when pushing" do
       When { stack.push(:new_item) }
 
       Then { stack.top.should == :new_item }
       Then { stack.depth.should == original_depth + 1 }
     end
 
-    context "popping an item removes the top item" do
+    context "when popping" do
       When(:pop_result) { stack.pop }
 
       Then { pop_result.should == :top_item }
@@ -100,7 +80,8 @@ describe Stack do
 end
 </pre>
 
-Let's talk about the individual sections.
+Let's talk about the individual statements used in the Given
+framework.
 
 ### Given
 
@@ -110,10 +91,15 @@ 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, we see three starting points of interest.
-One is an empty, just freshly created stack.  The next is a stack with
-exactly one item.  The final starting point is a stack with several
-items.
+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
@@ -127,13 +113,78 @@ 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.
+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.
 
 ### Then
 
@@ -141,10 +192,19 @@ The _Then_ sections are the postconditions of the specification. These
 then conditions must be true after the code under test (the _When_
 block) is run.
 
-The code in the _Then_ block should be a single boolean condition that
-devaluates to true if the code in the _When_ block is correct.  If the
-_Then_ block evaluates to false, then that is recorded as a failure.
+The code in the _Then_ block should be a single _should_
+assertion. Code in _Then_ blocks should not have any side effects.
+
+#### 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.
+
+<!--
 ### Invariant
 
 The _Invariant_ block is a new idea that doesn't have an analog in
@@ -158,7 +218,7 @@ You can conceptually think of an _Invariant_ block as a _Then_ block
 that automatically gets added to every _When_ within its scope.
 
 Invariants nested within a context only apply to the _When_ blocks in
-that context.  
+that context.
 
 Invariants that reference a _Given_ precondition accessor must only be
 used in contexts that define that accessor.
@@ -166,9 +226,33 @@ used in contexts that define that accessor.
 NOTE: Invariants are not yet implemented in the current version of
 rspec-given.
 
+-->
+
+# 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.
+
+First, I would like to introduce invariants.  An _Invariant_ block
+would essentially be a post-conditions that should be true after
+_Then_ block in the same (or nested) context as the invariant.
+
+Second, 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) 
+* 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: [http://onestepback.org/cgi-bin/bugs.cgi?project=rspec-given](http://onestepback.org/cgi-bin/bugs.cgi?project=rspec-given) 
+* Bug/Issue Reporting: [http://onestepback.org/cgi-bin/bugs.cgi?project=rspec-given](http://onestepback.org/cgi-bin/bugs.cgi?project=rspec-given)
 

data/Rakefile

@@ -7,8 +7,11 @@ CLOBBER.include("*.gemspec", "html")
 
 # README Formatting --------------------------------------------------
 
-require 'bluecloth'
-
+begin
+  require 'bluecloth'
+rescue LoadError => ex
+  puts "WARNING: BlueCloth not available"
+end
 
 task :default => :examples
 

data/examples/stack/stack_spec.rb

@@ -1,3 +1,4 @@
+require 'rspec/given'
 require 'spec_helper'
 require 'stack'
 
@@ -6,27 +7,19 @@ describe Stack do
   # Invariant { stack.depth >= 0 }
   # Invariant { stack.empty? == (stack.depth == 0) }
 
-  Given(:an_empty_stack) { Stack.new }
-
-  Given(:a_stack_with_one_item) do
-    Stack.new.tap do |s|
-      s.push(:an_item)
-    end
-  end
-
-  Given(:a_stack_with_several_items) do
-    Stack.new.tap do |s|
-      s.push(:second_item)
-      s.push(:top_item)
-    end
+  def stack_with(initial_contents)
+    stack = Stack.new
+    initial_contents.each do |item| stack.push(item) end
+    stack
   end
 
-  context "an empty stack" do
-    Given(:stack) { an_empty_stack }
+  Given(:stack) { stack_with(initial_contents) }
 
+  context "when empty" do
+    Given(:initial_contents) { [] }
     Then { stack.depth.should == 0 }
 
-    Scenario "pushing onto an empty stack" do
+    context "when pushing" do
       When { stack.push(:an_item) }
 
       Then { stack.depth.should == 1 }
@@ -34,10 +27,10 @@ describe Stack do
     end
   end
 
-  context "a stack with one item do" do
-    Given(:stack) { a_stack_with_one_item }
+  context "with one item" do
+    Given(:initial_contents) { [:an_item] }
 
-    Scenario "popping an item empties the stack" do
+    context "when popping" do
       When(:pop_result) { stack.pop }
 
       Then { pop_result.should == :an_item }
@@ -45,18 +38,18 @@ describe Stack do
     end
   end
 
-  context "a stack with several items" do
-    Given(:stack) { a_stack_with_several_items }
+  context "with several items" do
+    Given(:initial_contents) { [:second_item, :top_item] }
     Given!(:original_depth) { stack.depth }
 
-    Scenario "pushing a new item adds a new top" do
+    context "when pushing" do
       When { stack.push(:new_item) }
 
       Then { stack.top.should == :new_item }
       Then { stack.depth.should == original_depth + 1 }
     end
 
-    Scenario "popping an item removes the top item" do
+    context "when popping" do
       When(:pop_result) { stack.pop }
 
       Then { pop_result.should == :top_item }

data/examples/wrong/wrong_spec.rb

@@ -0,0 +1,26 @@
+require 'rspec/given'
+require 'wrong'
+
+include Wrong
+
+describe "Using Wrong" do
+  def self.Should(&block)
+    specify do
+      assert(&block)
+    end
+  end
+
+  # Scenario "trying wrong's assert" do
+  #   Given(:a) { 1 }
+  #   Given(:b) { 1 }
+  #   Then { a == b }
+  # end
+
+  context "trying wrong's assert" do
+    Given(:a) { 1 }
+    Given(:b) { 2 }
+    puts "DBG: BEFORE THEN"
+    Should { a == b }
+    puts "DBG: AFTER THEN"
+  end
+end

data/lib/rspec/given/version.rb

@@ -2,7 +2,7 @@ module RSpec
   module Given
     VERSION_MAJOR = 1
     VERSION_MINOR = 3
-    VERSION_BUILD = 0
+    VERSION_BUILD = 1
     VERSION_NUMBERS = [VERSION_MAJOR, VERSION_MINOR, VERSION_BUILD]
     VERSION = VERSION_NUMBERS.join(".")
   end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 1
   - 3
-  - 0
-  version: 1.3.0
+  - 1
+  version: 1.3.1
 platform: ruby
 authors: 
 - Jim Weirich
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-07 00:00:00 -05:00
+date: 2011-02-01 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -64,6 +64,7 @@ files:
 - examples/spec_helper.rb
 - examples/stack/stack.rb
 - examples/stack/stack_spec.rb
+- examples/wrong/wrong_spec.rb
 has_rdoc: true
 homepage: http://github.com/jimweirich/rspec-given
 licenses: []