Filtering
RSpec supports filtering examples and example groups in multiple ways, allowing you to run a targeted subset of your suite that you are currently interested in.
Filtering by Tag
Examples and groups can be filtered by matching tags declared on
the command line or options files, or filters declared via
RSpec.configure
, with hash key/values submitted within example group
and/or example declarations. For example, given this declaration:
RSpec.describe Thing, :awesome => true do
it "does something" do
# ...
end
end
That group (or any other with :awesome => true
) would be filtered in
with any of the following commands:
rspec --tag awesome:true
rspec --tag awesome
rspec -t awesome:true
rspec -t awesome
Prefixing the tag names with ~
negates the tags, thus excluding this
group with any of:
rspec --tag ~awesome:true
rspec --tag ~awesome
rspec -t ~awesome:true
rspec -t ~awesome
Filtering by Example description
RSpec provides the --example
(short form: -e
) option to allow you to
select examples or groups by their description. All loaded examples
whose full description (computed based on the description of the example
plus that of all ancestor groups) contains the provided argument will be
executed.
rspec --example "Homepage when logged in"
rspec -e "Homepage when logged in"
You can specify this option multiple times to select multiple sets of examples:
rspec -e "Homepage when logged in" -e "User"
Note that RSpec will load all spec files in these situations, which can incur considerable start-up costs (particularly for Rails apps). If you know that the examples you are targeting are in particular files, you can also pass the file or directory name so that RSpec loads only those spec files, speeding things up:
rspec spec/homepage_spec.rb -e "Homepage when logged in"
rspec -e "Homepage when logged in" spec/homepage_spec.rb
Note also that description-less examples that have generated descriptions (typical when using the one-liner syntax) cannot be directly filtered with this option, because it is necessary to execute the example to generate the description, so RSpec is unable to use the not-yet-generated description to decide whether or not to execute an example. You can, of course, pass part of a group's description to select all examples defined in the group (including those that have no description).
Filtering by Example Location
Examples and groups can be selected from the command line by passing the file and line number where they are defined, separated by a colon:
rspec spec/homepage_spec.rb:14 spec/widgets_spec.rb:40 spec/users_spec.rb
This command would run the example or group defined on line 14 of
spec/homepage_spec.rb
, the example or group defined on line 40 of
spec/widgets_spec.rb
, and all examples and groups defined in
spec/users_spec.rb
.
If there is no example or group defined at the specified line, RSpec will run the last example or group defined before the line.
Focusing
RSpec supports configuration options that make it easy to select
examples by temporarily tweaking them. In your spec_helper.rb
(or
a similar file), put this configuration:
RSpec.configure do |config|
config.filter_run_when_matching :focus
end
This configuration is generated for you by rspec --init
in the
commented-out section of recommendations. With that in place, you
can tag any example group or example with :focus
metadata to
select it:
it "does something" do
# becomes...
it "does something", :focus do
RSpec also ships with aliases of the common example group definition
methods (describe
, context
) and example methods (it
, specify
,
example
) with an f
prefix that automatically includes :focus =>
true
metadata, allowing you to easily change it
to fit
(think
"focused it"), describe
to fdescribe
, etc in order to temporarily
focus them.
Options files and command line overrides
Command line option declarations can be stored in .rspec
, ~/.rspec
,
$XDG_CONFIG_HOME/rspec/options
or a custom options file. This is useful for
storing defaults. For example, let's say you've got some slow specs that you
want to suppress most of the time. You can tag them like this:
RSpec.describe Something, :slow => true do
And then store this in .rspec
:
--tag ~slow:true
Now when you run rspec
, that group will be excluded.
Overriding
Of course, you probably want to run them sometimes, so you can override this tag on the command line like this:
rspec --tag slow:true
Precedence
Location and description filters have priority over tag filters since
they express a desire by the user to run specific examples. Thus, you
could specify a location or description at the command line to run an
example or example group that would normally be excluded due to a
:slow
tag if you were using the above configuration.
RSpec.configure
You can also store default tags with RSpec.configure
. We use tag
on
the command line (and in options files like .rspec
), but for historical
reasons we use the term filter
in RSpec.configure
:
RSpec.configure do |c|
c.filter_run_including :foo => :bar
c.filter_run_excluding :foo => :bar
end
These declarations can also be overridden from the command line.
Silencing filter announcements
By default, RSpec will print a message before your specs run indicating what filters are configured, for instance, it might print "Run options: include :focus=>true" if you set config.filter_run_including :focus => true
.
If you wish to prevent those messages from appearing in your spec output, you can set the silence_filter_announcements
config setting to true
like this:
RSpec.configure do |c|
c.filter_run_including :foo => :bar
c.silence_filter_announcements = true
end