rspec-expectations 2.13.0 → 2.14.0.rc1

data/lib/rspec/expectations/fail_with.rb

@@ -52,7 +52,17 @@ module RSpec
 
       def coerce_to_string(string_or_array)
         return string_or_array unless Array === string_or_array
-        string_or_array.join(',')
+        diffably_stringify(string_or_array).join("\n")
+      end
+
+      def diffably_stringify(array)
+        array.map do |entry|
+          if Array === entry
+            entry.inspect
+          else
+            entry.to_s.gsub("\n", "\\n")
+          end
+        end
       end
 
       if String.method_defined?(:encoding)

data/lib/rspec/expectations/handler.rb

@@ -2,13 +2,14 @@ module RSpec
   module Expectations
 
     class ExpectationHandler
-      def self.message_must_be_string(msg)
-        "WARNING: ignoring the provided expectation message argument " +
-        "(#{msg.inspect}) since it is not a string."
-      end
-
       def self.check_message(msg)
-        ::Kernel.warn message_must_be_string(msg) unless msg.nil? || msg.is_a?(String)
+        unless msg.nil? || msg.respond_to?(:to_str) || msg.respond_to?(:call)
+          ::Kernel.warn [
+            "WARNING: ignoring the provided expectation message argument (",
+            msg.inspect,
+            ") since it is not a string or a proc."
+          ].join
+        end
       end
     end
 
@@ -23,6 +24,8 @@ module RSpec
         match = matcher.matches?(actual, &block)
         return match if match
 
+        message = message.call if message.respond_to?(:call)
+
         message ||= matcher.respond_to?(:failure_message_for_should) ?
                     matcher.failure_message_for_should :
                     matcher.failure_message
@@ -47,6 +50,8 @@ module RSpec
                 matcher.matches?(actual, &block)
         return match unless match
 
+        message = message.call if message.respond_to?(:call)
+
         message ||= matcher.respond_to?(:failure_message_for_should_not) ?
                     matcher.failure_message_for_should_not :
                     matcher.negative_failure_message

data/lib/rspec/expectations/syntax.rb

@@ -32,10 +32,10 @@ module RSpec
       # `ExpectationTarget`.
       # @example
       #   expect(actual).to eq(expected)
-      #   expect(actual).to_not eq(expected)
+      #   expect(actual).not_to eq(expected)
       # @return [ExpectationTarget]
       # @see ExpectationTarget#to
-      # @see ExpectationTarget#to_not
+      # @see ExpectationTarget#not_to
 
       # @api private
       # Determines where we add `should` and `should_not`.

data/lib/rspec/expectations/version.rb

@@ -2,7 +2,7 @@ module RSpec
   module Expectations
     # @private
     module Version
-      STRING = '2.13.0'
+      STRING = '2.14.0.rc1'
     end
   end
 end

data/lib/rspec/matchers.rb

@@ -1,5 +1,19 @@
+require 'rspec/matchers/extensions/instance_eval_with_args'
+require 'rspec/matchers/pretty'
+
+require 'rspec/matchers/built_in'
+require 'rspec/matchers/matcher'
+require 'rspec/matchers/operator_matcher'
+require 'rspec/matchers/be_close'
+
+require 'rspec/matchers/generated_descriptions'
+require 'rspec/matchers/method_missing'
+require 'rspec/matchers/compatibility'
+require 'rspec/matchers/dsl'
+require 'rspec/matchers/test_unit_integration'
+
 module RSpec
-  # RSpec::Matchers provides a number of useful matchers we use to compose
+  # RSpec::Matchers provides a number of useful matchers we use to define
   # expectations. A matcher is any object that responds to the following:
   #
   #     matches?(actual)
@@ -20,28 +34,29 @@ module RSpec
   # A Ruby predicate is a method that ends with a "?" and returns true or false.
   # Common examples are `empty?`, `nil?`, and `instance_of?`.
   #
-  # All you need to do is write `should be_` followed by the predicate without
-  # the question mark, and RSpec will figure it out from there. For example:
+  # All you need to do is write `expect(..).to be_` followed by the predicate
+  # without the question mark, and RSpec will figure it out from there.
+  # For example:
   #
