Module: RSpec::Core::Formatters

Built-in Formatters

• progress (default) - Prints dots for passing examples, F for failures, * for pending.
• documentation - Prints the docstrings passed to describe and it methods (and their aliases).
• html
• json - Useful for archiving data for subsequent analysis.

The progress formatter is the default, but you can choose any one or more of the other formatters by passing with the --format (or -f for short) command-line option, e.g.

rspec --format documentation

You can also send the output of multiple formatters to different streams, e.g.

rspec --format documentation --format html --out results.html

This example sends the output of the documentation formatter to $stdout, and the output of the html formatter to results.html.

Custom Formatters

You can tell ::RSpec to use a custom formatter by passing its path and name to the rspec command. For example, if you define MyCustomFormatter in path/to/my_custom_formatter.rb, you would type this command:

rspec --require path/to/my_custom_formatter.rb --format MyCustomFormatter

The reporter calls every formatter with this protocol:

• To start
  • start(StartNotification)
• Once per example group
  • example_group_started(GroupNotification)
• Once per example
  • example_started(ExampleNotification)
• One of these per example, depending on outcome
  • example_passed(ExampleNotification)
  • example_failed(FailedExampleNotification)
  • example_pending(ExampleNotification)
• Optionally at any time
  • message(MessageNotification)
• At the end of the suite
  • stop(ExamplesNotification)
  • start_dump(NullNotification)
  • dump_pending(ExamplesNotification)
  • dump_failures(ExamplesNotification)
  • dump_summary(SummaryNotification)
  • seed(SeedNotification)
  • close(NullNotification)

Only the notifications to which you subscribe your formatter will be called on your formatter. To subscribe your formatter use: RSpec::Core::Formatters#register e.g.

RSpec::Core::Formatters.register FormatterClassName, <code>:example_passed</code>, :example_failed

We recommend you implement the methods yourself; for simplicity we provide the default formatter output via our notification objects but if you prefer you can subclass BaseTextFormatter and override the methods you wish to enhance.