Command line

The rspec command comes with several options you can use to customize RSpec’s
behavior, including output formats, filtering examples, etc.

For a full list of options, run the rspec command with the --help flag:

$ rspec --help

Run with ruby

Generally, life is simpler if you just use the rspec command. If you must use the ruby command, however, you’ll need to require rspec/autorun. You can either pass a -rrspec/autorun CLI option when invoking ruby, or add a require 'rspec/autorun' to one or more of your spec files.

It is conventional to put the configuration and require assorted support files from spec/spec_helper.rb. It is also conventional to require that file from the spec files using require 'spec_helper'. This works because RSpec implicitly adds the spec directory to the LOAD_PATH. It also adds lib, so your implementation files will be on the LOAD_PATH as well.

If you’re using the ruby command, you’ll need to do this yourself (with the -I option). Putting these together, your command might be something like this:

$ ruby -Ilib -Ispec -rrspec/autorun path/to/spec.rb

Rspec command line options

--example option	Use the --example (or -e) option to filter examples by name. The argument is matched against the full description of the example, which is the concatenation of descriptions of the group (including any nested groups) and the example. This allows you to run a single uniquely named example, all examples with similar names, all the examples in a uniquely named group, etc, etc.	rspec . --example example
--format option	Formats the progress bar as dots or full spec-by-spec output (documentation)	rspec spec --format documentation --out rspec.txt
--tag option	Use the --tag (or -t) option to run examples that match a specified tag. The tag can be a simple name or a name:value pair.
–failure-exit-code	When rspec exits with a failure (non-success), it normally exits back to the OS with an exit code of 1	rspec spec –failure-exit-code 5
–order	Tells Rspec in which order to run the specs: defined, rand, or rand:123 where 123 is the seed for the randomness.	rspec spec –order defined
–dry-run	print your suite’s formatter output without running any examples or hooks
–example-matches

--example option

Use the --example (or -e) option to filter examples by name.

The argument is matched against the full description of the example, which is the concatenation of descriptions of the group (including any nested groups) and the example.

This allows you to run a single uniquely named example, all examples with similar names, all the examples in a uniquely named group. You can also use the option more than once to specify multiple example matches.

Note: 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 pass part of a group’s description to select all examples defined in the group (including those without description).

first_spec.rb

RSpec.describe "first group" do
  it "first example in first group" do; end
  it "second example in first group" do; end
end

second_spec.rb

RSpec.describe "second group" do
  it "first example in second group" do; end
  it "second example in second group" do; end
end

third_spec.rb

RSpec.describe "third group" do
  it "first example in third group" do; end
  context "nested group" do
    it "first example in nested group" do; end
    it "second example in nested group" do; end
  end
end

fourth_spec.rb

RSpec.describe Array do
  describe "#length" do
    it "is the number of items" do
      expect(Array.new([1,2,3]).length).to eq 3
    end
  end
end

No matches

rspec . --example nothing_like_this

the process succeeds even though no examples were run

Match on one word

rspec . --example example

One match in each context

rspec . --example 'first example'

One match in one file using just the example name

rspec . --example 'first example in first group'

One match in one file using the example name and the group name

rspec . --example 'first group first example in first group'

All examples in one group

rspec . --example 'first group'

One match in one file with group name

rspec . --example 'second group first example'

All examples in one group, including examples in nested groups

rspec . --example 'third group'

Match using `ClassName#method_name` form

rspec . --example 'Array#length'

Using –example flag multiple times

rspec . --example 'first group' --example 'second group' --format d

--format option

Use the --format option to tell RSpec how to format the output.

RSpec ships with several formatters built in (the formatted determines how the output looks when you run it). By default, it uses the progress formatter, which generates output like this:

....F.....*.....

A . represents a passing example, F is failing, and * is pending.

.	Passing spec
F	Failing spec
*	Pending spec

