Module: RSpec::Core::Formatters

Defined in:
lib/rspec/core/formatters.rb,
lib/rspec/core/formatters/helpers.rb,
lib/rspec/core/formatters/protocol.rb,
lib/rspec/core/formatters/html_printer.rb,
lib/rspec/core/formatters/console_codes.rb,
lib/rspec/core/formatters/json_formatter.rb,
lib/rspec/core/formatters/html_formatter.rb,
lib/rspec/core/formatters/base_formatter.rb,
lib/rspec/core/formatters/profile_formatter.rb,
lib/rspec/core/formatters/snippet_extractor.rb,
lib/rspec/core/formatters/progress_formatter.rb,
lib/rspec/core/formatters/base_text_formatter.rb,
lib/rspec/core/formatters/deprecation_formatter.rb,
lib/rspec/core/formatters/documentation_formatter.rb

Overview

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 Also:

Defined Under Namespace

Modules: ConsoleCodes, Helpers Classes: BaseFormatter, BaseTextFormatter, Loader, ProfileFormatter, Protocol, SnippetExtractor

Class Method Summary (collapse)

Class Method Details

+ (void) register(formatter_class, *notifications)

Register the formatter class

Parameters:

  • formatter_class (Class)

    formatter class to register

  • notifications (Symbol, ...)

    one or more notifications to be registered to the specified formatter

See Also:

78
79
80
# File 'lib/rspec/core/formatters.rb', line 78
def self.register(formatter_class, *notifications)
  Loader.formatters[formatter_class] = notifications
end