rspec-expectations 3.0.0.beta1 → 3.0.0.beta2

data/features/built_in_matchers/output.feature

@@ -0,0 +1,70 @@
+Feature: output matcher
+
+  The `output` matcher provides a way to assert that the
+  has emitted content to either `$stdout` or `$stderr`.
+
+  With no arg, passes if the block outputs `to_stdout` or `to_stderr`.
+  With a string, passes if the blocks outputs that specific string
+  `to_stdout` or `to_stderr`. With a regexp or matcher, passes if the
+  blocks outputs a string `to_stdout` or `to_stderr` that matches.
+
+  Note: This matcher works by temporarily replacing `$stdout` or `$stderr`,
+  so it's not able to intercept stream output that explicitly uses `STDOUT`/`STDERR`
+  or that uses a reference to `$stdout`/`$stderr` that was stored before the
+  matcher is used.
+
+  Scenario: output_to_stdout matcher
+    Given a file named "output_to_stdout_spec.rb" with:
+      """ruby
+      describe "output.to_stdout matcher" do
+        specify { expect { print('foo') }.to output.to_stdout }
+        specify { expect { print('foo') }.to output('foo').to_stdout }
+        specify { expect { print('foo') }.to output(/foo/).to_stdout }
+        specify { expect { }.to_not output.to_stdout }
+        specify { expect { print('foo') }.to_not output('bar').to_stdout }
+        specify { expect { print('foo') }.to_not output(/bar/).to_stdout }
+
+        # deliberate failures
+        specify { expect { }.to output.to_stdout }
+        specify { expect { }.to output('foo').to_stdout }
+        specify { expect { print('foo') }.to_not output.to_stdout }
+        specify { expect { print('foo') }.to output('bar').to_stdout }
+        specify { expect { print('foo') }.to output(/bar/).to_stdout }
+      end
+      """
+    When I run `rspec output_to_stdout_spec.rb`
+    Then the output should contain all of these:
+      | 11 examples, 5 failures                                      |
+      | expected block to output to stdout, but did not              |
+      | expected block to not output to stdout, but did              |
+      | expected block to output "bar" to stdout, but output "foo"   |
+      | expected block to output "foo" to stdout, but output nothing |
+      | expected block to output /bar/ to stdout, but output "foo"   |
+
+  Scenario: output_to_stderr matcher
+    Given a file named "output_to_stderr.rb" with:
+      """ruby
+      describe "output_to_stderr matcher" do
+        specify { expect { warn('foo') }.to output.to_stderr }
+        specify { expect { warn('foo') }.to output("foo\n").to_stderr }
+        specify { expect { warn('foo') }.to output(/foo/).to_stderr }
+        specify { expect { }.to_not output.to_stderr }
+        specify { expect { warn('foo') }.to_not output('bar').to_stderr }
+        specify { expect { warn('foo') }.to_not output(/bar/).to_stderr }
+
+        # deliberate failures
+        specify { expect { }.to output.to_stderr }
+        specify { expect { }.to output('foo').to_stderr }
+        specify { expect { warn('foo') }.to_not output.to_stderr }
+        specify { expect { warn('foo') }.to output('bar').to_stderr }
+        specify { expect { warn('foo') }.to output(/bar/).to_stderr }
+      end
+      """
+    When I run `rspec output_to_stderr.rb`
+    Then the output should contain all of these:
+      | 11 examples, 5 failures                                      |
+      | expected block to output to stderr, but did not              |
+      | expected block to not output to stderr, but did              |
+      | expected block to output "bar" to stderr, but output "foo\n" |
+      | expected block to output "foo" to stderr, but output nothing |
+      | expected block to output /bar/ to stderr, but output "foo\n" |

data/features/composing_matchers.feature

