rspec-expectations 2.99.2 → 3.0.0.beta1

data/spec/rspec/matchers/change_spec.rb

@@ -193,8 +193,7 @@ end
 
 describe "expect { ... }.to change { block }" do
   o = SomethingExpected.new
-  o.some_value = 1
-  it_behaves_like "an RSpec matcher", :valid_value => lambda { o.some_value += 1 },
+  it_behaves_like "an RSpec matcher", :valid_value => lambda { o.some_value = 5 },
                                       :invalid_value => lambda { } do
     let(:matcher) { change { o.some_value } }
   end
@@ -248,80 +247,6 @@ describe "expect { ... }.not_to change { block }" do
   end
 end
 
-describe "expect { ... }.not_to change { }.from" do
-  context 'when the value starts at the from value' do
-    it 'passes when the value does not change' do
-      k = 5
-      expect { }.not_to change { k }.from(5)
-    end
-
-    it 'fails when the value does change' do
-      expect {
-        k = 5
-        expect { k += 1 }.not_to change { k }.from(5)
-      }.to fail_with(/but did change from 5 to 6/)
-    end
-
-    it 'does not issue a deprecation warning' do
-      expect(RSpec.configuration.reporter).not_to receive(:deprecation)
-      k = 5
-      expect { }.not_to change { k }.from(5)
-    end
-  end
-
-  context 'when the value starts at a different value' do
-    before { allow_deprecation }
-
-    it 'passes when the value does not change' do
-      k = 6
-      expect { }.not_to change { k }.from(5)
-    end
-
-    it 'passes when the value does change' do
-      k = 6
-      expect { k += 1 }.not_to change { k }.from(5)
-    end
-
-    it 'issues a deprecation warning' do
-      expect_deprecation_with_call_site(__FILE__, __LINE__ + 2, /#{Regexp.escape("expect { }.not_to change { }.from()")}/)
-      k = 6
-      expect { }.not_to change { k }.from(5)
-    end
-  end
-end
-
-describe "expect { ... }.not_to change { }.to" do
-  it 'issues a deprecation warning' do
-    expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /#{Regexp.escape("expect { }.not_to change { }.to()")}/)
-    expect {
-    }.not_to change { }.to(3)
-  end
-end
-
-describe "expect { ... }.not_to change { }.by" do
-  it 'issues a deprecation warning' do
-    expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /#{Regexp.escape("expect { }.not_to change { }.by()")}/)
-    expect {
-    }.not_to change { }.by(3)
-  end
-end
-
-describe "expect { ... }.not_to change { }.by_at_least" do
-  it 'issues a deprecation warning' do
-    expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /#{Regexp.escape("expect { }.not_to change { }.by_at_least()")}/)
-    expect {
-    }.not_to change { }.by_at_least(3)
-  end
-end
-
-describe "expect { ... }.not_to change { }.by_at_most" do
-  it 'issues a deprecation warning' do
-    expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /#{Regexp.escape("expect { }.not_to change { }.by_at_most()")}/)
-    expect {
-    }.not_to change { }.by_at_most(3)
-  end
-end
-
 describe "expect { ... }.to change(actual, message).by(expected)" do
   before(:each) do
     @instance = SomethingExpected.new

data/spec/rspec/{expectations → matchers}/configuration_spec.rb

@@ -2,10 +2,10 @@ require 'spec_helper'
 require 'delegate'
 
 module RSpec
-  module Expectations
+  module Matchers
     describe "RSpec::Matchers.configuration" do
       it 'returns a memoized configuration instance' do
-        expect(RSpec::Matchers.configuration).to be_a(RSpec::Expectations::Configuration)
+        expect(RSpec::Matchers.configuration).to be_a(RSpec::Matchers::Configuration)
         expect(RSpec::Matchers.configuration).to be(RSpec::Matchers.configuration)
       end
     end
@@ -13,25 +13,6 @@ module RSpec
     describe Configuration do
       let(:config) { Configuration.new }
 
-      context "when accessing it using the old 2.x const name" do
-        it 'returns the new constant' do
-          allow_deprecation
-          expect(RSpec::Matchers::Configuration).to be(RSpec::Expectations::Configuration)
-        end
-
-        it 'issues a deprecation warning' do
-          expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /RSpec::Matchers::Configuration/)
-          RSpec::Matchers::Configuration
-        end
-
-        it 'allows other undefined constant to raise errors like normal' do
-          expect_no_deprecation
-          expect {
-            RSpec::Matchers::FooBarBazz
-          }.to raise_error(NameError, /RSpec::Matchers::FooBarBazz/)
-        end
-      end
-
       describe "#backtrace_formatter" do
         let(:original_backtrace) { %w[ clean-me/a.rb other/file.rb clean-me/b.rb ] }
         let(:cleaned_backtrace)  { %w[ other/file.rb ] }
@@ -42,11 +23,14 @@ module RSpec
 
         before do
           @old_patterns = RSpec.configuration.backtrace_exclusion_patterns
+          @orig_full_backtrace = RSpec.configuration.full_backtrace?
+          RSpec.configuration.full_backtrace = false
           RSpec.configuration.backtrace_exclusion_patterns = [/clean-me/]
         end
 
         after do
           RSpec.configuration.backtrace_exclusion_patterns = @old_patterns