Use the documentation formatter to see the documentation strings passed to
describe, it, and their aliases:

$ rspec spec --format documentation

You can also specify an output target ($stdout by default) with an --out
option immediately following the --format option:

$ rspec spec --format documentation --out rspec.txt

Run rspec --help to see a listing of available formatters.

Progress bar format (default)

rspec --format progress example_spec.rb

Rspec will format the progress bar like so:

.F**

Documentation format

rspec example_spec.rb --format documentation

Example output

something
  does something that passes
  does something that fails (FAILED - 1)
  does something that is pending (PENDING: No reason given)
  does something that is skipped (PENDING: No reason given)

Documentation format saved to a file

rspec example_spec.rb --format documentation --out rspec.txt

A file named rspec.txt will get written your current directory with the spec-by-spec documentation above.

--tag option

Use the --tag (or -t) option to run examples that match a specified tag.

The tag can be a simple name or a name:value pair If a simple name is supplied, only examples with :name => true will run. If a name:value pair is given, examples with name => value will run, where value is always a string. In both cases, name is converted to a symbol. Tags can also be used to exclude examples by adding a ~ before the tag. For example, ~tag will exclude all examples marked with :tag => true and ~tag:value will exclude all examples marked with :tag => value. Filtering by tag uses a hash internally, which means that you can’t specify multiple filters for the same key. For instance, if you try to exclude :name => 'foo' and :name => 'bar', you will only end up excluding :name => 'bar'.

To be compatible with the Cucumber syntax, tags can optionally start with an @ symbol, which will be ignored as part of the tag, e.g. --tag @focus is treated the same as --tag focus and is expanded to :focus => true.

Filter examples with non-existent tag

 rspec . --tag nonexistanttag

You will get success even though no examples were run

Filter examples with a simple tag

WhenI run rspec . --tag focus

Filter examples with a simple tag and @

WhenI run rspec . --tag @focus

Filter examples with a `name:value` tag

rspec . --tag type:special

Filter examples with a `name:value` tag and

rspec . --tag @type:special

Thenthe output should contain:

include {:type=>"special"}

Exclude examples with a simple tag

rspec . --tag ~skip

Exclude examples with a simple tag and @

rspec . --tag ~@skip

Exclude examples with a `name:value` tag

rspec . --tag ~speed:slow

Exclude examples with a `name:value` tag and @

rspec . --tag ~@speed:slow

Filter examples with a simple tag, exclude examples with another tag

rspec . --tag focus --tag ~skip

Exclude examples with multiple tags

rspec . --tag ~skip --tag ~speed:slow

Line number appended to file path

To run one or more examples or groups, you can append the line number to the
path, e.g.

$ rspec path/to/example_spec.rb:37

Examples of how to nest one describe inside another.

RSpec.describe "outer group" do
  it "first example in outer group" do

  end
  it "second example in outer group" do

  end
  
  describe "nested group" do
    it "example in nested group" do

    end
  end
end

One-liners

RSpec.describe 9 do
 it { is_expected.to be > 8 }
 it { is_expected.to be < 10 }
end

You can specify to run rspec on the command line by listing the file paths or patterns.

If you use spaces, each space will be interpreted as either a new filepath or pattern.

When you run rspec at a specific line number you will use a colon:

rspec example_spec.rb:2

Rspec will either run one or a group of specs. What determines if it runs one or a group of specs is where the line number is: IF the line number is within the scope of a single spec, that single spec will be run. If the line number is in the scope of a describe block, then all of the its in that describe will get run.

rspec example_spec.rb:2

Here, Rspec will run only the spec that begins on line number 2.

If you use more than one colon, Rspec will treat each

rspec example_spec.rb:2:10

Here, Rspec will run both the spec that begins on line number 2 and line number 10.

rspec example_spec.rb:2:10

--failure-exit-code option (exit status)

The rspec command exits with an exit status of 0 if all examples pass, and 1
if any examples fail, which is the default behavior for most Unix commands.

