rspec-given 1.6.0 → 2.0.0.beta.1

data/README.md

@@ -1,6 +1,6 @@
 # rspec-given
 
-Covering rspec-given, version 1.6.0.beta.1.
+Covering rspec-given, version 2.0.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
@@ -36,6 +36,7 @@ describe Stack do
   end
 
   Given(:stack) { stack_with(initial_contents) }
+  Invariant { stack.empty?.should == (stack.depth == 0) }
 
   context "when empty" do
     Given(:initial_contents) { [] }

data/Rakefile

@@ -3,6 +3,7 @@
 require 'rake/clean'
 require './lib/rspec/given/version'
 
+CLEAN.include("pkg/rspec-given-*").exclude("pkg/*.gem")
 CLOBBER.include("*.gemspec", "html", "README", "README.old")
 
 # README Formatting --------------------------------------------------
@@ -15,6 +16,36 @@ end
 
 task :default => :ex2
 
+def version
+  RSpec::Given::VERSION
+end
+
+def tag_name
+  "rspec-given-#{version}"
+end
+
+def tagged?
+  `git tag`.split.include?(tag_name)
+end
+
+def git_clean?
+  sh "git status | grep 'nothing to commit'", :verbose => false do |status|
+    return status
+  end
+end
+
+desc "Display the current version tag"
+task :version do
+  puts tag_name
+end
+
+desc "Tag the current commit with #{tag_name}"
+task :tag do
+  fail "Cannot tag, project directory is not clean" unless git_clean?
+  fail "Cannot tag, #{tag_name} already exists." if tagged?
+  sh "git tag #{tag_name}"
+end
+
 # Running examples ---------------------------------------------------
 
 desc "Run all the examples"