@@ -0,0 +1,250 @@
+Feature: Composing Matchers
+
+  RSpec's matchers are designed to be composable so that you can
+  combine them to express the exact details of what you expect
+  but nothing more. This can help you avoid writing over-specified
+  brittle specs, by using a matcher in place of an exact value to
+  specify only the essential aspects of what you expect.
+
+  The following matchers accept matchers as arguments:
+
+    * `change { }.by(matcher)`
+    * `change { }.from(matcher).to(matcher)`
+    * `contain_exactly(matcher, matcher, matcher)`
+    * `end_with(matcher, matcher)`
+    * `include(matcher, matcher)`
+    * `include(:key => matcher, :other => matcher)`
+    * `match(arbitrary_nested_structure_with_matchers)`
+    * `output(matcher).to_stdout`
+    * `output(matcher).to_stderr`
+    * `raise_error(ErrorClass, matcher)`
+    * `start_with(matcher, matcher)`
+    * `throw_symbol(:sym, matcher)`
+    * `yield_with_args(matcher, matcher)`
+    * `yield_successive_args(matcher, matcher)`
+
+  Note that many built-in matchers do not accept matcher arguments
+  because they have precise semantics that do not allow for a matcher
+  argument. For example, `equal(some_object)` is designed to pass only
+  if the actual and expected arguments are references to the same object.
+  It would not make sense to support a matcher argument here.
+
+  All of RSpec's built-in matchers have one or more aliases that allow
+  you to use a noun-phrase rather than verb form since they read better
+  as composed arguments. They also provide customized failure output so
+  that the failure message reads better as well.
+
+  A full list of these aliases is out of scope here, but here are some
+  of the aliases used below:
+
+    * `be < 2` => `a_value < 2`
+    * `be > 2` => `a_value > 2`
+    * `be_an_instance_of` => `an_instance_of`
+    * `be_within` => `a_value_within`
+    * `contain_exactly` => `a_collection_containing_exactly`
+    * `end_with` => `a_string_ending_with`, `ending_with`
+    * `match` => `a_string_matching`
+    * `start_with` => `a_string_starting_with`
+
+  For a full list, see the API docs for the `RSpec::Matchers` module.
+
+  Scenario: Composing matchers with `change`
+    Given a file named "change_spec.rb" with:
+      """
+      describe "Passing matchers to `change`" do
+        specify "you can pass a matcher to `by`" do
+          k = 0
+          expect { k += 1.05 }.to change { k }.
+            by( a_value_within(0.1).of(1.0) )
+        end
+
+        specify "you can pass matchers to `from` and `to" do
+          s = "food"
+          expect { s = "barn" }.to change { s }.
+            from( a_string_matching(/foo/) ).
+            to( a_string_matching(/bar/) )
+        end
+      end
+      """
+    When I run `rspec change_spec.rb`
+    Then the examples should all pass
+
+  Scenario: Composing matchers with `contain_exactly`
+    Given a file named "contain_exactly_spec.rb" with:
+      """
+      describe "Passing matchers to `contain_exactly`" do
+        specify "you can pass matchers in place of exact values" do
+          expect(["barn", 2.45]).to contain_exactly(
+            a_value_within(0.1).of(2.5),
+            a_string_starting_with("bar")
+          )
+        end
+      end
+      """
+    When I run `rspec contain_exactly_spec.rb`
+    Then the examples should all pass
+
+  Scenario: Composing matchers with `end_with`
+    Given a file named "end_with_spec.rb" with:
+      """
+      describe "Passing matchers to `end_with`" do
+        specify "you can pass matchers in place of exact values" do
+          expect(["barn", "food", 2.45]).to end_with(
+            a_string_matching("foo"),
+            a_value > 2
+          )
+        end
+      end
+      """
+    When I run `rspec end_with_spec.rb`
+    Then the examples should all pass
+
+  Scenario: Composing matchers with `include`
+    Given a file named "include_spec.rb" with:
+      """
+      describe "Passing matchers to `contain_exactly`" do
+        specify "you can use matchers in place of array values" do
+          expect(["barn", 2.45]).to include( a_string_starting_with("bar") )
+        end
+
+        specify "you can use matchers in place of hash values" do
+          expect(:a => "food", :b => "good").to include(:a => a_string_matching(/foo/))
+        end
+
+        specify "you can use matchers in place of hash keys" do
+          expect("food" => "is good").to include( a_string_matching(/foo/) )
+        end
+      end
+      """
+    When I run `rspec include_spec.rb`
+    Then the examples should all pass
+
+  Scenario: Composing matchers with `match`:
+    Given a file named "match_spec.rb" with:
+      """
+      describe "Passing matchers to `match`" do
+        specify "you can match nested data structures against matchers" do
+          hash = {
+            :a => {
+              :b => ["foo", 5],
+              :c => { :d => 2.05 }
+            }
+          }
+
+          expect(hash).to match(
+            :a => {
+              :b => a_collection_containing_exactly(
+                a_string_starting_with("f"),
+                an_instance_of(Fixnum)
+              ),
+              :c => { :d => (a_value < 3) }
+            }
+          )
+        end
+      end
+      """
+    When I run `rspec match_spec.rb`
+    Then the examples should all pass
+
+  Scenario: Composing matchers with `output`
+    Given a file named "output_spec.rb" with:
+      """
+      describe "Passing matchers to `output`" do
+        specify "you can pass a matcher in place of the output (to_stdout)" do
+          expect {
+            print 'foo'
+          }.to output(a_string_starting_with('f')).to_stdout
+        end
+        specify "you can pass a matcher in place of the output (to_stderr)" do
+          expect {
+            warn 'foo'
+          }.to output(a_string_starting_with('f')).to_stderr
+        end
+      end
+      """
+    When I run `rspec output_spec.rb`
+    Then the examples should all pass
+
+  Scenario: Composing matchers with `raise_error`
+    Given a file named "raise_error_spec.rb" with:
+      """
+      describe "Passing matchers to `raise_error`" do
+        specify "you can pass a matcher in place of the message" do
+          expect {
+            raise RuntimeError, "this goes boom"
+          }.to raise_error(RuntimeError, a_string_ending_with("boom"))
+        end
+      end
+      """
+    When I run `rspec raise_error_spec.rb`
+    Then the examples should all pass
+
+  Scenario: Composing matchers with `start_with`
+    Given a file named "start_with_spec.rb" with:
+      """
+      describe "Passing matchers to `start_with`" do
+        specify "you can pass matchers in place of exact values" do
+          expect(["barn", "food", 2.45]).to start_with(
+            a_string_matching("bar"),
+            a_string_matching("foo")
+          )
+        end
+      end
+      """
+    When I run `rspec start_with_spec.rb`
+    Then the examples should all pass
+
+  Scenario: Composing matchers with `throw_symbol`
+    Given a file named "throw_symbol_spec.rb" with:
+      """
+      describe "Passing matchers to `throw_symbol`" do
+        specify "you can pass a matcher in place of a throw arg" do
+          expect {
+            throw :pi, Math::PI
+          }.to throw_symbol(:pi, a_value_within(0.01).of(3.14))
+        end
+      end
+      """
+    When I run `rspec throw_symbol_spec.rb`
+    Then the examples should all pass
+
+  Scenario: Composing matchers with `yield_with_args`
+    Given a file named "yield_with_args_spec.rb" with:
+      """
+      describe "Passing matchers to `yield_with_args`" do
+        specify "you can pass matchers in place of the args" do
+          expect { |probe|
+            "food".tap(&probe)
+          }.to yield_with_args(a_string_matching(/foo/))
+        end
+      end
+      """
+    When I run `rspec yield_with_args_spec.rb`
+    Then the examples should all pass
+
+  Scenario: Composing matchers with `yield_successive_args`
+    Given a file named "yield_successive_args_spec.rb" with:
+      """
+      describe "Passing matchers to `yield_successive_args`" do
+        specify "you can pass matchers in place of the args" do
+          expect { |probe|
+            [1, 2, 3].each(&probe)
+          }.to yield_successive_args(a_value < 2, 2, a_value > 2)
+        end
+      end
+      """
+    When I run `rspec yield_successive_args_spec.rb`
+    Then the examples should all pass
+
+  Scenario: Composing matchers using a compound `and` expression
+    Given a file named "include_spec.rb" with:
+      """
+      describe "Passing a compound matcher expression to `include`" do
+        example do
+          expect(["food", "drink"]).to include( a_string_starting_with("f").and ending_with("d"))
+        end
+      end
+      """
+    When I run `rspec include_spec.rb`
+    Then the examples should all pass
+