+          RSpec.configuration.full_backtrace = @orig_full_backtrace
         end
 
         it "defaults to rspec-core's backtrace formatter when rspec-core is loaded" do
@@ -124,6 +108,37 @@ module RSpec
           configure_syntax :expect
         end
 
+        describe "`:should` being enabled by default deprecation" do
+          before { configure_default_syntax }
+
+          it "warns when the should syntax is called by default" do
+            expected_arguments = [
+              /Using.*without explicitly enabling/,
+              {:replacement=>"the new `:expect` syntax or explicitly enable `:should`"}
+            ]
+
+            expect(RSpec).to receive(:deprecate).with(*expected_arguments)
+            3.should eq(3)
+          end
+
+          it "includes the call site in the deprecation warning by default" do
+            expect_deprecation_with_call_site(__FILE__, __LINE__ + 1)
+            3.should eq(3)
+          end
+
+          it "does not warn when only the should syntax is explicitly configured" do
+            configure_syntax(:should)
+            RSpec.should_not_receive(:deprecate)
+            3.should eq(3)
+          end
+
+          it "does not warn when both the should and expect syntaxes are explicitly configured" do
+            configure_syntax([:should, :expect])
+            expect(RSpec).not_to receive(:deprecate)
+            3.should eq(3)
+          end
+        end
+
         it 'can re-enable the :should syntax' do
           configure_syntax :expect
           configure_syntax [:should, :expect]
@@ -179,6 +194,10 @@ module RSpec
         end
       end
 
+      def configure_default_syntax
+        RSpec::Matchers.configuration.reset_syntaxes_to_default
+      end
+
       describe "configuring rspec-expectations directly" do
         it_behaves_like "configuring the expectation syntax" do
           def configure_syntax(syntax)
@@ -201,6 +220,7 @@ module RSpec
             end
           end
 
+
           def configured_syntax
             RSpec.configure do |rspec|
               rspec.expect_with :rspec do |c|

data/spec/rspec/matchers/description_generation_spec.rb

@@ -92,25 +92,6 @@ describe "Matchers should be able to generate their own descriptions" do
     expect(RSpec::Matchers.generated_description).to eq 'should have taste for "wine", "cheese"'
   end
 
-  context "the deprecated collection cardinality matchers" do
-    before { allow_deprecation }
-
-    it "expect(...).to have n items" do
-      expect(team).to have(3).players
-      expect(RSpec::Matchers.generated_description).to eq "should have 3 players"
-    end
-
-    it "expect(...).to have at least n items" do
-      expect(team).to have_at_least(2).players
-      expect(RSpec::Matchers.generated_description).to eq "should have at least 2 players"
-    end
-
-    it "expect(...).to have at most n items" do
-      expect(team).to have_at_most(4).players
-      expect(RSpec::Matchers.generated_description).to eq "should have at most 4 players"
-    end
-  end
-
   it "expect(...).to include(x)" do
     expect([1,2,3]).to include(3)
     expect(RSpec::Matchers.generated_description).to eq "should include 3"
@@ -130,9 +111,9 @@ describe "Matchers should be able to generate their own descriptions" do
     expect(RSpec::Matchers.generated_description).to eq "should include description"
   end
 
-  it "expect(array).not_to match_array [1,2,3]" do
+  it "expect(array).to match_array [1,2,3]" do
     expect([1,2,3]).to match_array [1,2,3]
-    expect(RSpec::Matchers.generated_description).to eq "should contain exactly 1, 2, and 3"
+    expect(RSpec::Matchers.generated_description).to eq "should contain exactly 1, 2 and 3"
   end
 
   it "expect(...).to match" do

data/spec/rspec/matchers/equal_spec.rb

@@ -24,32 +24,6 @@ module RSpec
         expect(matcher.description).to eq "equal 1"
       end
 
-      context "when the expected object is falsey in conditinal semantics" do
-        it "describes itself with the expected object" do
-          matcher = equal(nil)
-          matcher.matches?(nil)
-          expect(matcher.description).to eq "equal nil"
-        end
-      end
-
-      context "when the expected object's #equal? always returns true" do
-        let(:strange_string) do
-          string = "foo"
-
-          def string.equal?(other)
-            true
-          end
-
-          string
-        end
-
-        it "describes itself with the expected object" do
-          matcher = equal(strange_string)
-          matcher.matches?(strange_string)
-          expect(matcher.description).to eq 'equal "foo"'
-        end
-      end
-
       it "suggests the `eq` matcher on failure" do
         expected, actual = "1", "1"
         expect {

data/spec/rspec/matchers/has_spec.rb

@@ -48,20 +48,6 @@ describe "expect(...).to have_sym(*args)" do
     }.to raise_error(NoMethodError)
   end
 
-  it "warns of deprecation if #has_sym?(*args) is private" do
-    klass = Class.new do
-      def has_foo?
-        true
-      end
-      private :has_foo?
-
-      # prevents double deprecation
-      def respond_to?(_); true; end
-    end
-    expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /matching with have_foo on private method/)
-    expect(klass.new).to have_foo
-  end
-
   it "reraises an exception thrown in #has_sym?(*args)" do
     o = Object.new
     def o.has_sym?(*args)
