Command Line
Executing examples directly
Any file RSpec examples can be run directly from the command line:
$ spec path/to/my_spec.rb [options]
This will print the results to STDOUT. Use the —help option for more details. This is practical when you only want to run one file. If you want to run more, use the spec command or the Rake task.
The spec command
After you install RSpec, you should have the spec command on your PATH. This command can be used to process several files in one go.
Any number of files, directories and shell globs can be provided, all ruby source files that are found are loaded. To see this in action, cd to the RSpec install directory (normally under /usr/local/lib/ruby/gems/1.8/gems/rspec-x.y.z/) and type spec examples:
$ spec examples Profiling enabled. ......................................... Top 10 slowest examples: 0.0004640 A FileAccessor should open a file and pass it to the processor's process method 0.0003350 The square root of 1 should be 1 0.0001950 Stack (empty) should be empty 0.0001800 An IoProcessor should raise nothing when the file is exactly 32 bytes 0.0001760 Stack (with one item less than capacity) should not be empty 0.0001690 Stack (full) should complain on #push 0.0001630 Stack (empty) should complain when sent #peek 0.0001630 An IoProcessor should raise an exception when the file length is less than 32 bytes 0.0001560 Stack (full) should be full 0.0001510 Stack (empty) should complain when sent #pop Finished in 0.01743 seconds 41 examples, 0 failures
Very simple and to the point. Passing examples are indicated by a ‘.’, failing ones by a ‘F’. Note that failure indicates a violated expectation as well as an unexpected exception being raised. Here are examples of both:
$ spec examples/failing/team_spec.rb Profiling enabled. F.F Top 10 slowest examples: 0.0001250 BDD framework should be intuitive 1) 'BDD framework should be adopted quickly' FAILED expected adopted_quickly? to return true, got false ./examples/failing/predicate_example.rb:20: 2) NoMethodError in 'BDD framework should not respond to test' private method `test' called for #<BddFramework:0x10d984578> ./examples/failing/predicate_example.rb:29: Finished in 0.0106 seconds 3 examples, 2 failures
Command line options
When you run spec with the —help option it prints a help message:
$ spec --help
Usage: spec (FILE(:LINE)?|DIRECTORY|GLOB)+ [options]
-p, --pattern [PATTERN] Limit files loaded to those matching this pattern. Defaults to '**/*_spec.rb'
Separate multiple patterns with commas.
Applies only to directories named on the command line (files
named explicitly on the command line will be loaded regardless).
-D, --diff [FORMAT] Show diff of objects that are expected to be equal when they are not
Builtin formats: unified|u|context|c
You can also specify a custom differ class
(in which case you should also specify --require)
-c, --colour, --color Show coloured (red/green) output
-e, --example [NAME|FILE_NAME] Execute example(s) with matching name(s). If the argument is
the path to an existing file (typically generated by a previous
run using --format failing_examples:file.txt), then the examples
on each line of that file will be executed. If the file is empty,
all examples will be run (as if --example was not specified).
If the argument is not an existing file, then it is treated as
an example name directly, causing RSpec to run just the example
matching that name
-s, --specification [NAME] DEPRECATED - use -e instead
(This will be removed when autotest works with -e)
-l, --line LINE_NUMBER Execute example group or example at given line.
(does not work for dynamically generated examples)
-f, --format FORMAT[:WHERE] Specifies what format to use for output. Specify WHERE to tell
the formatter where to write the output. All built-in formats
expect WHERE to be a file name, and will write to $stdout if it's
not specified. The --format option may be specified several times
if you want several outputs
Builtin formats:
silent|l : No output
progress|p : Text-based progress bar
profile|o : Text-based progress bar with profiling of 10 slowest examples
specdoc|s : Code example doc strings
nested|n : Code example doc strings with nested groups indented
html|h : A nice HTML report
failing_examples|e : Write all failing examples - input for --example
failing_example_groups|g : Write all failing example groups - input for --example
FORMAT can also be the name of a custom formatter class
(in which case you should also specify --require to load it)
-r, --require FILE Require FILE before running specs
Useful for loading custom formatters or other extensions.
If this option is used it must come before the others
-b, --backtrace Output full backtrace
-L, --loadby STRATEGY Specify the strategy by which spec files should be loaded.
STRATEGY can currently only be 'mtime' (File modification time)
By default, spec files are loaded in alphabetical order if --loadby
is not specified.
-R, --reverse Run examples in reverse order
-t, --timeout FLOAT Interrupt and fail each example that doesn't complete in the
specified time
-H, --heckle CODE If all examples pass, this will mutate the classes and methods
identified by CODE little by little and run all the examples again
for each mutation. The intent is that for each mutation, at least
one example *should* fail, and RSpec will tell you if this is not the
case. CODE should be either Some::Module, Some::Class or
Some::Fabulous#method}
-d, --dry-run Invokes formatters without executing the examples.
-O, --options PATH Read options from a file
-G, --generate-options PATH Generate an options file for --options
-U, --runner RUNNER Use a custom Runner.
-u, --debugger Enable ruby-debugging.
-X, --drb Run examples via DRb. (For example against script/spec_server)
--port PORT Port for DRb server. (Ignored without --drb)
-v, --version Show version
--autospec
-h, --help You're looking at it
The command line options can be passed to customize the output and behaviour of RSpec.
The options apply whether specs are run in standalone mode (by executing the .rb files directly with ruby),
or using the spec command.