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 like this −

RSpec.describe "An Example Group with positive and negative Examples" do 
   context ''when testing Ruby''s build-in math library'' 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 like 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 library'' 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 slightly different command −

rspec --tag positive filter_spec.rb

Now, you will see output that looks like 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 telling RSpec to only run Examples with the: positive metadata variable defined. We could do the same thing with negative tests by running the command like 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 like 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, like 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-like style. You might be wondering what these options look like when you have a failure in a test (Example). Let’s change the code in formatter_spec.rb to look like 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 ability to change the way test results display, it is even possible to create your own custom Formatter, but that is a more advanced topic.