-  #     [].should be_empty     # => [].empty?() | passes
-  #     [].should_not be_empty # => [].empty?() | fails
+  #     expect([]).to be_empty     # => [].empty?() | passes
+  #     expect([]).not_to be_empty # => [].empty?() | fails
   #
   # In addtion to prefixing the predicate matchers with "be_", you can also use "be_a_"
   # and "be_an_", making your specs read much more naturally:
   #
-  #     "a string".should be_an_instance_of(String) =>"a string".instance_of?(String) #passes
+  #     expect("a string").to be_an_instance_of(String) # =>"a string".instance_of?(String) # passes
   #
-  #     3.should be_a_kind_of(Fixnum)        # => 3.kind_of?(Numeric)     | passes
-  #     3.should be_a_kind_of(Numeric)       # => 3.kind_of?(Numeric)     | passes
-  #     3.should be_an_instance_of(Fixnum)   # => 3.instance_of?(Fixnum)  | passes
-  #     3.should_not be_instance_of(Numeric) # => 3.instance_of?(Numeric) | fails
+  #     expect(3).to be_a_kind_of(Fixnum)        # => 3.kind_of?(Numeric)     | passes
+  #     expect(3).to be_a_kind_of(Numeric)       # => 3.kind_of?(Numeric)     | passes
+  #     expect(3).to be_an_instance_of(Fixnum)   # => 3.instance_of?(Fixnum)  | passes
+  #     expect(3).not_to be_an_instance_of(Numeric) # => 3.instance_of?(Numeric) | fails
   #
   # RSpec will also create custom matchers for predicates like `has_key?`. To
   # use this feature, just state that the object should have_key(:key) and RSpec will
   # call has_key?(:key) on the target. For example:
   #
-  #     {:a => "A"}.should have_key(:a) # => {:a => "A"}.has_key?(:a) | passes
-  #     {:a => "A"}.should have_key(:b) # => {:a => "A"}.has_key?(:b) | fails
+  #     expect(:a => "A").to have_key(:a)
+  #     expect(:a => "A").to have_key(:b) # fails
   #
   # You can use this feature to invoke any predicate that begins with "has_", whether it is
   # part of the Ruby libraries (like `Hash#has_key?`) or a method you wrote on your own class.
@@ -58,15 +73,15 @@ module RSpec
   # zones on a virtual board. To specify that bob should be in zone 4, you
   # could say:
   #
-  #     bob.current_zone.should eql(Zone.new("4"))
+  #     expect(bob.current_zone).to eql(Zone.new("4"))
   #
   # But you might find it more expressive to say:
   #
-  #     bob.should be_in_zone("4")
+  #     expect(bob).to be_in_zone("4")
   #
   # and/or
   #
-  #     bob.should_not be_in_zone("3")
+  #     expect(bob).not_to be_in_zone("3")
   #
   # You can create such a matcher like so:
   #
@@ -102,7 +117,7 @@ module RSpec
   # passed to the <tt>create</tt> method (in this case, <tt>zone</tt>). The
   # failure message methods (<tt>failure_message_for_should</tt> and
   # <tt>failure_message_for_should_not</tt>) are passed the actual value (the
-  # receiver of <tt>should</tt> or <tt>should_not</tt>).
+  # receiver of <tt>expect(..)</tt> or <tt>expect(..).not_to</tt>).
   #
   # ### Custom Matcher from scratch
   #
@@ -158,35 +173,6 @@ module RSpec
   #     RSpec::configure do |config|
   #       config.include(CustomGameMatchers)
   #     end
-  module Matchers
-    # Include Matchers for other test frameworks.  Note that MiniTest _must_
-    # come before TU because on ruby 1.9, T::U::TC is a subclass of MT::U::TC
-    # and a 1.9 bug can lead to infinite recursion from the `super` call in our
-    # method_missing hook.  See this gist for more info:
-    # https://gist.github.com/845896
-    if defined?(MiniTest::Unit::TestCase)
-      MiniTest::Unit::TestCase.send(:include, self)
-    end
-    if defined?(Test::Unit::TestCase)
-      Test::Unit::TestCase.send(:include, self)
-    end
-  end
-end
-
-require 'rspec/matchers/extensions/instance_eval_with_args'
-require 'rspec/matchers/pretty'
-
-require 'rspec/matchers/built_in'
-require 'rspec/matchers/matcher'
-require 'rspec/matchers/operator_matcher'
-require 'rspec/matchers/be_close'
-
-require 'rspec/matchers/generated_descriptions'
-require 'rspec/matchers/method_missing'
-require 'rspec/matchers/compatibility'
-require 'rspec/matchers/dsl'
-
-module RSpec
   module Matchers
 
     # Passes if actual is truthy (anything but false or nil)
