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, :example_passed, :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.