@@ -71,16 +57,6 @@ describe "expect(...).to have_sym(*args)" do
       expect(o).to have_sym(:foo)
     }.to raise_error("Funky exception")
   end
-
-  it 'warns of deprecation when actual does not respond to #has_sym?' do
-    foo_class = Class.new do
-      def method_missing(method)
-        return true if method == :has_foo?
-      end
-    end
-    expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /Matching with have_foo on an object that doesn't respond to `has_foo\?`/)
-    expect(foo_class.new).to have_foo
-  end
 end
 
 describe "expect(...).not_to have_sym(*args)" do

data/spec/rspec/matchers/match_array_spec.rb

@@ -47,19 +47,6 @@ describe "should =~ array", :uses_should do
       array.should =~ array
     end
   end
-
-  context "when the array undefines `=~`" do
-    it 'still works' do
-      array_klass = Class.new(Array) { undef =~ }
-      array = array_klass.new([1, 2])
-
-      array.should =~ [1, 2]
-
-      expect {
-        array.should =~ [0, 1, 2]
-      }.to fail_with(/expected collection contained/)
-    end
-  end
 end
 
 describe "should_not =~ [:with, :multiple, :args]", :uses_should do

data/spec/rspec/matchers/matcher_spec.rb

@@ -1,15 +1,16 @@
+# encoding: utf-8
 require 'spec_helper'
 
 class UnexpectedError < StandardError; end
 module MatcherHelperModule
   def self.included(base)
-    base.module_eval do
+    base.module_exec do
       def included_method; end
     end
   end
 
   def self.extended(base)
-    base.instance_eval do
+    base.instance_exec do
       def extended_method; end
     end
   end
@@ -21,6 +22,12 @@ end
 
 module RSpec::Matchers::DSL
   describe Matcher do
+    def new_matcher(name, *expected, &block)
+      RSpec::Matchers::DSL::Matcher.
+        new(name, block, *expected).
+        tap { |m| m.matcher_execution_context = self }
+    end
+
     it "can be stored aside and used later" do
       # Supports using rspec-expectation matchers as argument matchers in
       # rspec-mocks.
@@ -39,10 +46,10 @@ module RSpec::Matchers::DSL
 
     context "with an included module" do
       let(:matcher) do
-        RSpec::Matchers::DSL::Matcher.new(:be_a_greeting) do
+        new_matcher(:be_a_greeting) do
           include MatcherHelperModule
           match { |actual| actual == greeting }
-        end.for_expected
+        end
       end
 
       it "has access to the module's methods" do
@@ -58,64 +65,41 @@ module RSpec::Matchers::DSL
       end
 
       it 'allows multiple modules to be included at once' do
-        m = RSpec::Matchers::DSL::Matcher.new(:multiple_modules) do
+        m = new_matcher(:multiple_modules) do
           include Enumerable, Comparable
-        end.for_expected
+        end
         expect(m).to be_a(Enumerable)
         expect(m).to be_a(Comparable)
       end
     end
 
-    context "matching blocks" do
-      it 'warns when matching blocks by default' do
-        matcher = RSpec::Matchers::DSL::Matcher.new(:not_supporting_blocks) do
-          match { true }
-        end.for_expected
-
-        expect_deprecation_with_call_site(__FILE__, __LINE__ + 2, /block expectation/)
-        expect(3).to matcher
-        expect { 3 }.to matcher
-      end
-
-      it 'does not when if it declares `supports_block_expectations`' do
-        matcher = RSpec::Matchers::DSL::Matcher.new(:supporting_blocks) do
-          match { true }
-          supports_block_expectations
-        end.for_expected
-
-        expect_no_deprecation
-        expect(3).to matcher
-        expect { 3 }.to matcher
-      end
-    end
-
     context "without overrides" do
-      before(:each) do
-        @matcher = RSpec::Matchers::DSL::Matcher.new(:be_a_multiple_of) do |multiple|
+      let(:matcher) do
+        new_matcher(:be_a_multiple_of, 3) do |multiple|
           match do |actual|
             actual % multiple == 0
           end
-        end.for_expected(3)
+        end
       end
 
       it "provides a default description" do
-        expect(@matcher.description).to eq "be a multiple of 3"
+        expect(matcher.description).to eq "be a multiple of 3"
       end
 
       it "provides a default failure message for #should" do
-        @matcher.matches?(8)
-        expect(@matcher.failure_message_for_should).to eq "expected 8 to be a multiple of 3"
+        matcher.matches?(8)
+        expect(matcher.failure_message_for_should).to eq "expected 8 to be a multiple of 3"
       end
 
       it "provides a default failure message for #should_not" do
-        @matcher.matches?(9)
-        expect(@matcher.failure_message_for_should_not).to eq "expected 9 not to be a multiple of 3"
+        matcher.matches?(9)
+        expect(matcher.failure_message_for_should_not).to eq "expected 9 not to be a multiple of 3"
       end
     end
 
     context "with separate match logic for should and should not" do
       let(:matcher) do
