Permalink
Browse files

Additional improvements to raise_error matcher docs.

  • Loading branch information...
1 parent 1a60dff commit f5ddd17e9d285a45052b1be1f491c95dad05db5b @dchelimsky dchelimsky committed Feb 2, 2011
View
@@ -1,4 +1,4 @@
-## rspec-expectations release history (incomplete)
+## rspec-expectations release history
### dev
@@ -7,6 +7,9 @@
* Enhancements
* `should exist` works with `exist?` or `exists?` (Myron Marston)
+* Documentation
+ * improved docs for raise_error matcher (James Almond)
+
### 2.4.0 / 2011-01-02
[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.3.0...v2.4.0)
@@ -1,151 +1,105 @@
Feature: raise_error matcher
- The raise_error matcher is used to specify that a block of code
- raises an error. The most basic form passes if any error is thrown:
+ Use the `raise_error` matcher to specify that a block of code raises an
+ error. The most basic form passes if any error is thrown:
- expect { raise StandardError }.to raise_error
+ expect { raise StandardError }.to raise_error
- You'll often want to specify that a particular error is thrown:
+ You can use `raise_exception` instead if you prefer that wording:
- expect { raise ArgumentError }.to raise_error(ArgumentError)
+ expect { 3 / 0 }.to raise_exception
- If you care about the message given to the error, you can specify
- that using both strings and regular expressions:
+ `raise_error` and `raise_exception` are functionally interchangeable, so use
+ the one that makes the most sense to you in any given context.
- expect { raise StandardError, "my message" }.to raise_error(StandardError, "my message")
- expect { raise StandardError, "my message" }.to raise_error(StandardError, /mess/)
+ In addition to the basic form, above, there are a number of ways to specify
+ details of an error/exception:
- If you want to assert on the error itself you can pass a block to the matcher:
-
- expect { raise StandardError }.to raise_error{|error| error.should be_a_kind_of(StandardError)}
-
- You can also assert that the block of code does not raise an error:
-
- expect { 1 + 1 }.to_not raise_error # fails if any error is raised
- expect { 1 + 1 }.to_not raise_error(ArgumentError) # passes if anything other than an ArgumentError is raised
- expect { 1 + 1 }.to_not raise_error(ArgumentError, "my message") # passes if an ArgumentError is raise with a different message
- expect { 1 + 1 }.to_not raise_error(ArgumentError, /mess/) # passes if an ArgumentError is raised that doesn't match the regexp
-
-
- Scenario: expect error
+ Scenario: expect any error
Given a file named "expect_error_spec.rb" with:
"""
- describe Object, "#non_existent_message" do
- it "should raise" do
- expect{Object.non_existent_message}.to raise_error(NameError)
- end
- end
-
- #deliberate failure
- describe Object, "#public_instance_methods" do
- it "should raise" do
- expect{Object.public_instance_methods}.to raise_error(NameError)
+ describe "calling a method that does not exist" do
+ it "raises" do
+ expect { Object.new.foo }.to raise_error
end
end
"""
- When I run "rspec ./expect_error_spec.rb"
- Then the output should contain "2 examples, 1 failure"
- Then the output should contain "expected NameError but nothing was raised"
+ When I run "rspec expect_error_spec.rb"
+ Then the example should pass
- Scenario: expect no error
- Given a file named "expect_no_error_spec.rb" with:
+ Scenario: expect specific error
+ Given a file named "expect_error_spec.rb" with:
"""
- describe Object, "#public_instance_methods" do
- it "should not raise" do
- expect{Object.public_instance_methods}.to_not raise_error(NameError)
- end
- end
-
- #deliberate failure
- describe Object, "#non_existent_message" do
- it "should not raise" do
- expect{Object.non_existent_message}.to_not raise_error(NameError)
+ describe "calling a method that does not exist" do
+ it "raises" do
+ expect { Object.new.foo }.to raise_error(NameError)
end
end
"""
- When I run "rspec ./expect_no_error_spec.rb"
- Then the output should contain "2 examples, 1 failure"
- Then the output should contain "undefined method `non_existent_message'"
+ When I run "rspec expect_error_spec.rb"
+ Then the example should pass
- Scenario: expect error with a message
+ Scenario: expect specific error message using a string
Given a file named "expect_error_with_message.rb" with:
"""
- describe "matching error message with string" do
- it "should match the error message" do
- expect{ raise StandardError, 'my message'}.to raise_error(StandardError, 'my message')
- end
- #deliberate failure
- it "should match the error message" do
- expect{ raise StandardError, 'another message'}.to raise_error(StandardError, 'my message')
- end
+ describe "matching error message with string" do
+ it "matches the error message" do
+ expect { raise StandardError, 'this message exactly'}
+ .to raise_error(StandardError, 'this message exactly')
end
+ end
"""
- When I run "rspec ./expect_error_with_message.rb"
- Then the output should contain all of these:
- | 2 examples, 1 failure |
- | expected StandardError with "my message" |
+ When I run "rspec expect_error_with_message.rb"
+ Then the example should pass
- Scenario: expect error with regular expression
+ Scenario: expect specific error message using a regular expression
Given a file named "expect_error_with_regex.rb" with:
"""
describe "matching error message with regex" do
- it "should match the error message" do
- expect{raise StandardError, "my message"}.to raise_error(StandardError, /mess/)
- end
-
- # deliberate failure
- it "should match the error message" do
- expect{raise StandardError, "my message"}.to raise_error(StandardError, /pass/)
+ it "matches the error message" do
+ expect { raise StandardError, "my message" }
+ .to raise_error(StandardError, /my mess/)
end
end
"""
- When I run "rspec ./expect_error_with_regex.rb"
- Then the output should contain all of these:
- | 2 examples, 1 failure |
- | expected StandardError with message matching /pass/ |
+ When I run "rspec expect_error_with_regex.rb"
+ Then the example should pass
- Scenario: expect no error with message
- Given a file named "expect_no_error_with_message.rb" with:
+ Scenario: set expectations on error object passed to block
+ Given a file named "expect_error_with_block_spec.rb" with:
"""
- describe "matching no error with message" do
- it "should not match errors with a different message" do
- expect{raise StandardError, 'my message'}.to_not raise_error(StandardError, "another message")
- end
-
- #deliberate failure
- it "should not match errors with a different message" do
- expect{raise StandardError, "my message"}.to_not raise_error(StandardError, 'my message')
- end
+ describe "#foo" do
+ it "raises NameError" do
+ expect { Object.new.foo }.to raise_error { |error|
+ error.should be_a(NameError)
+ }
end
+ end
"""
- When I run "rspec ./expect_no_error_with_message.rb"
- Then the output should contain all of these:
- | 2 examples, 1 failure |
- | expected no StandardError with "my message" |
+ When I run "rspec expect_error_with_block_spec.rb"
+ Then the example should pass
- Scenario: expect error with block
- Given a file named "expect_error_with_block_spec.rb" with:
+ Scenario: expect no error at all
+ Given a file named "expect_no_error_spec.rb" with:
"""
- describe "accessing expected error" do
- let(:expected_error){ StandardError.new}
-
- it "should pass the error to the block" do
- expect{raise expected_error}.to raise_error{|block_error|
- block_error.should eq(expected_error)
- }
+ describe "#to_s" do
+ it "does not raise" do
+ expect { Object.new.to_s }.to_not raise_error
end
-
- # deliberate failure to assert block called
- it "should pass the error to the block" do
- expect{raise expected_error}.to raise_error{|block_error|
- block_error.should_not eq(expected_error)
- }
+ end
+ """
+ When I run "rspec expect_no_error_spec.rb"
+ Then the example should pass
+
+ Scenario: expect no occurence of a specific error
+ Given a file named "expect_no_error_spec.rb" with:
+ """
+ describe Object, "#public_instance_methods" do
+ it "does not raise" do
+ expect { Object.public_instance_methods }
+ .to_not raise_error(NameError)
end
-
end
"""
- When I run "rspec ./expect_error_with_block_spec.rb"
- Then the output should contain all of these:
- | 2 examples, 1 failure |
- | expected #<StandardError: StandardError> not to equal #<StandardError: StandardError> |
-
+ When I run "rspec expect_no_error_spec.rb"
+ Then the example should pass
@@ -11,3 +11,12 @@
end
end
+Then /^the example(?:s)? should(?: all)? pass$/ do
+ Then %q{the output should contain "0 failures"}
+ Then %q{the exit status should be 0}
+end
+
+Then /^the example should fail$/ do
+ Then %q{the output should contain "1 failure"}
+ Then %q{the exit status should not be 0}
+end

0 comments on commit f5ddd17

Please sign in to comment.