@@ -205,12 +191,12 @@ module RSpec
     end
 
     # @example
-    #   actual.should be_true
-    #   actual.should be_false
-    #   actual.should be_nil
-    #   actual.should be_[arbitrary_predicate](*args)
-    #   actual.should_not be_nil
-    #   actual.should_not be_[arbitrary_predicate](*args)
+    #   expect(actual).to     be_true
+    #   expect(actual).to     be_false
+    #   expect(actual).to     be_nil
+    #   expect(actual).to     be_[arbitrary_predicate](*args)
+    #   expect(actual).not_to be_nil
+    #   expect(actual).not_to be_[arbitrary_predicate](*args)
     #
     # Given true, false, or nil, will pass if actual value is true, false or
     # nil (respectively). Given no args means the caller should satisfy an if
@@ -240,9 +226,9 @@ module RSpec
     #
     # @example
     #
-    #   5.should be_instance_of(Fixnum)
-    #   5.should_not be_instance_of(Numeric)
-    #   5.should_not be_instance_of(Float)
+    #   expect(5).to     be_an_instance_of(Fixnum)
+    #   expect(5).not_to be_an_instance_of(Numeric)
+    #   expect(5).not_to be_an_instance_of(Float)
     def be_an_instance_of(expected)
       BuiltIn::BeAnInstanceOf.new(expected)
     end
@@ -253,9 +239,9 @@ module RSpec
     #
     # @example
     #
-    #   5.should be_kind_of(Fixnum)
-    #   5.should be_kind_of(Numeric)
-    #   5.should_not be_kind_of(Float)
+    #   expect(5).to     be_a_kind_of(Fixnum)
+    #   expect(5).to     be_a_kind_of(Numeric)
+    #   expect(5).not_to be_a_kind_of(Float)
     def be_a_kind_of(expected)
       BuiltIn::BeAKindOf.new(expected)
     end
@@ -266,8 +252,8 @@ module RSpec
     #
     # @example
     #
-    #   result.should be_within(0.5).of(3.0)
-    #   result.should_not be_within(0.5).of(3.0)
+    #   expect(result).to     be_within(0.5).of(3.0)
+    #   expect(result).not_to be_within(0.5).of(3.0)
     def be_within(delta)
       BuiltIn::BeWithin.new(delta)
     end
@@ -283,55 +269,59 @@ module RSpec
     #
     # When passing a block, it must use the <tt>{ ... }</tt> format, not
     # do/end, as <tt>{ ... }</tt> binds to the +change+ method, whereas do/end
-    # would errantly bind to the +should+ or +should_not+ method.
+    # would errantly bind to the +expect(..)+ or +expect(..).not_to+ method.
     #
     # @example
     #
-    #   lambda {
+    #   expect {
     #     team.add_player(player)
-    #   }.should change(roster, :count)
+    #   }.to change(roster, :count)
     #
-    #   lambda {
+    #   expect {
     #     team.add_player(player)
-    #   }.should change(roster, :count).by(1)
+    #   }.to change(roster, :count).by(1)
     #
-    #   lambda {
+    #   expect {
     #     team.add_player(player)
-    #   }.should change(roster, :count).by_at_least(1)
+    #   }.to change(roster, :count).by_at_least(1)
     #
-    #   lambda {
+    #   expect {
     #     team.add_player(player)
-    #   }.should change(roster, :count).by_at_most(1)
+    #   }.to change(roster, :count).by_at_most(1)
     #
     #   string = "string"
-    #   lambda {
+    #   expect {
     #     string.reverse!
-    #   }.should change { string }.from("string").to("gnirts")
+    #   }.to change { string }.from("string").to("gnirts")
     #
