rspec-given 2.3.0.beta.3 → 2.3.0

data/README.md

@@ -1,6 +1,6 @@
 # rspec-given
 
-Covering rspec-given, version 2.3.0.beta.3.
+Covering rspec-given, version 2.3.0.
 
 rspec-given is an RSpec extension to allow Given/When/Then notation in
 RSpec specifications.  It is a natural extension of the experimental
@@ -305,14 +305,19 @@ stick with _Then_ clauses.
 
 The _Invariant_ clause is a new idea that doesn't have an analog in
 RSpec or Test::Unit. The invariant allows you specify things that must
-always be true in the scope of the invariant. In the stack example,
-<tt>empty?</tt> is defined in term of <tt>size</tt>. Whenever
-<tt>size</tt> is 0, <tt>empty?</tt> should be true. Whenever
-<tt>size</tt> is non-zero, <tt>empty?</tt> should be false.
+always be true in the scope of the invariant. In the stack example, the method
+<tt>empty?</tt> is defined in term of <tt>size</tt>.
+
+```ruby
+  Invariant { stack.empty? == (stack.depth == 0) }
+```
+
+This invariant states that <code>empty?</code> is true if and only if
+the stack depth is zero, and that assertion is checked at every _Then_
+clause that is in the same scope.
 
 You can conceptually think of an _Invariant_ clause as a _Then_ block
 that automatically gets added to every _Then_ within its scope.
-
 Invariants nested within a context only apply to the _Then_ clauses
 that are in the scope of that context.
 
@@ -325,10 +330,40 @@ Notes:
    represented in the RSpec formatted output (e.g. the '--format html'
    option).
 
+## Execution Ordering
+
+When running the test for a specific _Then_ clause, the following will
+be true:
+
+* The _Given_ clauses will be run in the order that they are
+  specified, from the outermost scope to the innermost scope
+  containing the _Then_.
+
+* All of the _Given_ clauses in all of the relevant scopes will run
+  before the first (outermost) _When_ clause in those same scopes.
+  That means that the _When_ code can assume that the givens have been
+  established, even if the givens are in a more nested scope than the
+  When.
+
+* _When_ clauses and RSpec _before_ blocks will be executed in the
+  order that they are specified, from the outermost block to the
+  innermost block.  This makes _before_ blocks an excellent choice
+  when writing narrative tests to specify actions that happen between
+  the "whens" of a narrative.
+
+Note that the ordering between _Given_ clauses and _before_ blocks are
+a not strongly specified. Hoisting a _When_ clause out of an inner
+scope to an outer scope may change the ordering of when the _Given_
+clause runs in relation to a _before_ block (the hoisting will cause
+the givens to possibly run earlier).  Because of this, do not split
+order dependent code between _Given_ clauses and _before_ blocks.
+
 ## Natural Assertions
 
 **NOTE:** <em>Natural assertions are an experimental feature of
-RSpec/Given. They are currently disabled by default.</em>
+RSpec/Given. They are currently disabled by default. They can be
+enabled by a simple configuration option (see "use_natural_assertions"
+below).</em>
 
 RSpec/Given now supports the use of "natural assertions" in _Then_,
 _And_, and _Invariant_ blocks. Natural assertions are just Ruby
@@ -399,12 +434,14 @@ Keep the following in mind when using Natural Assertions.
   to join the conditions into a single expression (and the failure
   message will breakdown the values for each part).
 
-* Natural assertions must be **idempotent** (that means they don't
-  change anything). Since the natural assertion error message contains
+* Then clauses need be **idempotent**. This is true in general, but it
+  is particularly important for Natural assertions to obey this
+  restriction. This means that assertions in a Then clause should not
+  change anything. Since the natural assertion error message contains
   the values of all the subexpressions, the expression and its
-  subexpressions will be evaluated multiple times. If the block is not
-  idempotent, you will get changing answers as the subexpressions are
-  evaluated.
+  subexpressions will be evaluated multiple times. If the Then clause
+  is not idempotent, you will get changing answers as the
+  subexpressions are evaluated.
 
 That last point is important. If you write code like this:
 