data/features/compound_expectations.feature

@@ -0,0 +1,45 @@
+Feature: Compound Expectations
+
+  Matchers can be composed using `and` or `or` to make compound expectations.
+
+  Scenario: Use `and` to chain expectations
+    Given a file named "compound_and_matcher_spec.rb" with:
+      """ruby
+      describe "A compound `and` matcher" do
+        let(:string) { "foo bar bazz" }
+
+        it "passes when both are true" do
+          expect(string).to start_with("foo").and end_with("bazz")
+        end
+
+        it "fails when the first matcher fails" do
+          expect(string).to start_with("bar").and end_with("bazz")
+        end
+
+        it "fails when the second matcher fails" do
+          expect(string).to start_with("foo").and end_with("bar")
+        end
+      end
+      """
+    When I run `rspec compound_and_matcher_spec.rb`
+    Then the output should contain "3 examples, 2 failures"
+
+  Scenario: Use `or` to chain expectations
+    Given a file named "stoplight_spec.rb" with:
+      """ruby
+      class StopLight
+        def color
+          %w[ green yellow red ].shuffle.first
+        end
+      end
+
+      describe StopLight, "#color" do
+        it "is green, yellow or red" do
+          light = StopLight.new
+          expect(light.color).to eq("green").or eq("yellow").or eq("red")
+        end
+      end
+      """
+    When I run `rspec stoplight_spec.rb`
+    Then the example should pass
+