-    #   lambda {
+    #   string = "string"
+    #   expect {
+    #     string
+    #   }.not_to change { string }
+    #
+    #   expect {
     #     person.happy_birthday
-    #   }.should change(person, :birthday).from(32).to(33)
+    #   }.to change(person, :birthday).from(32).to(33)
     #
-    #   lambda {
+    #   expect {
     #     employee.develop_great_new_social_networking_app
-    #   }.should change(employee, :title).from("Mail Clerk").to("CEO")
+    #   }.to change(employee, :title).from("Mail Clerk").to("CEO")
     #
-    #   lambda {
+    #   expect {
     #     doctor.leave_office
-    #   }.should change(doctor, :sign).from(/is in/).to(/is out/)
+    #   }.to change(doctor, :sign).from(/is in/).to(/is out/)
     #
     #   user = User.new(:type => "admin")
-    #   lambda {
+    #   expect {
     #     user.symbolize_type
-    #   }.should change(user, :type).from(String).to(Symbol)
+    #   }.to change(user, :type).from(String).to(Symbol)
     #
     # == Notes
     #
     # Evaluates <tt>receiver.message</tt> or <tt>block</tt> before and after it
-    # evaluates the proc object (generated by the lambdas in the examples
-    # above).
+    # evaluates the block passed to <tt>expect</tt>.
     #
-    # <tt>should_not change</tt> only supports the form with no subsequent
+    # <tt>expect( ... ).not_to change</tt> only supports the form with no subsequent
     # calls to <tt>by</tt>, <tt>by_at_least</tt>, <tt>by_at_most</tt>,
     # <tt>to</tt> or <tt>from</tt>.
     def change(receiver=nil, message=nil, &block)
@@ -343,11 +333,11 @@ module RSpec
     # and it will only pass if all args are found in Range.
     #
     # @example
-    #   (1..10).should cover(5)
-    #   (1..10).should cover(4, 6)
-    #   (1..10).should cover(4, 6, 11) # will fail
-    #   (1..10).should_not cover(11)
-    #   (1..10).should_not cover(5)    # will fail
+    #   expect(1..10).to     cover(5)
+    #   expect(1..10).to     cover(4, 6)
+    #   expect(1..10).to     cover(4, 6, 11) # fails
+    #   expect(1..10).not_to cover(11)
+    #   expect(1..10).not_to cover(5)        # fails
     #
     # ### Warning:: Ruby >= 1.9 only
     def cover(*values)
@@ -361,45 +351,48 @@ module RSpec
     #
     # @example
     #
-    #   "this string".should end_with "string"
-    #   [0, 1, 2, 3, 4].should end_with 4
-    #   [0, 2, 3, 4, 4].should end_with 3, 4
+    #   expect("this string").to   end_with "string"
+    #   expect([0, 1, 2, 3, 4]).to end_with 4
+    #   expect([0, 2, 3, 4, 4]).to end_with 3, 4
     def end_with(*expected)
       BuiltIn::EndWith.new(*expected)
     end
 
     # Passes if <tt>actual == expected</tt>.
     #
-    # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more information about equality in Ruby.
+    # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more
+    # information about equality in Ruby.
     #
     # @example
     #
-    #   5.should eq(5)
-    #   5.should_not eq(3)
+    #   expect(5).to     eq(5)
+    #   expect(5).not_to eq(3)
     def eq(expected)
       BuiltIn::Eq.new(expected)
     end
 
     # Passes if +actual.eql?(expected)+
     #
-    # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more information about equality in Ruby.
+    # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more
+    # information about equality in Ruby.
     #
     # @example
     #
-    #   5.should eql(5)
-    #   5.should_not eql(3)
+    #   expect(5).to     eql(5)
+    #   expect(5).not_to eql(3)
     def eql(expected)
       BuiltIn::Eql.new(expected)
     end
 
     # Passes if <tt>actual.equal?(expected)</tt> (object identity).
     #
-    # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more information about equality in Ruby.
+    # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more
+    # information about equality in Ruby.
     #
     # @example
     #
