Selecting Which Specs to Run

When you’re running your specs, you often want to change which ones you include. In this section, we’re going to show you a few different situations where this kind of slicing and dicing comes in handy.

Filtering

Most of the time when we start RSpec, we don’t run the entire suite. We’re either running unit specs for a specific class we’re designing or we’re kicking off some integration specs to catch regressions.

We first touched on running specific examples in ​Running Just What You Need​. You saw how to select examples by pass/fail status, by our need to focus on them, and by custom tags. Let’s take a deeper dive into how to control which specs to run.

Excluding Examples

Sometimes, you want to exclude a set of examples from your RSpec run. For instance, when you’re testing a project for compatibility across Ruby interpreters, you may have a few examples that are implementation-specific. You can give these a tag such as :jruby_only, and then use your RSpec.configure block to omit those specs when you’re testing on another Ruby interpreter:

Here, the filter_run_excluding call indicates which examples we’re leaving out.

Including Examples

The flip side to that method is filter_run_including, or just filter_run for short. As you might have guessed, this method directs RSpec to run just the examples with matching metadata.

This style of filtering is pretty brute-force. If no examples match the filter, RSpec will run nothing at all.

A more generally useful approach is to use filter_run_when_matching. With this method, if nothing matches the filter, RSpec just ignores it. For example, if you haven’t marked any specs as focused (via the fdescribe/fcontext/fit methods or via the focus: true metadata), the following filter will have no effect:

In this section, we’ve used RSpec.configure to define example filters. These are permanent settings, baked into your setup code. They’ll be in effect every time you run RSpec.

Sometimes, though, you want to filter examples temporarily for just one or two RSpec runs. Editing your spec_helper.rb file every time would get old quickly. Instead, you can use RSpec’s command-line interface.

The Command Line

To run just the specs matching a particular piece of metadata, pass the --tag option to rspec. For example, you may want to run just the examples tagged with :fast:

If you prefix the tag name with a tilde (~), RSpec treats the name as an exclusion filter. For example, to run all examples that lack the :fast tag, you could use the following command:

Note that some shells treat ~ as a special character, and try to expand it to a directory name. You can avoid this issue by quoting the tag name:

The previous examples look for the tag’s truthiness; any value besides nil or false will match. Sometimes, you care about the specific tag value. For example, you may have several specs tagged with a bug ID from your bug tracking system. If you run RSpec like so:

…you can filter the examples to just the ones related to the ticket you’re working on.