data/features/custom_matchers/access_running_example.feature

@@ -49,5 +49,5 @@ Feature: access running example
     When I run `rspec ./example_spec.rb`
     Then the output should contain "1 example, 1 failure"
     And the output should match /undefined.*method/
-    And the output should contain "RSpec::Matchers::DSL::Matcher bar"
+    And the output should contain "RSpec::Matchers::DSL::Matcher"
     And the output should not contain "ExampleGroup"

data/features/custom_matchers/define_matcher.feature

@@ -46,7 +46,7 @@ Feature: define matcher
     And the output should contain "expected 9 to be a multiple of 4"
     And the output should contain "expected 9 not to be a multiple of 3"
 
-  Scenario: overriding the failure_message_for_should
+  Scenario: overriding the failure_message
     Given a file named "matcher_with_failure_message_spec.rb" with:
       """ruby
       require 'rspec/expectations'
@@ -55,7 +55,7 @@ Feature: define matcher
         match do |actual|
           actual % expected == 0
         end
-        failure_message_for_should do |actual|
+        failure_message do |actual|
           "expected that #{actual} would be a multiple of #{expected}"
         end
       end
@@ -70,7 +70,7 @@ Feature: define matcher
     And the stdout should contain "1 example, 1 failure"
     And the stdout should contain "expected that 9 would be a multiple of 4"
 
-  Scenario: overriding the failure_message_for_should_not
+  Scenario: overriding the failure_message_when_negated
     Given a file named "matcher_with_failure_for_message_spec.rb" with:
       """ruby
       require 'rspec/expectations'
@@ -79,7 +79,7 @@ Feature: define matcher
         match do |actual|
           actual % expected == 0
         end
-        failure_message_for_should_not do |actual|
+        failure_message_when_negated do |actual|
           "expected that #{actual} would not be a multiple of #{expected}"
         end
       end
@@ -261,11 +261,11 @@ Feature: define matcher
     Given a file named "matcher_with_separate_should_not_logic_spec.rb" with:
       """ruby
       RSpec::Matchers.define :contain do |*expected|
-        match_for_should do |actual|
+        match do |actual|
           expected.all? { |e| actual.include?(e) }
         end
 
-        match_for_should_not do |actual|
+        match_when_negated do |actual|
           expected.none? { |e| actual.include?(e) }
         end
       end

data/features/custom_matchers/define_matcher_outside_rspec.feature

@@ -7,8 +7,8 @@ Feature: define matcher outside rspec
   Scenario: define a matcher with default messages
     Given a file named "test_multiples.rb" with:
       """ruby
-      require "rspec/expectations"
-      require "test/unit"
+      require "minitest/autorun"
+      require "rspec/expectations/minitest_integration"
 
       RSpec::Matchers.define :be_a_multiple_of do |expected|
         match do |actual|
@@ -16,11 +16,7 @@ Feature: define matcher outside rspec
         end
       end
 
-      class Test::Unit::TestCase
-        include RSpec::Matchers
-      end
-
-      class TestMultiples < Test::Unit::TestCase
+      class TestMultiples < Minitest::Test
 
         def test_9_should_be_a_multiple_of_3
           expect(9).to be_a_multiple_of(3)
@@ -35,4 +31,4 @@ Feature: define matcher outside rspec
     When I run `ruby test_multiples.rb`
     Then the exit status should not be 0
     And the output should contain "expected 9 to be a multiple of 4"
-    And the output should contain "2 tests, 0 assertions, 0 failures, 1 errors"
+    And the output should contain "2 runs, 2 assertions, 1 failures, 0 errors"