rspec-expectations 2.10.0 → 2.11.0

data/Changelog.md

@@ -1,10 +1,33 @@
+### 2.11.0 / 2012-07-07
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.10.0...v2.11.0)
+
+Enhancements
+
+* Expand `expect` syntax so that it supports expections on bare values
+  in addition to blocks (Myron Marston).
+* Add configuration options to control available expectation syntaxes
+  (Myron Marston):
+  * `RSpec.configuration.expect_with(:rspec) { |c| c.syntax = :expect }`
+  * `RSpec.configuration.expect_with(:rspec) { |c| c.syntax = :should }`
+  * `RSpec.configuration.expect_with(:rspec) { |c| c.syntax = [:should, :expect] }`
+  * `RSpec.configuration.add_should_and_should_not_to Delegator`
+
+Bug fixes
+
+* Allow only `Numeric` values to be the "actual" in the `be_within` matcher.
+  This prevents confusing error messages. (Su Zhang @zhangsu)
+* Define `should` and `should_not` on `BasicObject` rather than `Kernel`
+  on 1.9. This makes `should` and `should_not` work properly with
+  `BasicObject`-subclassed proxy objects like `Delegator`. (Myron
+  Marston)
+
 ### 2.10.0 / 2012-05-03
 [full changelog](http://github.com/rspec/rspec-expectations/compare/v2.9.1...v2.10.0)
 
 Enhancements
 
 * Add new `start_with` and `end_with` matchers (Jeremy Wadsack)
-* Add new matchers for specifying yields (Myron Marson):
+* Add new matchers for specifying yields (Myron Marston):
     * `expect {...}.to yield_control`
     * `expect {...}.to yield_with_args(1, 2, 3)`
     * `expect {...}.to yield_with_no_args`

data/README.md

@@ -1,4 +1,4 @@
-# RSpec Expectations
+# RSpec Expectations [![Build Status](https://secure.travis-ci.org/rspec/rspec-expectations.png?branch=master)](http://travis-ci.org/rspec/rspec-expectations) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/rspec/rspec-expectations)
 
 RSpec::Expectations lets you express expected outcomes on an object in an
 example.
@@ -62,7 +62,7 @@ actual.should eql(expected) # passes if actual.eql?(expected)
 actual.should be(expected)    # passes if actual.equal?(expected)
 actual.should equal(expected) # passes if actual.equal?(expected)
 ```
-    
+
 ### Comparisons
 
 ```ruby
@@ -163,6 +163,40 @@ actual.should end_with(expected)
 "this string".should end_with("ring")
 ```
 
+## Syntax Options
+
+In addition to the `should` syntax, rspec-expectations supports
+an additional `expect` syntax:
+
+```ruby
+# rather than:
+[1, 2, 3].should include(1)
+
+#...you can use:
+expect([1, 2, 3]).to include(1)
+
+# rather than:
+foo.should_not eq(bar)
+
+#...you can use:
+expect(foo).not_to eq(bar)
+```
+
+If you want your project to only use one of these syntaxes, you can
+configure it:
+
+```ruby
+RSpec.configure do |config|
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+    # or
+    c.syntax = :should
+    # or
+    c.syntax = [:should, :expect]
+  end
+end
+```
+
 ## Also see
 
 * [http://github.com/rspec/rspec](http://github.com/rspec/rspec)

data/features/built_in_matchers/be.feature

@@ -26,13 +26,32 @@ Feature: "be" matchers
       end
       """
     When I run `rspec be_true_spec.rb`
-    Then the output should contain all of these:
-      | 10 examples, 5 failures       |
-      | expected true not to be true  |
-      | expected 7 not to be true     |
-      | expected "foo" not to be true |
-      | expected nil to be true       |
-      | expected false to be true     |
+    Then the output should contain "10 examples, 5 failures"
+    And the output should contain:
+      """
+             expected: non-true value
+                  got: true
+      """
+    And the output should contain:
+      """
+             expected: non-true value
+                  got: 7
+      """
+    And the output should contain:
+      """
+             expected: non-true value
+                  got: "foo"
+      """
+    And the output should contain:
+      """
+             expected: true value
+                  got: nil
+      """
+    And the output should contain:
+      """
+             expected: true value
+                  got: false
+      """
 
   Scenario: be_false matcher
     Given a file named "be_false_spec.rb" with:
@@ -53,13 +72,32 @@ Feature: "be" matchers
       end
       """
     When I run `rspec be_false_spec.rb`
-    Then the output should contain all of these:
-      | 10 examples, 5 failures        |
-      | expected nil not to be false   |
-      | expected false not to be false |
-      | expected true to be false      |
-      | expected 7 to be false         |
-      | expected "foo" to be false     |
+    Then the output should contain "10 examples, 5 failures"
+    And the output should contain:
+      """
+             expected: non-false value
+                  got: nil
+      """
+    And the output should contain:
+      """
+             expected: non-false value
+                  got: false
+      """
+    And the output should contain:
+      """
+             expected: false value
+                  got: true
+      """
+    And the output should contain:
+      """
+             expected: false value
+                  got: 7
+      """
+    And the output should contain:
+      """
+             expected: false value
+                  got: "foo"
+      """
 
   Scenario: be_nil matcher
     Given a file named "be_nil_spec.rb" with:

data/features/syntax_configuration.feature

@@ -0,0 +1,68 @@
+Feature: Syntax Configuration
+
+  In addition to the long-supported `should` syntax, rspec-expectations
+  supports an alternate `expect` syntax. If you want your project to
+  only use one syntax, you can configure the available syntaxes.
+
+  Background:
+    Given a file named "syntaxes_spec.rb" with:
+      """ruby
+      describe "using the should syntax" do
+        specify { 3.should eq(3) }
+        specify { 3.should_not eq(4) }
+        specify { lambda { raise "boom" }.should raise_error("boom") }
+        specify { lambda { }.should_not raise_error }
+      end
+
+      describe "using the expect syntax" do
+        specify { expect(3).to eq(3) }
+        specify { expect(3).not_to eq(4) }
+        specify { expect { raise "boom" }.to raise_error("boom") }
+        specify { expect { }.not_to raise_error }
+      end
+      """
+
+  Scenario: Both syntaxes are available by default
+    When I run `rspec syntaxes_spec.rb`
+    Then the examples should all pass
+
+  Scenario: Disable should syntax
+    Given a file named "disable_should_syntax.rb" with:
+      """ruby
+      RSpec.configure do |config|
+        config.expect_with :rspec do |c|
+          c.syntax = :expect
+        end
+      end
+      """
+    When I run `rspec disable_should_syntax.rb syntaxes_spec.rb`
+    Then the output should contain all of these:
+      | 8 examples, 4 failures    |
+      | undefined method `should' |
+
+  Scenario: Disable expect syntax
+    Given a file named "disable_expect_syntax.rb" with:
+      """ruby
+      RSpec.configure do |config|
+        config.expect_with :rspec do |c|
+          c.syntax = :should
+        end
+      end
+      """
+    When I run `rspec disable_expect_syntax.rb syntaxes_spec.rb`
+    Then the output should contain all of these:
+      | 8 examples, 4 failures    |
+      | undefined method `expect' |
+
+  Scenario: Explicitly enable both syntaxes
+    Given a file named "enable_both_syntaxes.rb" with:
+      """ruby
+      RSpec.configure do |config|
+        config.expect_with :rspec do |c|
+          c.syntax = [:should, :expect]
+        end
+      end
+      """
+    When I run `rspec enable_both_syntaxes.rb syntaxes_spec.rb`
+    Then the examples should all pass
+

data/lib/rspec/expectations.rb

@@ -1,5 +1,7 @@
 require 'rspec/expectations/extensions'
 require 'rspec/matchers'
+require 'rspec/matchers/configuration'
+require 'rspec/expectations/expectation_target'
 require 'rspec/expectations/fail_with'
 require 'rspec/expectations/errors'
 require 'rspec/expectations/deprecation'

data/lib/rspec/expectations/expectation_target.rb

@@ -0,0 +1,52 @@
+module RSpec
+  module Expectations
+    # Wraps the target of an expectation.
+    # @example
+    #   expect(something) # => ExpectationTarget wrapping something
+    class ExpectationTarget
+      # @api private
+      def initialize(target)
+        @target = target
+      end
+
+      # Runs the given expectation, passing if `matcher` returns true.
+      # @example
+      #   expect(value).to eq(5)
+      #   expect { perform }.to raise_error
+      # @param [Matcher]
+      #   matcher
+      # @param [String] message optional message to display when the expectation fails
+      # @return [Boolean] true if the expectation succeeds (else raises)
+      # @see RSpec::Matchers
+      def to(matcher=nil, message=nil, &block)
+        prevent_operator_matchers(:to, matcher)
+        RSpec::Expectations::PositiveExpectationHandler.handle_matcher(@target, matcher, message, &block)
+      end
+
+      # Runs the given expectation, passing if `matcher` returns false.
+      # @example
+      #   expect(value).to_not eq(5)
+      #   expect(value).not_to eq(5)
+      # @param [Matcher]
+      #   matcher
+      # @param [String] message optional message to display when the expectation fails
+      # @return [Boolean] false if the negative expectation succeeds (else raises)
+      # @see RSpec::Matchers
+      def to_not(matcher=nil, message=nil, &block)
+        prevent_operator_matchers(:to_not, matcher)
+        RSpec::Expectations::NegativeExpectationHandler.handle_matcher(@target, matcher, message, &block)
+      end
+      alias not_to to_not
+
+    private
+
+      def prevent_operator_matchers(verb, matcher)
+        return if matcher
+
+        raise ArgumentError, "The expect syntax does not support operator matchers, " +
+                             "so you must pass a matcher to `##{verb}`."
+      end
+    end
+  end
+end
+

data/lib/rspec/expectations/extensions.rb

@@ -1,3 +1,2 @@
-require 'rspec/expectations/extensions/kernel'
 require 'rspec/expectations/extensions/array'
 require 'rspec/expectations/extensions/object'

data/lib/rspec/expectations/syntax.rb

@@ -0,0 +1,105 @@
+module RSpec
+  module Expectations
+    # @api private
+    # Provides methods for enabling and disabling the available
+    # syntaxes provided by rspec-expectations.
+    module Syntax
+      extend self
+
+      # @method should
+      # Passes if `matcher` returns true.  Available on every `Object`.
+      # @example
+      #   actual.should eq expected
+      #   actual.should match /expression/
+      # @param [Matcher]
+      #   matcher
+      # @param [String] message optional message to display when the expectation fails
+      # @return [Boolean] true if the expectation succeeds (else raises)
+      # @see RSpec::Matchers
+
+      # @method should_not
+      # Passes if `matcher` returns false.  Available on every `Object`.
+      # @example
+      #   actual.should_not eq expected
+      # @param [Matcher]
+      #   matcher
+      # @param [String] message optional message to display when the expectation fails
+      # @return [Boolean] false if the negative expectation succeeds (else raises)
+      # @see RSpec::Matchers
+
+      # @method expect
+      # Wraps `target` in an `ExpectationTarget`
+      # @return [ExpectationTarget]
+
+      # @api private
+      # Determines where we add `should` and `should_not`.
+      def default_should_host
+        @default_should_host ||= defined?(::BasicObject) ?
+                                 ::BasicObject : ::Kernel
+      end
+
+      # @api private
+      # Enables the `should` syntax.
+      def enable_should(syntax_host = default_should_host)
+        return if should_enabled?(syntax_host)
+
+        syntax_host.module_eval do
+          def should(matcher=nil, message=nil, &block)
+            ::RSpec::Expectations::PositiveExpectationHandler.handle_matcher(self, matcher, message, &block)
+          end
+
+          def should_not(matcher=nil, message=nil, &block)
+            ::RSpec::Expectations::NegativeExpectationHandler.handle_matcher(self, matcher, message, &block)
+          end
+        end
+      end
+
+      # @api private
+      # Disables the `should` syntax.
+      def disable_should(syntax_host = default_should_host)
+        return unless should_enabled?(syntax_host)
+
+        syntax_host.module_eval do
+          undef should
+          undef should_not
+        end
+      end
+
+      # @api private
+      # Enables the `expect` syntax.
+      def enable_expect(syntax_host = ::RSpec::Matchers)
+        return if expect_enabled?(syntax_host)
+
+        syntax_host.module_eval do
+          def expect(*target, &target_block)
+            target << target_block if block_given?
+            raise ArgumentError.new("You must pass an argument or a block to #expect but not both.") unless target.size == 1
+            ::RSpec::Expectations::ExpectationTarget.new(target.first)
+          end
+        end
+      end
+
+      # @api private
+      # Disables the `expect` syntax.
+      def disable_expect(syntax_host = ::RSpec::Matchers)
+        return unless expect_enabled?(syntax_host)
+
+        syntax_host.module_eval do
+          undef expect
+        end
+      end
+
+      # @api private
+      # Indicates whether or not the `should` syntax is enabled.
+      def should_enabled?(syntax_host = default_should_host)
+        syntax_host.method_defined?(:should)
+      end
+
+      # @api private
+      # Indicates whether or not the `expect` syntax is enabled.
+      def expect_enabled?(syntax_host = ::RSpec::Matchers)
+        syntax_host.method_defined?(:expect)
+      end
+    end
+  end
+end

data/lib/rspec/expectations/version.rb

@@ -2,7 +2,7 @@ module RSpec
   module Expectations
     # @private
     module Version
-      STRING = '2.10.0'
+      STRING = '2.11.0'
     end
   end
 end

data/lib/rspec/matchers.rb

@@ -181,7 +181,6 @@ require 'rspec/matchers/matcher'
 require 'rspec/matchers/operator_matcher'
 require 'rspec/matchers/be_close'
 
-require 'rspec/matchers/block_aliases'
 require 'rspec/matchers/generated_descriptions'
 require 'rspec/matchers/method_missing'
 require 'rspec/matchers/compatibility'
@@ -664,19 +663,27 @@ module RSpec
       BuiltIn::YieldSuccessiveArgs.new(*args)
     end
 
-    # Passes if actual contains all of the expected regardless of order. 
-    # This works for collections. Pass in multiple args  and it will only 
+    # Passes if actual contains all of the expected regardless of order.
+    # This works for collections. Pass in multiple args and it will only
     # pass if all args are found in collection.
     #
-    # NOTE: there is no should_not version of array.should =~ other_array
-    # 
+    # @note This is also available using the `=~` operator with `should`,
+    #       but `=~` is not supported with `expect`.
+    # @note There is no should_not version of array.should =~ other_array
+    #
     # @example
     #
+    #   expect([1,2,3]).to match_array([1,2,3])
+    #   expect([1,2,3]).to match_array([1,3,2])
     #   [1,2,3].should   =~ [1,2,3]   # => would pass
     #   [1,2,3].should   =~ [2,3,1]   # => would pass
     #   [1,2,3,4].should =~ [1,2,3]   # => would fail
     #   [1,2,2,3].should =~ [1,2,3]   # => would fail
     #   [1,2,3].should   =~ [1,2,3,4] # => would fail
+    def match_array(array)
+      BuiltIn::MatchArray.new(array)
+    end
+
     OperatorMatcher.register(Array, '=~', BuiltIn::MatchArray)
   end
 end