RSpec - Filtering

You may want to read the section on RSpec Metadata before reading this section because, as it turns out, RSpec filtering is based on RSpec Metadata.

Imagine that you have a spec file and it contains two types of tests (Examples): positive functional tests and negative (error) tests. Let’s define them pke this −

RSpec.describe "An Example Group with positive and negative Examples" do 
   context  when testing Ruby s build-in math pbrary  do
      
      it  can do normal numeric operations  do 
         expect(1 + 1).to eq(2) 
      end 
      
      it  generates an error when expected  do
         expect{1/0}.to raise_error(ZeroDivisionError) 
      end
      
   end 
end

Now, save the above text as a file called ‘filter_spec.rb’ and then run it with this command −

rspec filter_spec.rb

You will see output that looks something pke this −

.. 
Finished in 0.003 seconds (files took 0.11201 seconds to load) 
2 examples, 0 failures

Now what if, we wanted to re-run only the positive tests in this file? Or only the negative tests? We can easily do that with RSpec Filters. Change the above code to this −

RSpec.describe "An Example Group with positive and negative Examples" do 
   context  when testing Ruby s build-in math pbrary  do
      
      it  can do normal numeric operations , positive: true do 
         expect(1 + 1).to eq(2) 
      end 
      
      it  generates an error when expected , negative: true do 
         expect{1/0}.to raise_error(ZeroDivisionError) 
      end
      
   end 
end

Save your changes to filter_spec.rb and run this spghtly different command −

rspec --tag positive filter_spec.rb

Now, you will see output that looks pke this −

Run options: include {:positive=>true} 
. 
Finished in 0.001 seconds (files took 0.11401 seconds to load) 
1 example, 0 failures

By specifying --tag positive, we’re telpng RSpec to only run Examples with the: positive metadata variable defined. We could do the same thing with negative tests by running the command pke this −

rspec --tag negative filter_spec.rb

Keep in mind that these are just examples, you can specify a filter with any name that you want.

RSpec Formatters

Formatters allow RSpec to display the output from tests in different ways. Let’s create a new RSpec file containing this code −

RSpec.describe "A spec file to demonstrate how RSpec Formatters work" do 
   context  when running some tests  do 
      
      it  the test usually calls the expect() method at least once  do 
         expect(1 + 1).to eq(2) 
      end
      
   end 
end

Now, save this to a file called formatter_spec.rb and run this RSpec command −

rspec formatter_spec.rb

You should see output that looks pke this −

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

Now run the same command but this time specify a formatter, pke this −

rspec --format progress formatter_spec.rb

You should see the same output this time −

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

The reason is that the “progress” formatter is the default formatter. Let’s try a different formatter next, try running this command −

rspec --format doc formatter_spec.rb

Now you should see this output −

A spec file to demonstrate how RSpec Formatters work 
   when running some tests 
      the test usually calls the expect() method at least once
Finished in 0.002 seconds (files took 0.11401 seconds to load) 
1 example, 0 failures

As you can see, the output is quite different with the “doc” formatter. This formatter presents the output in a documentation-pke style. You might be wondering what these options look pke when you have a failure in a test (Example). Let’s change the code in formatter_spec.rb to look pke this −

RSpec.describe "A spec file to demonstrate how RSpec Formatters work" do 
   context  when running some tests  do 
      
      it  the test usually calls the expect() method at least once  do 
         expect(1 + 1).to eq(1) 
      end
      
   end 
end

The expectation expect(1 + 1).to eq(1) should fail. Save your changes and re-run the above commands −

rspec --format progress formatter_spec.rb and remember, since the “progress” formatter is the default, you could just run: rspec formatter_spec.rb. You should see this output −

F 
Failures:
1) A spec file to demonstrate how RSpec Formatters work when running some tests 
the test usually calls the expect() method at least once
   Failure/Error: expect(1 + 1).to eq(1)
	
      expected: 1
         got: 2
			  
      (compared using ==)			  
   # ./formatter_spec.rb:4:in `block (3 levels) in <top (required)> 

Finished in 0.016 seconds (files took 0.11201 seconds to load)
1 example, 1 failure
Failed examples:

rspec ./formatter_spec.rb:3 # A spec file to demonstrate how RSpec 
   Formatters work when running some tests the test usually calls 
   the expect() method at least once

Now, let’s try the doc formatter, run this command −

rspec --format doc formatter_spec.rb

Now, with the failed test, you should see this output −

A spec file to demonstrate how RSpec Formatters work
   when running some tests
      the test usually calls the expect() method at least once (FAILED - 1)
		
Failures:

1) A spec file to demonstrate how RSpec Formatters work when running some
   tests the test usually calls the expect() method at least once
   Failure/Error: expect(1 + 1).to eq(1)
	
   expected: 1
        got: 2
		  
   (compared using ==)
   # ./formatter_spec.rb:4:in `block (3 levels) in <top (required)> 
	
Finished in 0.015 seconds (files took 0.11401 seconds to load) 
1 example, 1 failure

Failed Examples

rspec ./formatter_spec.rb:3 # A spec file to demonstrate how RSpec Formatters work when running some tests the test usually calls the expect() method at least once.

RSpec Formatters offer the abipty to change the way test results display, it is even possible to create your own custom Formatter, but that is a more advanced topic.