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 ‘RSpec::Core::Formatters::BaseTextFormatter` and override the methods you wish to enhance.