-        RSpec::Matchers::DSL::Matcher.new(:to_be_composed_of) do |a, b|
+        new_matcher(:to_be_composed_of, 7, 11) do |a, b|
           match_for_should do |actual|
             actual == a * b
           end
@@ -123,7 +107,7 @@ module RSpec::Matchers::DSL
           match_for_should_not do |actual|
             actual == a + b
           end
-        end.for_expected(7, 11)
+        end
       end
 
       it "invokes the match_for_should block for #matches?" do
@@ -140,82 +124,194 @@ module RSpec::Matchers::DSL
         matcher.does_not_match?(77)
         expect(matcher.failure_message_for_should_not).to eq "expected 77 not to to be composed of 7 and 11"
       end
+
+      it 'can access helper methods from `match_for_should_not`' do
+        matcher = new_matcher(:be_foo) do
+          def foo
+            :foo
+          end
+
+          match_for_should_not do |actual|
+            actual != foo
+          end
+        end
+
+        expect(matcher.does_not_match?(:bar)).to be true
+      end
     end
 
     it "allows helper methods to be defined with #define_method to have access to matcher parameters" do
-      matcher = RSpec::Matchers::DSL::Matcher.new(:name) do |a, b|
+      matcher = new_matcher(:name, 3, 4) do |a, b|
         define_method(:sum) { a + b }
-      end.for_expected(3,4)
+      end
 
       expect(matcher.sum).to eq 7
     end
 
     it "is not diffable by default" do
-      matcher = RSpec::Matchers::DSL::Matcher.new(:name) {}
+      matcher = new_matcher(:name) { }
       expect(matcher).not_to be_diffable
     end
 
     it "is diffable when told to be" do
-      matcher = RSpec::Matchers::DSL::Matcher.new(:name) { diffable }.for_expected
+      matcher = new_matcher(:name) { diffable }
       expect(matcher).to be_diffable
     end
 
-    it "provides expected" do
-      expect_no_deprecation
-      matcher = RSpec::Matchers::DSL::Matcher.new(:name) {}.for_expected('expected', 'strings')
-      expect(matcher.expected).to eq %w[expected strings]
-    end
+    it 'does not confuse the diffability of different matchers' do
+      # Necessary to guard against a regression that involved
+      # using a class variable to store the diffable state,
+      # which had the side effect of causing all custom matchers
+      # to share that state
+      m1 = new_matcher(:m1) { diffable }
+      m2 = new_matcher(:m2) { }
+      m3 = new_matcher(:m3) { diffable }
 
-    it "provides expected as an array" do
-      expect_no_deprecation
-      matcher = RSpec::Matchers::DSL::Matcher.new(:name) {}.for_expected('expected string')
-      expect(matcher.expected_as_array).to eq ['expected string']
+      expect(m1).to be_diffable
+      expect(m2).not_to be_diffable
+      expect(m3).to be_diffable
     end
 
-    it "warns of deprecation about expected when it's a single value" do
-      expect_deprecation_with_call_site __FILE__, __LINE__ + 2
-      matcher = RSpec::Matchers::DSL::Matcher.new(:name) {}.for_expected('expected string')
+    it "provides expected" do
+      matcher = new_matcher(:name, "expected string") { }
       expect(matcher.expected).to eq ['expected string']
     end
 
-    it "provides actual" do
-      matcher = RSpec::Matchers::DSL::Matcher.new(:name) do
+    it "provides actual when `match` is used" do
+      matcher = new_matcher(:name, 'expected string') do
         match {|actual|}
-      end.for_expected('expected string')
+      end
 
       matcher.matches?('actual string')
 
       expect(matcher.actual).to eq 'actual string'
     end
 
-    context "wrapping another expectation (should == ...)" do
-      it "returns true if the wrapped expectation passes" do
-        matcher = RSpec::Matchers::DSL::Matcher.new(:name) do |expected|
+    it "provides actual when the `match` block accepts splat args" do
+      matcher = new_matcher(:actual) do
+        match { |*actual| actual == [5] }
+      end
+
+      expect(matcher.matches?(5)).to be true
+      expect(matcher.matches?(4)).to be false
+    end
+
+    it 'allows an early `return` to be used from a `match` block' do
+      matcher = new_matcher(:with_return, 5) do |expected|
+        match { |actual| return true if expected == actual }
+      end
+
+      expect(matcher.matches?(5)).to be true
+      expect(matcher.matches?(4)).to be_falsey
+    end
+
+    it 'provides actual when `match_unless_raises` is used' do
+      matcher = new_matcher(:name, 'expected string') do
+        match_unless_raises(SyntaxError) {|actual|}
+      end
+
+      matcher.matches?('actual string')
+
+      expect(matcher.actual).to eq 'actual string'
+    end
+
+    it 'allows an early `return` to be used from a `match_unless_raises` block' do
+      matcher = new_matcher(:with_return) do |expected|
+        match_unless_raises(ArgumentError) do |actual|
+          return actual if [true, false].include?(actual)
+          raise ArgumentError
+        end
+      end
+
+      expect(matcher.matches?(true)).to be true
+      # It should match even if it returns false, because no error was raised.
+      expect(matcher.matches?(false)).to be true
+      expect(matcher.matches?(4)).to be_falsey
+    end
+
+    it 'provides actual when `match_for_should_not` is used' do
+      matcher = new_matcher(:name, 'expected string') do
+        match_for_should_not {|actual|}
+      end
+
+      matcher.does_not_match?('actual string')
+
+      expect(matcher.actual).to eq 'actual string'
+    end
+
+    it 'allows an early `return` to be used from a `match_for_should_not` block' do
+      matcher = new_matcher(:with_return, 5) do |expected|
+        match_for_should_not { |actual| return true if expected != actual }
+      end
+
+      expect(matcher.does_not_match?(5)).to be_falsey
+      expect(matcher.does_not_match?(4)).to be true
+    end
+
+    context "wrapping another expectation (expect(...).to eq ...)" do
+      let(:matcher) do
+        new_matcher(:name, "value") do |expected|
           match do |actual|
             expect(actual).to eq expected
           end