@@ -23,6 +54,7 @@ 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"
@@ -79,8 +111,8 @@ file "README.md" => ["examples/stack/stack_spec.rb", "lib/rspec/given/version.rb
       while line = ins.gets
         case state
         when :copy
-          if line =~ /version +\d+\.\d+\.\d+/
-            line.gsub!(/version +\d+\.\d+\.\d+/, "version #{RSpec::Given::VERSION}")
+          if line =~ /version +\d+(\.(\d+|beta))+/
+            line.gsub!(/version +\d+(\.(\d+|beta))+/, "version #{RSpec::Given::VERSION}")
             outs.puts line
           elsif line =~ /^<pre>/
             state = :insert

data/examples/integration/given_spec.rb

@@ -0,0 +1,51 @@
+require 'rspec-given'
+
+describe "Running Givens before Whens" do
+  Given(:info) { [] }
+  Given { info << "outer1" }
+  Given { info << "outer2" }
+
+  context "using a when without result" do
+    When { info << "when" }
+
+    context "inner with When" do
+      Given { info << "inner1" }
+      Given { info << "inner2" }
+      Then { info.should == ["outer1", "outer2", "inner1", "inner2", "when"] }
+
+      context "using a nested When" do
+        When { info << "when2" }
+        Then { info.should == ["outer1", "outer2", "inner1", "inner2", "when", "when2"] }
+      end
+    end
+  end
+
+  context "using a when with a result" do
+    When(:result) { info << "when" }
+
+    context "inner with when" do
+      Given { info << "inner1" }
+      Given { info << "inner2" }
+      Then { info.should == ["outer1", "outer2", "inner1", "inner2", "when"] }
+    end
+  end
+
+  context "using no whens" do
+    Given { info << "inner1" }
+    Given { info << "inner2" }
+    Then { info.should == ["outer1", "outer2", "inner1", "inner2"] }
+  end
+end
+
+describe "Lazy Givens" do
+  Given(:bomb) { fail "SHOULD NEVER BE CALLED" }
+
+  context "when called" do
+    Then { lambda { bomb }.should raise_error(StandardError, /NEVER/) }
+  end
+
+  context "when not called" do
+    Given(:value) { :ok }
+    Then { value.should == :ok }
+  end
+end

data/examples/integration/invariant_spec.rb

@@ -0,0 +1,31 @@
+require 'rspec/given'
+
+describe "Invariants" do
+  Given(:info) { [] }
+
+  Invariant { info << "I1" }
+
+  Then { info.should == ["I1"] }
+
+  context "with nested invariants" do
+    Invariant { info << "I2" }
+
+    Then { info.should == ["I1", "I2"] }
+  end
+
+  context "with multiple invariants" do
+    Invariant { info << "I2a" }
+    Invariant { info << "I2b" }
+
+    Then { info.should == ["I1", "I2a", "I2b"] }
+  end
+
+  context "with a when" do
+    Invariant { info << "I2" }
+
+    When(:when_info) { info.dup }
+
+    Then { info.should == ["I1", "I2"] }
+    Then { when_info.should == [] }
+  end
+end

data/examples/stack/stack_spec.rb

@@ -10,6 +10,7 @@ describe Stack do
   end
 
   Given(:stack) { stack_with(initial_contents) }
+  Invariant { stack.empty?.should == (stack.depth == 0) }
 
   context "when empty" do
     Given(:initial_contents) { [] }

data/lib/rspec/given/configure.rb

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

data/lib/rspec/given/extensions.rb

@@ -2,13 +2,55 @@ require 'rspec/given/failure'
 
 module RSpec
   module Given
-    module Extensions
+
+    # Provide run-time methods to support RSpec/Given infrastructure.
+    # All the methods in this module are considered private and
+    # implementation-specific.
+    module InstanceExtensions   # :nodoc:
+
+      # Establish all the Given preconditions the current and
+      # surrounding describe/context blocks, starting with the
+      # outermost context.
+      def _rg_establish_givens  # :nodoc:
+        return if defined?(@_rg_ran)
+        self.class.ancestors.reverse.each do |context|
+          context._rg_givens.each do |block|
+            instance_eval(&block)
+          end
+        end
+        @_rg_ran = true
+      end
+
+      # Check all the invariants in the current and surrounding
+      # describe/context blocks, starting with the outermost context.
+      def _rg_check_invariants  # :nodoc:
+        self.class.ancestors.reverse.each do |context|
+          context._rg_invariants.each do |block|
+            instance_eval(&block)
+          end
+        end
+      end
+    end
+
+    module ClassExtensions
+
+      # List of all givens directly in the current describe/context
+      # block.
+      def _rg_givens            # :nodoc:
+        @_rg_givens ||= []
+      end
+
+      # List of all invariants directly in the current
+      # describe/context block.
+      def _rg_invariants        # :nodoc:
+        @_rg_invariants ||= []
+      end
 
       # *DEPRECATED:*
       #
-      # The Scenario command is deprecated.  Future versions of
-      # rspec/given will start displaying warnings when used.
-      # Eventually the command will be removed.
+      # The Scenario command is deprecated. Using Scenario in a spec
+      # will result in a warning message. Eventually the command will
+      # be removed.
       #
       # Declare a scenario to contain Given/When/Then declarations.  A
       # Scenario is essentially an RSpec context, with the additional
@@ -21,6 +63,9 @@ module RSpec
       #    Scenario "a scenario description" do ... end
       #
       def Scenario(description, &block)
+        line = eval("__LINE__", block.binding)
+        file = eval("__FILE__", block.binding)
+        puts "WARNING: Scenario is deprecated, please use either describe or context (#{file}:#{line})"
         context(description, &block)
       end
 
@@ -38,7 +83,7 @@ module RSpec
         if args.first.is_a?(Symbol)
           let(args.first, &block)
         else
-          before(&block)
+          _rg_givens << block
         end
       end
 
@@ -62,15 +107,38 @@ module RSpec
         if args.first.is_a?(Symbol)
           let!(args.first) do
             begin
+              _rg_establish_givens
               instance_eval(&block)
             rescue Exception => ex
               Failure.new(ex)
             end
           end
         else
-          before(&block)
+          before do
+            _rg_establish_givens
+            instance_eval(&block)
+          end
         end
       end
+
+      # Provide an assertion about the specification.
+      #
+      # Then supplies an assertion that should be true after all the
+      # Given and When blocks have been run. All invariants in scope
+      # will be checked before the Then block is run.
+      def Then(&block)
+        specify do
+          _rg_establish_givens
+          _rg_check_invariants
+          instance_eval(&block)
+        end
+      end
+
+      # Establish an invariant that must be true for all Then blocks
+      # in the current (and nested) scopes.
+      def Invariant(&block)
+        _rg_invariants << block
+      end
     end
   end
 end

data/lib/rspec/given/version.rb

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

metadata

@@ -1,8 +1,8 @@
 --- !ruby/object:Gem::Specification
 name: rspec-given
 version: !ruby/object:Gem::Version
-  version: 1.6.0
-  prerelease: 
+  version: 2.0.0.beta.1
+  prerelease: 6
 platform: ruby
 authors:
 - Jim Weirich
@@ -13,7 +13,7 @@ date: 2012-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70231666072020 !ruby/object:Gem::Requirement
+  requirement: &70366429396080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>'
@@ -21,10 +21,10 @@ dependencies:
         version: 1.2.8
   type: :runtime
   prerelease: false
-  version_requirements: *70231666072020
+  version_requirements: *70366429396080
 - !ruby/object:Gem::Dependency
   name: bluecloth
-  requirement: &70231666071580 !ruby/object:Gem::Requirement
+  requirement: &70366429395640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70231666071580
+  version_requirements: *70366429395640
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &70231666070900 !ruby/object:Gem::Requirement
+  requirement: &70366429394960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>'
@@ -43,7 +43,7 @@ dependencies:
         version: 2.4.2
   type: :development
   prerelease: false
-  version_requirements: *70231666070900
+  version_requirements: *70366429394960
 description: ! 'Given is an RSpec extension that allows explicit definition of the
 
   pre and post-conditions for code under test.
@@ -56,7 +56,6 @@ extra_rdoc_files: []
 files:
 - MIT-LICENSE
 - Rakefile
-- README
 - README.md
 - lib/rspec-given.rb
 - lib/rspec/given/configure.rb
@@ -66,6 +65,8 @@ files:
 - lib/rspec/given/rspec1_given.rb
 - lib/rspec/given/version.rb
 - lib/rspec/given.rb
+- examples/integration/given_spec.rb
+- examples/integration/invariant_spec.rb
 - examples/spec_helper.rb
 - examples/stack/stack.rb
 - examples/stack/stack_spec.rb
@@ -91,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

data/README

@@ -1,242 +0,0 @@
-= 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.
-
-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_ 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)