@@ -433,6 +470,9 @@ like this is good:
   end
 ```
 
+It is good to note that non-idempotent assertions will also cause
+problems with And clauses.
+
 ### Mixing Natural Assertions and RSpec Assertions
 
 Natural assertions and RSpec assertions for the most part can be
@@ -463,49 +503,79 @@ will not process natural assertions.
 See the **configuration** section below to see how to enable natural
 assertions project wide.
 
-### Processing Natural Assertions
+### Matchers and Natural Assertions
 
-When natural assertions are enabled, they are only used if:
+In RSpec, matchers are used to provide nice, readable error messages
+when an assertion is not met. Natural assertions provide
+self-explanatory failure messages for most things without requiring
+any special matchers from the programmer.
 
-1. The block does not throw an RSpec assertion failure (or any other
-   exception for that matter).
+In the rare case that some extra information would be hepful, it is
+useful to create special objects that respond to the == operator.
 
-1. The block returns false (blocks that return true pass the
-   assertion and don't need a failure message).
+#### Asserting Nearly Equal
 
-1. The block does not directly use RSpec's _should_ or _expect_
-   method.
+Operations on floating point numbers rarely create numbers that are
+exactly equal, therefore it is useful to assert that two floating
+point numbers are nearly equal.
 
-Detecting that last point (the use of _should_ and _expect_) is done
-by examining the source of the block. However it is not always
-possible to correctly determine if _should_ and _expect_ are used
-merely from the source. Fortunately you can always override the
-automatic detection by either forcing natural assertions (with
-:always) or disabling them (with false).
+For example, the following asserts that the square root of 10 is about
+3.1523 with an accuracy of 0.1 percent.
 
 ```ruby
-  # Then uses a non-RSpec version of "should" on
-  context "sample" do
-    use_natural_assertions :always
-    Then { obj.should }    # Non-rspec should is called
-  end
+    Then { Math.sqrt(10) == about(3.1623).percent(1) }
 ```
 
+As long as the real value of <code>Math.sqrt(10)</code> is within plus
+or minus 1% of 3.1623 (i.e. 3.1623 +/- 0.0031623), then the assertion
+will pass.
+
+There are several ways of creating approximate numbers:
+
+* <code>about(n).delta(d)</code> -- A fuzzy number matching the range
+  (n-d)..(n+d)
+
+* <code>about(n).percent(p)</code> -- A fuzzy number matching the
+  range (n-(n*p/100)) .. (n+(n*p/100))
+
+* <code>about(n).epsilon(neps)</code> -- A fuzzy number matching the
+  range (n-(neps*e)) .. (n+(neps*e)), where e is the difference
+  between 1.0 and the next smallest floating point number.
+
+* <code>about(n)</code> -- Same as <code>about(n).epsilon(10)</code>.
+
+#### Detecting Exceptions
+
+The RSpec matcher used for detecting exceptions will work with natural
+assertions out of the box. Just check for equality against the
+<code>have_failed</code> return value.
+
+For example, the following two Then clauses are equivalent:
+
 ```ruby
-  # Then does not call should directly, so disable natural assertions
-  context "sample" do
-    use_natural_assertions false
-    Then { check_validations(obj) }   # check_validations calls "should" internally
-  end
+    # Using an RSpec matcher
+    Then { result.should have_failed(StandardError, /message/) }
 
