Command-Line Configuration
To see all the available command-line options, run rspec --help. You’ll get a pretty big list of settings, some of which you’ve already used in this book. We’re not going to go over them all here, but there are a few we’d like to highlight.
Environment Options
Sometimes, you need to control how RSpec loads your Ruby code. For instance, you may be experimenting with a locally modified version of a library—in that case, you’d want RSpec to load your custom version of that library instead of the default one.
The first two options listed in the --help output are for these kinds of environment customizations:
| | -I PATH Specify PATH to add to $LOAD_PATH (may ↩ |
| | be used more than once). |
| | -r, --require PATH Require a file. |
If you’ve ever passed the -I or -r options to the ruby executable, these RSpec switches may look familiar—they were designed to match the ones for Ruby.
The second option, -r or --require, makes it easy to use supporting libraries while you’re testing. For example, you may want to use the byebug debugger to troubleshoot a failing spec.[60] You can easily enable debugging for a single RSpec run by using the -r option together with the library name:
| | $ rspec -rbyebug |
The other option in this group, -I, adds a directory to Ruby’s load path.[61] This helps Ruby find libraries that you load from a require statement or the --require switch.
RSpec already adds the two most important directories to the load path: your project’s lib and spec folders. But sometimes you may want to use a particular library without going through Bundler or RubyGems; that’s where this flag comes in handy.
Filtering Options
Now that we’ve covered options that configure the environment for your specs, let’s talk about the options that govern which of your specs RSpec will run. Running just the specs you need at any given time will make you much more productive. To that end, RSpec supports a number of filtering options, listed further down in the --help output:
| | **** Filtering/tags **** |
| | |
| | In addition to the following options for selecting specific files, |
| | groups, or examples, you can select individual examples by appending |
| | the line number(s) to the filename: |
| | |
| | rspec path/to/a_spec.rb:37:87 |
| | |
| | You can also pass example ids enclosed in square brackets: |
| | |
| | rspec path/to/a_spec.rb[1:5,1:6] # run the 5th and 6th examples/groups ↩ |
| | defined in the 1st group |
| | |
| | --only-failures Filter to just the examples that ↩ |
| | failed the last time they ran. |
| | --next-failure Apply `--only-failures` and abort ↩ |
| | after one failure. (Equivalent to ↩ |
| | `--only-failures --fail-fast --order ↩ |
| | defined`) |
| | -P, --pattern PATTERN Load files matching pattern (default: ↩ |
| | "spec/**/*_spec.rb"). |
| | --exclude-pattern PATTERN Load files except those matching ↩ |
| | pattern. Opposite effect of --pattern. |
| | -e, --example STRING Run examples whose full nested names ↩ |
| | include STRING (may be used more than ↩ |
| | once) |
| | -t, --tag TAG[:VALUE] Run examples with the specified tag, ↩ |
| | or exclude examples by adding ~ before ↩ |
| | the tag. |
| | - e.g. ~slow |
| | - TAG is always converted to a symbol |
| | --default-path PATH Set the default path where RSpec looks ↩ |
| | for examples (can be a path to a file ↩ |
| | or a directory). |
You’ve used several of these options throughout this book. For instance, you passed --only-failures to run just the specs that failed the previous RSpec run. You saw how to use --tag to run only the specs that were tagged with a piece of metadata, such as :fast.
We’re not going to spend too much time going back over these flags in detail a second time. But it’s worth gathering the most common options into one place and explaining when each one comes in handy:
- rspec path/to/a_spec.rb:37
-
Appending a line number to your filenames is the simplest way to run a particular example or group, particularly if you’ve configured your text editor to do so with a keystroke.
- --only-failures
-
Any time you have failed specs, those are usually the ones you want to focus your attention on. This option makes it easy to rerun just the failures.
- --next-failure
-
A more surgical form of --only-failures, this option is nice when you want to fix and test each failure one by one.
- --example ’part of a description’
-
This option comes in handy when you want to run a particular example or group, and you can remember part of the description but not what line it’s on.
- --tag tag_name
-
If you carefully tag your examples and groups with appropriate metadata, this powerful option will let you run arbitrary cross-sections of your suite.
By running exactly the specs you need, you minimize how long you have to wait to get feedback on your code changes.
Output Options
Different situations call for different levels of detail in your test suite output. Elsewhere in the --help text, you’ll see a number of output options:
| | **** Output **** |
| | |
| | -f, --format FORMATTER Choose a formatter. |
| | [p]rogress (default - dots) |
| | [d]ocumentation (group and example ↩ |
| | names) |
| | [h]tml |
| | [j]son |
| | custom formatter class name |
| | -o, --out FILE Write output to a file instead of ↩ |
| | $stdout. This option applies to the ↩ |
| | previously specified --format, or the ↩ |
| | default format if no format is ↩ |
| | specified. |
| | --deprecation-out FILE Write deprecation warnings to a file ↩ |
| | instead of $stderr. |
| | -b, --backtrace Enable full backtrace. |
| | --force-color, --force-colour Force the output to be in color, even ↩ |
| | if the output is not a TTY |
| | --no-color, --no-colour Force the output to not be in color, ↩ |
| | even if the output is a TTY |
| | -p, --[no-]profile [COUNT] Enable profiling of examples and list ↩ |
| | the slowest examples (default: 10). |
| | --dry-run Print the formatter output of your ↩ |
| | suite without running any examples or ↩ |
| | hooks |
| | -w, --warnings Enable ruby warnings |
We’ll get to formatters in a moment. For now, let’s take a closer look at three of the other options in this section:
- --backtrace
-
RSpec normally tries to keep error backtraces short; it excludes lines from RSpec itself and from any gems you’ve configured. When you need more context for debugging, you can pass --backtrace (or just -b) and see the entire call stack.
- --dry-run
-
This option, combined with --format doc, is a useful way to quickly get documentation-like output for your project—as long as you’ve taken care to phrase your example and group descriptions well.
- --warnings
-
Ruby’s warning mode can point out some common mistakes, such as instance variable misspellings. Unfortunately, Ruby will print warnings for all running code, including gems. If you’re developing an app with lots of dependencies, you’ll likely get a lot of noise in the output. But if you’re developing a simple library, this option can be useful.
These options will help you drill down into details when you’re diagnosing a failure, without cluttering up the output of every test run.