-        end.for_expected('value')
+        end
+      end
+
+      it "returns true if the wrapped expectation passes" do
         expect(matcher.matches?('value')).to be_truthy
       end
 
       it "returns false if the wrapped expectation fails" do
-        matcher = RSpec::Matchers::DSL::Matcher.new(:name) do |expected|
-          match do |actual|
-            expect(actual).to eq expected
-          end
-        end.for_expected('value')
         expect(matcher.matches?('other value')).to be_falsey
       end
+
+      it "can use the `include` matcher from a `match` block" do
+        RSpec::Matchers.define(:descend_from) do |mod|
+          match do |klass|
+            expect(klass.ancestors).to include(mod)
+          end
+        end
+
+        expect(Fixnum).to descend_from(Object)
+        expect(Fixnum).not_to descend_from(Array)
+
+        expect {
+          expect(Fixnum).to descend_from(Array)
+        }.to fail_with(/expected Fixnum to descend from Array/)
+
+        expect {
+          expect(Fixnum).not_to descend_from(Object)
+        }.to fail_with(/expected Fixnum not to descend from Object/)
+      end
+
+      it "can use the `match` matcher from a `match` block" do
+        RSpec::Matchers.define(:be_a_phone_number_string) do
+          match do |string|
+            expect(string).to match(/\A\d{3}\-\d{3}\-\d{4}\z/)
+          end
+        end
+
+        expect("206-123-1234").to be_a_phone_number_string
+        expect("foo").not_to be_a_phone_number_string
+
+        expect {
+          expect("foo").to be_a_phone_number_string
+        }.to fail_with(/expected "foo" to be a phone number string/)
+
+        expect {
+          expect("206-123-1234").not_to be_a_phone_number_string
+        }.to fail_with(/expected "206-123-1234" not to be a phone number string/)
+      end
     end
 
     context "with overrides" do
-      before(:each) do
-        @matcher = RSpec::Matchers::DSL::Matcher.new(:be_boolean) do |boolean|
+      let(:matcher) do
+        new_matcher(:be_boolean, true) do |boolean|
           match do |actual|
             actual
           end
-          description do
-            "be the boolean #{boolean}"
+          description do |actual|
+            "be the boolean #{boolean} (actual was #{actual})"
           end
           failure_message_for_should do |actual|
             "expected #{actual} to be the boolean #{boolean}"
@@ -223,108 +319,160 @@ module RSpec::Matchers::DSL
           failure_message_for_should_not do |actual|
             "expected #{actual} not to be the boolean #{boolean}"
           end
-        end.for_expected(true)
+        end
       end
 
       it "does not hide result of match block when true" do
-        expect(@matcher.matches?(true)).to be_truthy
+        expect(matcher.matches?(true)).to be_truthy
       end
 
       it "does not hide result of match block when false" do
-        expect(@matcher.matches?(false)).to be_falsey
+        expect(matcher.matches?(false)).to be_falsey
       end
 
-      it "overrides the description" do
-        expect(@matcher.description).to eq "be the boolean true"
+      it "overrides the description (which yields `actual`)" do
+        matcher.matches?(true)
+        expect(matcher.description).to eq "be the boolean true (actual was true)"
       end
 
       it "overrides the failure message for #should" do
-        @matcher.matches?(false)
-        expect(@matcher.failure_message_for_should).to eq "expected false to be the boolean true"
+        matcher.matches?(false)
+        expect(matcher.failure_message_for_should).to eq "expected false to be the boolean true"
       end
 
       it "overrides the failure message for #should_not" do
