RSpec - Matchers

If you recall our original Hello World example, it contained a line that looked like this −

expect(message).to eq "Hello World!"

The keyword eql is an RSpec “matcher”. Here, we will introduce the other types of matchers in RSpec.

Equality/Identity Matchers

Matchers to test for object or value equality.

Matcher Description Example
eq Passes when actual == expected expect(actual).to eq expected
eql Passes when actual.eql?(expected) expect(actual).to eql expected
be Passes when actual.equal?(expected) expect(actual).to be expected
equal Also passes when actual.equal?(expected) expect(actual).to equal expected

Example

describe "An example of the equality Matchers" do 

   it "should show how the equality Matchers work" do 
      a = "test string" 
      b = a 
      
      # The following Expectations will all pass 
      expect(a).to eq "test string" 
      expect(a).to eql "test string" 
      expect(a).to be b 
      expect(a).to equal b 
   end
   
end

When the above code is executed, it will produce the following output. The number of seconds may be slightly different on your computer −

.
Finished in 0.036 seconds (files took 0.11901 seconds to load)
1 example, 0 failures

Comparison Matchers

Matchers for comparing to values.

Matcher Description Example
> Passes when actual > expected expect(actual).to be > expected
>= Passes when actual >= expected expect(actual).to be >= expected
< Passes when actual < expected expect(actual).to be < expected
<= Passes when actual <= expected expect(actual).to be <= expected
be_between inclusive Passes when actual is <= min and >= max expect(actual).to be_between(min, max).inclusive
be_between exclusive Passes when actual is < min and > max expect(actual).to be_between(min, max).exclusive
match Passes when actual matches a regular expression expect(actual).to match(/regex/)

Example

describe "An example of the comparison Matchers" do

   it "should show how the comparison Matchers work" do
      a = 1
      b = 2
      c = 3		
      d = 'test string'
      
      # The following Expectations will all pass
      expect(b).to be > a
      expect(a).to be >= a 
      expect(a).to be < b 
      expect(b).to be <= b 
      expect(c).to be_between(1,3).inclusive 
      expect(b).to be_between(1,3).exclusive 
      expect(d).to match /TEST/i 
   end
   
end

When the above code is executed, it will produce the following output. The number of seconds may be slightly different on your computer −

. 
Finished in 0.013 seconds (files took 0.11801 seconds to load) 
1 example, 0 failures

Class/Type Matchers

Matchers for testing the type or class of objects.

Matcher Description Example
be_instance_of Passes when actual is an instance of the expected class. expect(actual).to be_instance_of(Expected)
be_kind_of Passes when actual is an instance of the expected class or any of its parent classes. expect(actual).to be_kind_of(Expected)
respond_to Passes when actual responds to the specified method. expect(actual).to respond_to(expected)

Example

describe "An example of the type/class Matchers" do
 
   it "should show how the type/class Matchers work" do
      x = 1 
      y = 3.14 
      z = 'test string' 
      
      # The following Expectations will all pass
      expect(x).to be_instance_of Fixnum 
      expect(y).to be_kind_of Numeric 
      expect(z).to respond_to(:length) 
   end
   
end

When the above code is executed, it will produce the following output. The number of seconds may be slightly different on your computer −

. 
Finished in 0.002 seconds (files took 0.12201 seconds to load) 
1 example, 0 failures

True/False/Nil Matchers

Matchers for testing whether a value is true, false or nil.

Matcher Description Example
be true Passes when actual == true expect(actual).to be true
be false Passes when actual == false expect(actual).to be false
be_truthy Passes when actual is not false or nil expect(actual).to be_truthy
be_falsey Passes when actual is false or nil expect(actual).to be_falsey
be_nil Passes when actual is nil expect(actual).to be_nil

Example

describe "An example of the true/false/nil Matchers" do
   it "should show how the true/false/nil Matchers work" do
      x = true 
      y = false 
      z = nil 
      a = "test string" 
      
      # The following Expectations will all pass
      expect(x).to be true 
      expect(y).to be false 
      expect(a).to be_truthy 
      expect(z).to be_falsey 
      expect(z).to be_nil 
   end 
end

When the above code is executed, it will produce the following output. The number of seconds may be slightly different on your computer −

. 
Finished in 0.003 seconds (files took 0.12301 seconds to load) 
1 example, 0 failures

Error Matchers

Matchers for testing, when a block of code raises an error.

Matcher Description Example
raise_error(ErrorClass) Passes when the block raises an error of type ErrorClass. expect {block}.to raise_error(ErrorClass)
raise_error("error message") Passes when the block raise an error with the message “error message”. expect {block}.to raise_error(“error message”)
raise_error(ErrorClass, "error message") Passes when the block raises an error of type ErrorClass with the message “error message” expect {block}.to raise_error(ErrorClass,“error message”)

Example

Save the following code to a file with the name error_matcher_spec.rb and run it with this command − rspec error_matcher_spec.rb.

describe "An example of the error Matchers" do 
   it "should show how the error Matchers work" do 
      
      # The following Expectations will all pass 
      expect { 1/0 }.to raise_error(ZeroDivisionError)
      expect { 1/0 }.to raise_error("divided by 0") 
      expect { 1/0 }.to raise_error("divided by 0", ZeroDivisionError) 
   end 
end

When the above code is executed, it will produce the following output. The number of seconds may be slightly different on your computer −

. 
Finished in 0.002 seconds (files took 0.12101 seconds to load) 
1 example, 0 failures
Advertisements