Hooks

Cucumber provides a number of hooks which allow us to run blocks at various points in the Cucumber test cycle. You can put them in your support/env.rb file or any other file under the support directory, for example in a file called support/hooks.rb. There is no association between where the hook is defined and which scenario/step it is run for, but you can use tagged hooks (see below) if you want more fine grained control.

All defined hooks are run whenever the relevant event occurs.

Scenario hooks

Before hooks will be run before the first step of each scenario. They will run in the same order of which they are registered.

Before do
  # Do something before each scenario.
end

After hooks will be run after the last step of each scenario, even when there are failing, undefined, pending or skipped steps. They will run in the opposite order of which they are registered.

After do |scenario|
  # Do something after each scenario.
  # The +scenario+ argument is optional, but
  # if you use it, you can inspect status with
  # the #failed?, #passed? and #exception methods.

  if(scenario.failed?)
    subject = "[Project X] #{scenario.exception.message}"
    send_failure_email(subject)
  end
end

Around hooks will run “around” a scenario. This can be used to wrap the execution a scenario in a block. The Around hook receives a scenario object and a block (Proc) object. The scenario will be executed when you invoke block.call.

The following example will cause scenarios tagged with @fast to fail if the execution takes longer than 0.5 seconds:

Around('@fast') do |scenario, block|
  Timeout.timeout(0.5) do
    block.call
  end
end

You may want to take a look at SystemTimer if you want a more reliable timeout.

Step hooks

Warning: AfterStep hook does not work with scenarios which have backgrounds (cucumber 0.3.11)

AfterStep do |scenario|
  # Do something after each step.
end

Tagged hooks

Sometimes you may want a certain hook to run only for certain scenarios. This can be achieved by associating a Before, After or AfterStep hook with one or more tags. You can OR and AND tags in much the same way as you can when running Cucumber from the command line. Examples:

To OR tags pass the tags in a single string comma separated:

Before('@cucumis,@sativus') do
  # This will only run before scenarios tagged
  # with @cucumis OR @sativus.
end

To AND tags pass the tags as separate tag strings:

Before('@cucumis', '@sativus') do
  # This will only run before scenarios tagged
  # with @cucumis AND @sativus.
end

You create complex tag conditions using both OR and AND on tags:

Before('@cucumis,@sativus', '@aqua') do
  # This will only run before scenarios tagged
  # with (@cucumis OR @sativus) AND @aqua 
end

After Step example:

AfterStep('@cucumis', '@sativus') do
  # This will only run before steps within scenarios tagged
  # with @cucumis AND @sativus.
end

Think twice before you use this feature, as whatever happens in hooks is invisible to people who only read the features. You should consider using background as a more explicit alternative if the setup should be readable by non-technical people.

Global hooks

If you want something to happen once before any scenario is run – just put that code at the top-level in your env.rb file (or any other file in your features/support directory. Use Kernel#at_exit for global teardown. Example:

my_heavy_object = HeavyObject.new
my_heavy_object.do_it

at_exit do
  my_heavy_object.undo_it
end

You may also provide an AfterConfiguration hook that will be run after Cucumber has been configured. The block you provide will be passed the cucumber configuration (an instance of Cucumber::Cli::Configuration). Example:

AfterConfiguration do |config|
  puts "Features dwell in #{config.feature_dirs}"
end

This hook will run only once; after support has been loaded but before features are loaded. You can use this hook to extend Cucumber, for example you could affect how features are loaded or register custom formatters programatically.