-        @matcher.matches?(true)
-        expect(@matcher.failure_message_for_should_not).to eq "expected true not to be the boolean true"
+        matcher.matches?(true)
+        expect(matcher.failure_message_for_should_not).to eq "expected true not to be the boolean true"
+      end
+
+      it 'can access helper methods from `description`' do
+        matcher = new_matcher(:desc) do
+          def subdesc() "sub description" end
+          description { "Desc (#{subdesc})" }
+        end
+
+        expect(matcher.description).to eq("Desc (sub description)")
+      end
+
+      it 'can access helper methods from `failure_message_for_should`' do
+        matcher = new_matcher(:positive_failure_message) do
+          def helper() "helper" end
+          failure_message_for_should { helper }
+        end
+
+        expect(matcher.failure_message_for_should).to eq("helper")
+      end
+
+      it 'can access helper methods from `failure_message_for_should_not`' do
+        matcher = new_matcher(:negative_failure_message) do
+          def helper() "helper" end
+          failure_message_for_should_not { helper }
+        end
+
+        expect(matcher.failure_message_for_should_not).to eq("helper")
+      end
+
+      it 'can exit early with a `return` from `description` just like in a method' do
+        matcher = new_matcher(:desc) do
+          description { return "Desc" }
+        end
+
+        expect(matcher.description).to eq("Desc")
+      end
+
+      it 'can exit early with a `return` from `failure_message_for_should` just like in a method' do
+        matcher = new_matcher(:positive_failure_message) do
+          failure_message_for_should { return "msg" }
+        end
+
+        expect(matcher.failure_message_for_should).to eq("msg")
+      end
+
+      it 'can exit early with a `return` from `failure_message_for_should_not` just like in a method' do
+        matcher = new_matcher(:negative_failure_message) do
+          failure_message_for_should_not { return "msg" }
+        end
+
+        expect(matcher.failure_message_for_should_not).to eq("msg")
       end
     end
 
     context "#new" do
       it "passes matches? arg to match block" do
-        matcher = RSpec::Matchers::DSL::Matcher.new(:ignore) do
+        matcher = new_matcher(:ignore) do
           match do |actual|
             actual == 5
           end
-        end.for_expected
+        end
         expect(matcher.matches?(5)).to be_truthy
       end
 
       it "exposes arg submitted through #new to matcher block" do
-        matcher = RSpec::Matchers::DSL::Matcher.new(:ignore) do |expected|
+        matcher = new_matcher(:ignore, 4) do |expected|
           match do |actual|
             actual > expected
           end
-        end.for_expected(4)
+        end
         expect(matcher.matches?(5)).to be_truthy
       end
     end
 
     context "with no args" do
-      before(:each) do
-        @matcher = RSpec::Matchers::DSL::Matcher.new(:matcher_name) do
+      let(:matcher) do
+        new_matcher(:matcher_name) do
           match do |actual|
             actual == 5
           end
-        end.for_expected
+        end
       end
 
       it "matches" do
-        expect(@matcher.matches?(5)).to be_truthy
+        expect(matcher.matches?(5)).to be_truthy
       end
 
       it "describes" do
-        expect(@matcher.description).to eq "matcher name"
+        expect(matcher.description).to eq "matcher name"
       end
     end
 
     context "with 1 arg" do
-      before(:each) do
-        @matcher = RSpec::Matchers::DSL::Matcher.new(:matcher_name) do |expected|
+      let(:matcher) do
+        new_matcher(:matcher_name, 1) do |expected|
           match do |actual|
             actual == 5 && expected == 1
           end
-        end.for_expected(1)
+        end
       end
 
       it "matches" do
-        expect(@matcher.matches?(5)).to be_truthy
+        expect(matcher.matches?(5)).to be_truthy
       end
 
       it "describes" do
-        expect(@matcher.description).to eq "matcher name 1"
+        expect(matcher.description).to eq "matcher name 1"
       end
     end
 
     context "with multiple args" do
-      before(:each) do
-        @matcher = RSpec::Matchers::DSL::Matcher.new(:matcher_name) do |a,b,c,d|
+      let(:matcher) do
+        new_matcher(:matcher_name, 1, 2, 3, 4) do |a, b, c, d|
           match do |sum|
             a + b + c + d == sum
           end
-        end.for_expected(1,2,3,4)
+        end
       end
 
       it "matches" do
-        expect(@matcher.matches?(10)).to be_truthy
+        expect(matcher.matches?(10)).to be_truthy
       end
 
       it "describes" do
-        expect(@matcher.description).to eq "matcher name 1, 2, 3, and 4"
+        expect(matcher.description).to eq "matcher name 1, 2, 3, and 4"
       end
     end
 
     it "supports helper methods" do
-      matcher = RSpec::Matchers::DSL::Matcher.new(:be_similar_to) do |sample|
+      matcher = new_matcher(:be_similar_to, [1, 2, 3]) do |sample|
         match do |actual|
           similar?(sample, actual)
         end
@@ -332,159 +480,35 @@ module RSpec::Matchers::DSL
         def similar?(a, b)
           a.sort == b.sort
         end
-      end.for_expected([1,2,3])
+      end
 
       expect(matcher.matches?([2,3,1])).to be_truthy
     end
 
     it "supports fluent interface" do
-      matcher = RSpec::Matchers::DSL::Matcher.new(:first_word) do
+      matcher = new_matcher(:first_word) do
         def second_word
           self
         end
-      end.for_expected
+      end
 
       expect(matcher.second_word).to eq matcher
     end
 
     it "treats method missing normally for undeclared methods" do
-      matcher = RSpec::Matchers::DSL::Matcher.new(:ignore) { }.for_expected
+      matcher = new_matcher(:ignore) { }
       expect { matcher.non_existent_method }.to raise_error(NoMethodError)
     end
 
     it "has access to other matchers" do
-      matcher = RSpec::Matchers::DSL::Matcher.new(:ignore) do |expected|
+      matcher = new_matcher(:ignore, 3) do |expected|
         match do |actual|
           extend RSpec::Matchers
           expect(actual).to eql(5 + expected)
         end