-  # You can also just not use a Then for that condition.
-  context "another sample" do
-    it "checks validations" do
-      check_validations(obj)
-    end
-  end
+    # Using natural assertions
+    Then { result == have_failed(StandardError, /message/) }
 ```
 
+### Processing Natural Assertions
+
+When natural assertions are enabled, they are only used if:
+
+1. The block does not throw an RSpec assertion failure (or any other
+   exception for that matter).
+
+1. The block returns false (blocks that return true pass the
+   assertion and don't need a failure message).
+
+1. The block does not use RSpec's _should_ or _expect_ methods.
+
+Detecting that last point (the use of _should_ and _expect_) is done
+by modifying the RSpec runtime to report uses of _should_ and
+_expect_.
+
 ### Further Reading
 
 Natural assertions were inspired by the [wrong assertion

data/examples/failing/natural_failing_spec.rb

@@ -23,6 +23,18 @@ describe "Natural Assertions" do
     (puts "Ha ha world", ! true)
   }
 
+  Then { Math.sqrt(10) == about(3.1623).percent(0.0001) }
+
+  describe "Error Examples" do
+    When(:result) { fail "OUCH" }
+    Then { result == :ok }
+  end
+
+  describe "Non-Error Failures" do
+    When(:result) { :ok }
+    Then { result == have_failed(StandardError, /^O/) }
+  end
+
   context "Incorrect non-idempotent conditions" do
     Given(:ary) { [1, 2, 3] }
     Then { ary.delete(1) == nil }

data/lib/rspec/given/configure.rb

@@ -1,5 +1,6 @@
 require 'rspec'
 require 'rspec/given/extensions'
+require 'rspec/given/fuzzy_number'
 require 'rspec/given/have_failed'
 require 'rspec/given/module_methods'
 
@@ -7,6 +8,7 @@ RSpec.configure do |c|
   c.extend(RSpec::Given::ClassExtensions)
   c.include(RSpec::Given::InstanceExtensions)
   c.include(RSpec::Given::HaveFailed)
+  c.include(RSpec::Given::Fuzzy)
 
   c.backtrace_clean_patterns << /lib\/rspec\/given/
 

data/lib/rspec/given/extensions.rb

@@ -159,7 +159,7 @@ module RSpec
       #    Scenario "a scenario description" do ... end
       #
       def Scenario(description, &block)
-        file, line = eval("[__LINE__, __FILE__]", block.binding)
+        file, line = eval("[__FILE__, __LINE__]", block.binding)
         puts "WARNING: Scenario is deprecated, please use either describe or context (#{file}:#{line})"
         context(description, &block)
       end
@@ -190,7 +190,7 @@ module RSpec
       #   Given!(:name) { ... code ... }
       #
       def Given!(name, &block)
-        let!(name, &block)
+        let(name, &block)
         _rgc_givens << _rgc_trigger_given(name)
       end
 

data/lib/rspec/given/failure.rb

@@ -14,9 +14,29 @@ module RSpec
         klass == Failure
       end
 
-      def method_missing(sym, *args, &block)
+      def ==(other)
+        if other.is_a?(::RSpec::Given::HaveFailed::HaveFailedMatcher)
+          other.matches?(self)
+        else
+          die
+        end
+      end
+
+      def !=(other)
+        if other.is_a?(::RSpec::Given::HaveFailed::HaveFailedMatcher)
+          ! other.matches?(self)
+        else
+          die
+        end
+      end
+
+      def die
         ::Kernel.raise @exception
       end
+
+      def method_missing(sym, *args, &block)
+        die
+      end
     end
   end
 end

data/lib/rspec/given/fuzzy_number.rb

@@ -0,0 +1,64 @@
+
+module RSpec
+  module Given
+    module Fuzzy
+      class FuzzyNumber
+
+        DEFAULT_EPSILON = 10 * Float::EPSILON
+
+        attr_reader :exact_value, :delta_amount
+
+        def initialize(exact_value)
+          @exact_value = exact_value
+          @delta_amount = exact_value * DEFAULT_EPSILON
+        end
+
+        # Low limit of the fuzzy number.
+        def low_limit
+          exact_value - delta_amount
+        end
+
+        # High limit of the fuzzy number.
+        def high_limit
+          exact_value + delta_amount
+        end
+
+        # True if the other number is in range of the fuzzy number.
+        def ==(other)
+          (other - exact_value).abs <= delta_amount
+        end
+
+        def to_s
+          "<Approximately #{exact_value} +/- #{delta_amount}>"
+        end
+
+        # Set the delta for a fuzzy number.
+        def delta(delta)
+          @delta_amount = delta.abs
+          self
+        end
+
+        # Specifying a percentage of the exact number to be used in
+        # setting the delta.
+        def percent(percentage)
+          delta(exact_value * (percentage / 100.0))
+        end
+
+        # Specifying the number of epsilons to be used in setting the
+        # delta.
+        def epsilon(neps)
+          delta(exact_value * (neps * Float::EPSILON))
+        end
+      end
+
+      # Create an approximate number that is approximately equal to
+      # the given number, plus or minus the delta value. If no
+      # explicit delta is given, then the default delta that is about
+      # 10X the size of the smallest possible change in the given
+      # number will be used.
+      def about(*args)
+        FuzzyNumber.new(*args)
+      end
+    end
+  end
+end

data/lib/rspec/given/have_failed.rb

@@ -24,6 +24,10 @@ module RSpec
               super(lambda { })
             end
           end
+
+          def to_s
+            "<Failure matching #{@expected_error}: #{@expected_message.inspect}>"
+          end
         end
 
       else
@@ -36,6 +40,10 @@ module RSpec
               super(lambda { })
             end
           end
+
+          def to_s
+            "<FailureMatcher on #{@expected_error}: #{@expected_message.inspect}>"
+          end
         end
 
       end
@@ -58,6 +66,10 @@ module RSpec
       def have_failed(error=Exception, message=nil, &block)
         HaveFailedMatcher.new(error, message, &block)
       end
+      alias have_raised have_failed
+
+      def failure(error=Exception, message=nil, &block)
+      end
     end
   end
 end

data/lib/rspec/given/version.rb

@@ -4,8 +4,6 @@ module RSpec
       VERSION_MAJOR = 2,
       VERSION_MINOR = 3,
       VERSION_BUILD = 0,
-      'beta',
-      VERSION_BETA  = 3,
     ]
     VERSION = VERSION_NUMBERS.join(".")
   end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: rspec-given
 version: !ruby/object:Gem::Version
-  version: 2.3.0.beta.3
-  prerelease: 6
+  version: 2.3.0
+  prerelease: 
 platform: ruby
 authors:
 - Jim Weirich
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-05 00:00:00.000000000 Z
+date: 2013-01-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -112,6 +112,7 @@ files:
 - lib/rspec/given/extensions.rb
 - lib/rspec/given/failure.rb
 - lib/rspec/given/file_cache.rb
+- lib/rspec/given/fuzzy_number.rb
 - lib/rspec/given/have_failed.rb
 - lib/rspec/given/line_extractor.rb
 - lib/rspec/given/module_methods.rb
@@ -153,9 +154,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: given
 rubygems_version: 1.8.24