If no specs are present in the file that you specify, Rspec will not fail and will exit with status 0 (passing) and a message:
0 examples, 0 failures

The failure exit code can be overridden using the --failure-exit-code option.

--order option

Use the --order option to tell RSpec how to order the files, groups, and examples. The available ordering schemes are defined and rand. defined is the default. It executes groups and examples in the order they are defined as the spec files are loaded, with the caveat that each group runs its examples before running its nested example groups, even if the nested groups are defined before the examples.

Use rand to randomize the order of groups and examples within the groups. Nested groups are always run from top-level to bottom-level in order to avoid executing  before(:context)  and  after(:context)  hooks more than once, but the order of groups at each level is randomized.

With rand you can also specify a seed. Use recently-modified to run the most recently modified files first. You can combine it with --only-failures to find the most recent failing specs. Note
that recently-modified and rand are mutually exclusive.

Example usage

The defined option is only necessary when you have --order rand stored in a
config file (e.g. .rspec) and you want to override it from the command line.

--order defined
--order rand
--order rand:123
--seed 123 # same as --order rand:123
--order recently-modified

--dry-run option

Use the --dry-run option to have RSpec print your suite’s formatter output without running any examples or hooks.

--example-matches option

Use the --example-matches (or -E) option to filter examples by name using REGEX.

The argument is matched against the full description of the example, which is the concatenation of descriptions of the group (including any nested groups) and the example. This allows you to run a single uniquely named example, all examples with similar names, all the examples in a uniquely named group, etc, etc. You can also use the option more than once to specify multiple example matches. Note: 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).

first_spec.rb

RSpec.describe "first group" do
  it "first" do; end
  it "first example in first group" do; end
  it "second example in first group" do; end
end

second_spec.rb

RSpec.describe "second group" do
  it "first example in second group" do; end
  it "second example in second group" do; end
end

third_spec.rb

RSpec.describe "third group" do
  it "first example in third group" do; end
  context "group of nest" do
    it "first example in nested group" do; end
    it "second example in nested group" do; end
    it "third example in nested_group with underscore" do; end
  end
end

fourth_spec.rb

RSpec.describe Array do
  describe "#length" do
    it "is the number of items" do
      expect(Array.new([1,2,3]).length).to eq 3
    end
  end
end

Match using `ClassName#method_name` form

rspec . --example-matches 'Array#length'Thenthe examples should all pass

Match only matching regex

WhenI run rspec . --example-matches "first$" --format dThenthe examples should all passAndthe output should contain all of these:

Match only matching regex with word boundaries

rspec . --example-matches "nested[^_]" --format d

Rake task

RSpec ships with a rake task with a number of useful options. We recommend you wrap this in a rescue clause so that you can use your Rakefile in an environment where RSpec is unavailable
(for example on a production server). e.g:

begin
  require 'rspec/core/rake_task'

  RSpec::Core::RakeTask.new(:spec)

  task :default => :spec
rescue LoadError
  # no rspec available
end

You can alternatively pass the block-style syntax to set the command line options:

begin
  require 'rspec/core/rake_task'

  RSpec::Core::RakeTask.new(:spec) do |t|
    t.fail_on_error = false
  end

  task :default => :spec
rescue LoadError
  # no rspec available
end

Passing arguments to the `rspec` command using `rspec_opts`

begin
  require 'rspec/core/rake_task'

  RSpec::Core::RakeTask.new(:spec) do |t|
    t.rspec_opts = "--tag fast"
  end
rescue LoadError
  # no rspec available
end

Passing rake task arguments to the `rspec` command via `rspec_opts`

begin
  require 'rspec/core/rake_task'

  RSpec::Core::RakeTask.new(:spec, :tag) do |t, task_args|
    t.rspec_opts = "--tag #{task_args[:tag]}"
  end
rescue LoadError
  # no rspec available
end