-      end.for_expected(3)
-
-      expect(matcher.matches?(8)).to be_truthy
-    end
-
-    shared_examples_for "accessing a singleton helper method" do
-      before { allow_deprecation }
-
-      it 'can access the helper method from `match`' do
-        expect([2, 3]).to matcher.for_expected(5)
-        expect([2, 3]).not_to matcher.for_expected(4)
-      end
-
-      it 'prints a deprecation warning when the helper method is accessed `match`' do
-        expect(RSpec).to receive(:deprecate).with(/sum_of/, an_instance_of(Hash))
-        matcher.for_expected(5).matches?([2, 3])
-      end
-
-      it 'includes the call site in the deprecation warning' do
-        expect_deprecation_with_call_site(__FILE__, line)
-        matcher.for_expected(5).matches?([2, 3])
-      end
-
-      it 'does not print a deprecation warning if the helper method is used as a macro' do
-        expect(RSpec).not_to receive(:deprecate)
-        matcher.for_expected(:use_as_macro).matches?([2, 3])
       end
-    end
 
-    context "when a module of helper methods is extended" do
-      include_examples "accessing a singleton helper method" do
-        let(:matcher) do
-          RSpec::Matchers::DSL::Matcher.new(:sum_to) do |sum|
-            extend Module.new {
-              def sum_of(x, y) x + y end
-              def define_match() match {} end
-            }
-
-            if sum == :use_as_macro
-              define_match
-            else
-              match { |summands| sum_of(*summands) == sum }
-            end
-          end
-        end
-        let(:line) { __LINE__ - 4 }
-      end
-    end
-
-    context "when a helper method is defined using `self.`" do
-      include_examples "accessing a singleton helper method" do
-        let(:matcher) do
-          RSpec::Matchers::DSL::Matcher.new(:sum_to) do |sum|
-            def self.sum_of(x, y) x + y end
-            def self.define_match() match {} end
-
-            if sum == :use_as_macro
-              define_match
-            else
-              match { |summands| sum_of(*summands) == sum }
-            end
-          end
-        end
-        let(:line) { __LINE__ - 4 }
-      end
-    end
-
-    shared_examples_for "accessing an instance helper method" do
-      before { allow_deprecation }
-
-      it 'can access the helper method from `match`' do
-        expect([2, 3]).to matcher.for_expected(5)
-        expect([2, 3]).not_to matcher.for_expected(4)
-      end
-
-      it 'does not print a deprecation warning when the helper method is accessed from `match`' do
-        expect(RSpec).not_to receive(:deprecate)
-        matcher.for_expected(5).matches?([2, 3])
-      end
-
-      it 'prints a deprecation warning if the helper method is used as a macro' do
-        expect(RSpec).to receive(:deprecate).with(/define_match/, an_instance_of(Hash))
-        matcher.for_expected(:use_as_macro).matches?([2, 3])
-      end
-
-      it 'includes the call site in the deprecation warning' do
-        expect_deprecation_with_call_site(__FILE__, line)
-        matcher.for_expected(:use_as_macro).matches?([2, 3])
-      end
-    end
-
-    context "when a module of helper methods is included" do
-      include_examples "accessing an instance helper method" do
-        let(:matcher) do
-          RSpec::Matchers::DSL::Matcher.new(:sum_to) do |sum|
-            include Module.new {
-              def sum_of(x, y) x + y end
-              def define_match() match {} end
-            }
-
-            if sum == :use_as_macro
-              define_match
-            else
-              match { |summands| sum_of(*summands) == sum }
-            end
-          end
-        end
-        let(:line) { __LINE__ - 6 }
-      end
-    end
-
-    context "when a helper method is defined using `def foo`" do
-      include_examples "accessing an instance helper method" do
-        let(:matcher) do
-          RSpec::Matchers::DSL::Matcher.new(:sum_to) do |sum|
-            def sum_of(x, y) x + y end
-            def define_match() match {} end
-
-            if sum == :use_as_macro
-              define_match
-            else
-              match { |summands| sum_of(*summands) == sum }
-            end
-          end
-        end
-        let(:line) { __LINE__ - 6 }
-      end
+      expect(matcher.matches?(8)).to be_truthy
     end
 
     context 'when multiple instances of the same matcher are used in the same example' do
@@ -527,21 +551,19 @@ module RSpec::Matchers::DSL
 
     describe "#match_unless_raises" do
       context "with an assertion" do
-        let(:mod) do
-          Module.new do
-            def assert_equal(a,b)
-              a == b ? nil : (raise UnexpectedError.new("#{b} does not equal #{a}"))
-            end
+        mod = Module.new do
+          def assert_equal(a,b)
+            raise UnexpectedError.new("#{b} does not equal #{a}") unless a == b
           end
         end
+
         let(:matcher) do
-          m = mod
-          RSpec::Matchers::DSL::Matcher.new :equal do |expected|
-            include m
+          new_matcher(:equal, 4) do |expected|
+            include mod
             match_unless_raises UnexpectedError do
               assert_equal expected, actual
             end
-          end.for_expected(4)
+          end
         end
 
         context "with passing assertion" do
