rspec-given 1.5.1 → 1.6.0.beta.1

data/README

@@ -0,0 +1,225 @@
+= rspec-given
+
+Covering rspec-given, version 1.6.0.beta.1.
+
+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) }
+    
+      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.should be_empty }
+        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.
+
+=== Then
+
+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 _should_
+assertion. Code in _Then_ blocks should not have any side effects.
+
+==== 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.
+
+
+= 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)
+* 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)

data/README.md

@@ -1,6 +1,6 @@
 # rspec-given
 
-Covering rspec-given, version 1.5.1.
+Covering rspec-given, version 1.6.0.beta.1.
 
 rspec-given is an RSpec extension to allow Given/When/Then notation in
 RSpec specifications.  It is a natural extension of the experimental
@@ -47,6 +47,11 @@ describe Stack do
       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
@@ -256,5 +261,4 @@ has laid some groundwork in this area.
 
 * 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: [https://github.com/jimweirich/rspec-given/issues](https://github.com/jimweirich/rspec-given/issues)

data/README.old

@@ -0,0 +1,264 @@
+# rspec-given
+
+Covering rspec-given, version 1.5.1.
+
+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) }
+
+  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.should be_empty }
+    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
+</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.
+
+### Then
+
+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 _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
+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 _When_ within its scope.
+
+Invariants nested within a context only apply to the _When_ blocks in
+that context.
+
+Invariants that reference a _Given_ precondition accessor must only be
+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)
+* 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)

data/Rakefile

@@ -13,32 +13,43 @@ rescue LoadError => ex
   puts "WARNING: BlueCloth not available"
 end
 
-task :default => :examples
+task :default => :ex2
 
 # Running examples ---------------------------------------------------
 
 desc "Run all the examples"
-task :examples => [:examples1, :examples2]
+task :examples => [:specs, :examples1, :examples2]
+
+desc "Run the RSpec 2 specs and examples"
+task :ex2 => [:specs, :examples2]
+
+desc "Run the specs"
+task :specs do
+  puts "Running specs"
+  sh "rspec spec"
+end
 
 desc "Run the examples in RSpec 1"
 task :examples1 => [:verify_rspec1] do
+  puts "Running examples (with RSpec2)"
   sh "spec examples/stack/stack_spec1.rb"
 end
 
 desc "Run the examples in RSpec 2"
 task :examples2 => [:verify_rspec2] do
+  puts "Running examples (with RSpec2)"
   sh "rspec examples"
 end
 
 task :verify_rspec1 do
   sh "type spec >/dev/null 2>&1", verbose: false do |status|
-    fail "You need to install RSpec 1 in order to test agains it." unless status
+    fail "You need to install RSpec 1 in order to test against it." unless status
   end
 end
 
 task :verify_rspec2 do
   sh "type rspec >/dev/null 2>&1", verbose: false do |status|
-    fail "You need to install RSpec 2 in order to test agains it." unless status
+    fail "You need to install RSpec 2 in order to test against it." unless status
   end
 end
 

data/examples/stack/stack.rb

@@ -1,4 +1,7 @@
 class Stack
+  class StackError < StandardError; end
+  class UnderflowError < StackError; end
+
   def initialize
     @items = []
   end
@@ -20,6 +23,7 @@ class Stack
   end
 
   def pop
+    fail UnderflowError, "Cannot pop an empty stack" if empty?
     @items.pop
   end
 end

data/examples/stack/stack_spec.rb

@@ -21,6 +21,11 @@ describe Stack do
       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

data/lib/rspec/given.rb

@@ -15,4 +15,6 @@ else
   require 'rspec/given/version'
   require 'rspec/given/extensions'
   require 'rspec/given/configure'
+  require 'rspec/given/failure'
+  require 'rspec/given/have_failed'
 end

data/lib/rspec/given/configure.rb

@@ -1,7 +1,9 @@
 require 'rspec'
 require 'rspec/given/extensions'