-    #   5.should equal(5) # Fixnums are equal
-    #   "5".should_not equal("5") # Strings that look the same are not the same object
+    #   expect(5).to       equal(5)   # Fixnums are equal
+    #   expect("5").not_to equal("5") # Strings that look the same are not the same object
     def equal(expected)
       BuiltIn::Equal.new(expected)
     end
@@ -407,7 +400,7 @@ module RSpec
     # Passes if `actual.exist?` or `actual.exists?`
     #
     # @example
-    #   File.should exist("path/to/file")
+    #   expect(File).to exist("path/to/file")
     def exist(*args)
       BuiltIn::Exist.new(*args)
     end
@@ -430,16 +423,16 @@ module RSpec
     # @example
     #
     #   # Passes if team.players.size == 11
-    #   team.should have(11).players
+    #   expect(team).to have(11).players
     #
     #   # Passes if [1,2,3].length == 3
-    #   [1,2,3].should have(3).items #"items" is pure sugar
+    #   expect([1,2,3]).to have(3).items #"items" is pure sugar
     #
     #   # Passes if ['a', 'b', 'c'].count == 3
-    #   [1,2,3].should have(3).items #"items" is pure sugar
+    #   expect([1,2,3]).to have(3).items #"items" is pure sugar
     #
     #   # Passes if "this string".length == 11
-    #   "this string".should have(11).characters #"characters" is pure sugar
+    #   expect("this string").to have(11).characters #"characters" is pure sugar
     def have(n)
       BuiltIn::Have.new(n)
     end
@@ -448,11 +441,11 @@ module RSpec
     # Exactly like have() with >=.
     #
     # @example
-    #   "this".should have_at_least(3).letters
+    #   expect("this").to have_at_least(3).letters
     #
     # ### Warning:
     #
-    # `should_not have_at_least` is not supported
+    # `expect(..).not_to have_at_least` is not supported
     def have_at_least(n)
       BuiltIn::Have.new(n, :at_least)
     end
@@ -460,11 +453,11 @@ module RSpec
     # Exactly like have() with <=.
     #
     # @example
-    #   should have_at_most(number).items
+    #   expect("this").to have_at_most(4).letters
     #
     # ### Warning:
     #
-    # `should_not have_at_most` is not supported
+    # `expect(..).not_to have_at_most` is not supported
     def have_at_most(n)
       BuiltIn::Have.new(n, :at_most)
     end
@@ -475,12 +468,12 @@ module RSpec
     #
     # @example
     #
-    #   [1,2,3].should include(3)
-    #   [1,2,3].should include(2,3) #would pass
-    #   [1,2,3].should include(2,3,4) #would fail
-    #   [1,2,3].should_not include(4)
-    #   "spread".should include("read")
-    #   "spread".should_not include("red")
+    #   expect([1,2,3]).to      include(3)
+    #   expect([1,2,3]).to      include(2,3)
+    #   expect([1,2,3]).to      include(2,3,4) # fails
+    #   expect([1,2,3]).not_to  include(4)
+    #   expect("spread").to     include("read")
+    #   expect("spread").not_to include("red")
     def include(*expected)
       BuiltIn::Include.new(*expected)
     end
@@ -489,10 +482,10 @@ module RSpec
     #
     # @example
     #
-    #   email.should match(/^([^\s]+)((?:[-a-z0-9]+\.)+[a-z]{2,})$/i)
-    #   email.should match("@example.com")
-    #   zipcode.should match_regex(/\A\d{5}(-\d{4})?\z/)
-    #   zipcode.should match_regex("90210")
+    #   expect(email).to   match(/^([^\s]+)((?:[-a-z0-9]+\.)+[a-z]{2,})$/i)
+    #   expect(email).to   match("@example.com")
+    #   expect(zipcode).to match_regex(/\A\d{5}(-\d{4})?\z/)
+    #   expect(zipcode).to match_regex("90210")
     #
     # @note Due to Ruby's method dispatch mechanism, using the `#match` matcher
     # within a custom matcher defined via the matcher DSL
@@ -513,16 +506,16 @@ module RSpec
     #
     # @example
     #