@@ -564,37 +586,78 @@ module RSpec::Matchers::DSL
 
       context "with an unexpected error" do
         let(:matcher) do
-          RSpec::Matchers::DSL::Matcher.new :foo do |expected|
+          new_matcher(:foo, :bar) do |expected|
             match_unless_raises SyntaxError do |actual|
               raise "unexpected exception"
             end
-          end.for_expected(:bar)
+          end
         end
 
         it "raises the error" do
-          expect do
+          expect {
             matcher.matches?(:bar)
-          end.to raise_error("unexpected exception")
+          }.to raise_error("unexpected exception")
+        end
+      end
+
+      context "without a specified error class" do
+        let(:matcher) do
+          new_matcher(:foo) do
+            match_unless_raises do |actual|
+              raise Exception unless actual == 5
+            end
+          end
+        end
+
+        it 'passes if no error is raised' do
+          expect(matcher.matches?(5)).to be true
+        end
+
+        it 'fails if an exception is raised' do
+          expect(matcher.matches?(4)).to be false
         end
       end
 
     end
 
     it "can define chainable methods" do
-      matcher = RSpec::Matchers::DSL::Matcher.new(:name) do
+      matcher = new_matcher(:name) do
+        chain(:expecting) do |expected_value|
+          @expected_value = expected_value
+        end
+        match { |actual| actual == @expected_value }
+      end
+
+      expect(matcher.expecting('value').matches?('value')).to be_truthy
+      expect(matcher.expecting('value').matches?('other value')).to be_falsey
+    end
+
+    it 'can use an early return from a `chain` block' do
+      matcher = new_matcher(:name) do
         chain(:expecting) do |expected_value|
           @expected_value = expected_value
+          return
         end
         match { |actual| actual == @expected_value }
-      end.for_expected
+      end
 
       expect(matcher.expecting('value').matches?('value')).to be_truthy
       expect(matcher.expecting('value').matches?('other value')).to be_falsey
     end
 
+    it 'allows chainable methods to accept blocks' do
+      matcher = new_matcher(:name) do
+        chain(:for_block) { |&b| @block = b }
+        match { |value| @block.call == value }
+      end
+
+      expect(matcher.for_block { 5 }.matches?(5)).to be true
+      expect(matcher.for_block { 3 }.matches?(4)).to be false
+    end
+
     it "prevents name collisions on chainable methods from different matchers" do
-      m1 = RSpec::Matchers::DSL::Matcher.new(:m1) { chain(:foo) { raise "foo in m1" } }.for_expected
-      m2 = RSpec::Matchers::DSL::Matcher.new(:m2) { chain(:foo) { raise "foo in m2" } }.for_expected
+      m1 = new_matcher(:m1) { chain(:foo) { raise "foo in m1" } }
+      m2 = new_matcher(:m2) { chain(:foo) { raise "foo in m2" } }
 
       expect { m1.foo }.to raise_error("foo in m1")
       expect { m2.foo }.to raise_error("foo in m2")
@@ -614,47 +677,30 @@ module RSpec::Matchers::DSL
         expect(example).to __access_running_example
       end
 
+      it 'can get a method object for methods in the running example', :if => (RUBY_VERSION.to_f > 1.8) do
+        matcher = new_matcher(:get_method_object) { }
+        method  = matcher.method(:a_method_in_the_example)
+        expect(method.call).to eq("method defined in the example")
+      end
+
+      it 'indicates that it responds to a method from the running example' do
+        matcher = new_matcher(:respond_to) { }
+        expect(matcher).to respond_to(:a_method_in_the_example)
+        expect(matcher).not_to respond_to(:a_method_not_in_the_example)
+      end
+
       it "raises NoMethodError for methods not in the running_example" do |example|
         RSpec::Matchers.define(:__raise_no_method_error) do
           match do |actual|
-            a_method_not_in_the_example == "method defined in the example"
+            self.a_method_not_in_the_example == "method defined in the example"
           end
         end
 
-        expect do
+        expect {
           expect(example).to __raise_no_method_error
-        end.to raise_error(/RSpec::Matchers::DSL::Matcher/)
+        }.to raise_error(NoMethodError, /Spec::Matchers::DSL::Matcher __raise_no_method_error/)
       end
     end
 
-    describe "#matcher_execution_context" do
-      before { allow_deprecation }
-
-      let(:matcher) do
-        RSpec::Matchers::DSL::Matcher.new :foo do |expected|
-        end.for_expected(:bar)
-      end
-
-      it 'can be set' do
-        expect {
-          matcher.matcher_execution_context = :the_context
-        }.to change(matcher, :matcher_execution_context).to(:the_context)
-      end
-
-      it 'is the target of method_missing delegation' do
-        matcher.matcher_execution_context = double(:abcd => "efg")
-        expect(matcher.abcd).to eq("efg")
-      end
-
-      specify "the writer is deprecated" do
-        expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /matcher_execution_context/)
-        matcher.matcher_execution_context = :the_context
-      end
-
-      specify "the reader is deprecated" do
-        expect_deprecation_with_call_site(__FILE__, __LINE__ + 1, /matcher_execution_context/)
-        matcher.matcher_execution_context
-      end
-    end
   end
 end