## 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` commmand. 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.
@see RSpec::Core::Formatters::BaseTextFormatter @see RSpec::Core::Reporter
Register the formatter class @param formatter_class [Class] formatter class to register @param notifications [Symbol, …] one or more notifications to be registered to the specified formatter
@see RSpec::Core::Formatters::BaseFormatter
# File lib/rspec/core/formatters.rb, line 77 def self.register(formatter_class, *notifications) Loader.formatters[formatter_class] = notifications end