-    #   lambda { do_something_risky }.should raise_error
-    #   lambda { do_something_risky }.should raise_error(PoorRiskDecisionError)
-    #   lambda { do_something_risky }.should raise_error(PoorRiskDecisionError) { |error| error.data.should == 42 }
-    #   lambda { do_something_risky }.should raise_error(PoorRiskDecisionError, "that was too risky")
-    #   lambda { do_something_risky }.should raise_error(PoorRiskDecisionError, /oo ri/)
+    #   expect { do_something_risky }.to raise_error
+    #   expect { do_something_risky }.to raise_error(PoorRiskDecisionError)
+    #   expect { do_something_risky }.to raise_error(PoorRiskDecisionError) { |error| expect(error.data).to eq 42 }
+    #   expect { do_something_risky }.to raise_error(PoorRiskDecisionError, "that was too risky")
+    #   expect { do_something_risky }.to raise_error(PoorRiskDecisionError, /oo ri/)
     #
-    #   lambda { do_something_risky }.should_not raise_error
-    #   lambda { do_something_risky }.should_not raise_error(PoorRiskDecisionError)
-    #   lambda { do_something_risky }.should_not raise_error(PoorRiskDecisionError, "that was too risky")
-    #   lambda { do_something_risky }.should_not raise_error(PoorRiskDecisionError, /oo ri/)
+    #   expect { do_something_risky }.not_to raise_error
+    #   expect { do_something_risky }.not_to raise_error(PoorRiskDecisionError)
+    #   expect { do_something_risky }.not_to raise_error(PoorRiskDecisionError, "that was too risky")
+    #   expect { do_something_risky }.not_to raise_error(PoorRiskDecisionError, /oo ri/)
     def raise_error(error=Exception, message=nil, &block)
       BuiltIn::RaiseError.new(error, message, &block)
     end
@@ -534,6 +527,8 @@ module RSpec
     #
     # @example
     #
+    # expect("string").to respond_to(:length)
+    #
     def respond_to(*names)
       BuiltIn::RespondTo.new(*names)
     end
@@ -550,9 +545,7 @@ module RSpec
     #
     # @example
     #
-    #   5.should satisfy { |n|
-    #     n > 3
-    #   }
+    #   expect(5).to satisfy { |n| n > 3 }
     def satisfy(&block)
       BuiltIn::Satisfy.new(&block)
     end
@@ -564,9 +557,9 @@ module RSpec
     #
     # @example
     #
-    #   "this string".should start_with "this s"
-    #   [0, 1, 2, 3, 4].should start_with 0
-    #   [0, 2, 3, 4, 4].should start_with 0, 1
+    #   expect("this string").to   start_with "this s"
+    #   expect([0, 1, 2, 3, 4]).to start_with 0
+    #   expect([0, 2, 3, 4, 4]).to start_with 0, 1
     def start_with(*expected)
       BuiltIn::StartWith.new(*expected)
     end
@@ -580,13 +573,13 @@ module RSpec
     #
     # @example
     #
-    #   lambda { do_something_risky }.should throw_symbol
-    #   lambda { do_something_risky }.should throw_symbol(:that_was_risky)
-    #   lambda { do_something_risky }.should throw_symbol(:that_was_risky, culprit)
+    #   expect { do_something_risky }.to throw_symbol
+    #   expect { do_something_risky }.to throw_symbol(:that_was_risky)
+    #   expect { do_something_risky }.to throw_symbol(:that_was_risky, 'culprit')
     #
-    #   lambda { do_something_risky }.should_not throw_symbol
-    #   lambda { do_something_risky }.should_not throw_symbol(:that_was_risky)
-    #   lambda { do_something_risky }.should_not throw_symbol(:that_was_risky, culprit)
+    #   expect { do_something_risky }.not_to throw_symbol
+    #   expect { do_something_risky }.not_to throw_symbol(:that_was_risky)
+    #   expect { do_something_risky }.not_to throw_symbol(:that_was_risky, 'culprit')
     def throw_symbol(expected_symbol=nil, expected_arg=nil)
       BuiltIn::ThrowSymbol.new(expected_symbol, expected_arg)
     end
@@ -679,17 +672,14 @@ module RSpec
     #
     # @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
+    #
+    # @note This matcher only supports positive expectations.
+    #       expect(..).not_to match_array(other_array) is not supported.
     #
     # @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