+require 'rspec/given/have_failed'
 
 RSpec.configure do |c|
   c.alias_example_to :Then
   c.extend(RSpec::Given::Extensions)
+  c.include(RSpec::Given::HaveFailed)
 end

data/lib/rspec/given/extensions.rb

@@ -1,3 +1,5 @@
+require 'rspec/given/failure'
+
 module RSpec
   module Given
     module Extensions
@@ -58,7 +60,13 @@ module RSpec
       #
       def When(*args, &block)
         if args.first.is_a?(Symbol)
-          let!(args.first, &block)
+          let!(args.first) do
+            begin
+              instance_eval(&block)
+            rescue Exception => ex
+              Failure.new(ex)
+            end
+          end
         else
           before(&block)
         end

data/lib/rspec/given/failure.rb

@@ -0,0 +1,18 @@
+module RSpec
+  module Given
+
+    # Failure objects will raise the given exception whenever you try
+    # to send it *any* message.
+    class Failure < BasicObject
+      undef_method :==, :!=, :!
+
+      def initialize(exception)
+        @exception = exception
+      end
+
+      def method_missing(sym, *args, &block)
+        ::Kernel.raise @exception
+      end
+    end
+  end
+end

data/lib/rspec/given/have_failed.rb

@@ -0,0 +1,24 @@
+module RSpec
+  module Given
+    module HaveFailed
+
+      # Alias for raise_error(...), but reads a bit better when using
+      # a failure result from a when clause.
+      #
+      # NOTE: This is new for 1.6.0.beta.1. A name change for this
+      # method is possible.
+      #
+      # Typical Usage:
+      #
+      #    When(:result) { fail "OUCH" }
+      #    Then { result.should have_failed(StandardError, /OUCH/) }
+      #
+      # :call-seq:
+      #    have_failed([exception_class [, message_pattern]])
+      #
+      def have_failed(*args, &block)
+        raise_error(*args, &block)
+      end
+    end
+  end
+end

data/lib/rspec/given/version.rb

@@ -2,8 +2,10 @@ module RSpec
   module Given
     VERSION_NUMBERS = [
       VERSION_MAJOR = 1,
-      VERSION_MINOR = 5,
-      VERSION_BUILD = 1,
+      VERSION_MINOR = 6,
+      VERSION_BUILD = 0,
+      VERSION_BETA = "beta",
+      VERSION_BETANUM = "1",
     ]
     VERSION = VERSION_NUMBERS.join(".")
   end

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: rspec-given
 version: !ruby/object:Gem::Version
-  version: 1.5.1
-  prerelease: 
+  version: 1.6.0.beta.1
+  prerelease: 6
 platform: ruby
 authors:
 - Jim Weirich
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-24 00:00:00.000000000 Z
+date: 2012-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70280441873660 !ruby/object:Gem::Requirement
+  requirement: &70359307141520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>'
@@ -21,10 +21,10 @@ dependencies:
         version: 1.2.8
   type: :runtime
   prerelease: false
-  version_requirements: *70280441873660
+  version_requirements: *70359307141520
 - !ruby/object:Gem::Dependency
   name: bluecloth
-  requirement: &70280441873280 !ruby/object:Gem::Requirement
+  requirement: &70359307140800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70280441873280
+  version_requirements: *70359307140800
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &70280441872640 !ruby/object:Gem::Requirement
+  requirement: &70359307140080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>'
@@ -43,7 +43,7 @@ dependencies:
         version: 2.4.2
   type: :development
   prerelease: false
-  version_requirements: *70280441872640
+  version_requirements: *70359307140080
 description: ! 'Given is an RSpec extension that allows explicit definition of the
 
   pre and post-conditions for code under test.
@@ -56,10 +56,14 @@ extra_rdoc_files: []
 files:
 - 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/rspec1_given.rb
 - lib/rspec/given/version.rb
 - lib/rspec/given.rb
@@ -88,9 +92,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>='
+  - - ! '>'
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: given
 rubygems_version: 1.8.15