Custom Formatters

Note that this information will go out of date when Cucumber 0.4 is released. See here for more details.

The public API for Cucumber’s formatters is defined by all the methods in the Cucumber::Ast::Visitor class, which you should use as your base class.

If you want to write your own custom formatter, just subclass Cucumber::Ast::Visitor. Maybe you want to create a formatter that posts a message to Twitter every time a step fails? (I’m sure that would get you a lot of followers).

Here is how you’d do that:

Save your custom formatter class in features/support (or if you want to put it elsewhere, put a file in that directory that requires your formatter class).

# features/support/twitter_formatter.rb
require 'rubygems'
require 'twitter'

module Silly
  class TwitterFormatter < Cucumber::Ast::Visitor
    def initialize(step_mother, io, options)
      super(step_mother)
      # We don't care about these - we're just twittering!
    end

    def visit_step_name(keyword, step_match, status, source_indent, background)
      if status == :failed
        step_name = step_match.format_args(lambda{|param| "*#{param}*"})
        message = "#{step_name} FAILED"
        Twitter::Base.new('your email', 'your password').post(message)
      end
    end
  end
end

Now you can run your features by passing --format Silly::TwitterFormatter to the cucumber command line, Rake task or even in cucumber.yml – see Running Features for all the options. You have more methods available than the ones used in this awesome example (but you only need to implement the ones you care about). Look at the sources for some of Cucumber’s built-in formatters to discover more methods.

If your formatter can’t be found

If cucumber complains that it can’t find your formatter, add an explicit --require dir, where dir is a parent directory of your formatter. You can also pass the full path to the ruby file where the formatter is defined.

The cucumber --help states:

Automatic loading is disabled when this option is specified, and all loading becomes explicit. Files under directories named “support” are always loaded first.

This means that you have to add your support folder to --require dir for it to be loaded.

Other Formatters

1. TeamCityFormatter: prints cucumber results in a format for interpretation by a TeamCity build agent
2. TextmateFormatter: prints cucumber results as HTML with enhanced styling and Javascript for Textmate