Macros4Cuke

Add macros to your Cucumber scenarios.
Homepage

Macros4Cuke is a lightweight library that adds a macro facility your Cucumber scenarios.
With it, you can create any new step that replaces a sequence of lower-level steps. All this can be done directly in your feature files without programming step definitions.

Highlights

Works with out-of-the-box Cucumber
Simple installation and setup (no programming required),
Substep sequence can be of arbitrary length,
Macro-steps may have data arguments,
Data values can be passed to the sub-steps.

A quick example

Here is a macro-step example taken from our demo files:

  Given I define the step "When I [enter my userid <userid> and password <password>]" to mean:  
  """  
  Given I landed in the homepage  
  When I click "Sign in"  
  And I fill in "Username" with "<userid>"  
  And I fill in "Password" with "<password>"  
  And I click "Submit"  
  """

Notice how the arguments userid and password are enclosed between chevrons (angle brackets) <...>.

That macro-step can then be used in a scenario like this:

  When I [enter my userid "jdoe" and password "hello-world"]

Once it is executing, the macro-step as the same effect as:

  Given I landed in the homepage  
  When I click "Sign in"  
  And I fill in "Username" with "jdoe"  
  And I fill in "Password" with "hello-world"  
  And I click "Submit"  
  """

In other words, this sequence of 5 steps can be replaced by just one. Macros4Cuke not only helps in getting rid of the repeated step sequences, it allows the feature writers to create themselves higher-level steps that are closer to the business logic.

See also the working examples in the features/ folder.

Setup

Installation

To install the macros4cuke gem:

$[sudo] gem install macros4cuke

Setting up your Cucumber project

Step 1: Add support for macros in your Cucumber project

# /features/support/env.rb
# Add the two next lines
require 'macros4cuke'  
World(Macros4Cuke::MacroStepSupport)

Step 2: Import the macro-management steps
In your /features/step_definitions/ folder:
- Create a Ruby file (say, 'use_macro_steps.rb') with the following line:

require 'macros4cuke/../macro_steps'

That's it! Now you can start writing macros in your Cucumber project.

Getting started

Working with a macro-step is a two-stages process:

Defining a new macro-step; and,
Using that macro-step in a scenario.

Let's begin by taking a closer look at the definition part.

Defining a macro-step

To create a macro-step, you'll need to use a defining step bundled with Macros4Cuke. It is a rather unusual Cucumber step in the sense that its sole purpose is to build another step!
The defining step follows the general pattern:

  Given I define the step "When I [some phrase]" to mean:  
  """  
  # A sequence of sub-steps comes here
  """

The defining step has two key components:

The quoted sentence "When I [some phrase]". That part specifies the syntax of your future macro-step.
The multiline text enclosed between the triple quotes (""") that immediately follows the the defining step. It is the place where the sub-steps are listed.

These two components are detailed now.

Specifying the syntax of a macro-step

As just mentioned earlier, the quoted sentence determines the syntax of the new macro-step. Its syntax is more or less free:

The text outside the square brackets follows a fixed pattern. In other words, the quoted sentence MUST always start as follows: "When I [.... Notice however, that the Given, Then keywords are also allowed.
The text delimited by the square brackets [...], is called the phrase.

A few remarks about the phrase part:

It must be unique. In other words, it is not possible to create another macro-step with the same phrase. In fact, Macros4Cuke uses the phrase internally as a mean to identify/name a macro-step.
It may have one or more arguments. Besides that, the text inside the phrase can be arbitrary (well, almost).

A phrase can be without argument as in:

  # A phrase without argument
  [enter my credentials]

Alternatively, a phrase can have one or more arguments enclosed between chevrons <...>. For instance, the next first phrase has two arguments, the second has three arguments:

  [enter my <userid> and <password>]
  [travel from <origin> to <destination> via <waypoint>]

Each argument (variable) is enclosed between <...> chevrons. In our last example, the argument names are: origin and destination. Notice that origin and destination are variable names that will take a value (if any) when the step is invoked (more on this later).

Specifying the sub-steps of a macro-step

The sub-steps are placed in a Gherkin multiline text, that is, a text that is enclosed between triple quotes ("""). In the next example,

  Given I define the step "When I [enter my credentials]" to mean:  
  """  
  Given I landed in the homepage   
  And I fill in "Username" with "tweedledum"  
  And I fill in "Password" with "tweedledee"  
  And I click "Sign in"  
  """

the text between triple quotes enumerates the sub-steps associated with the macro-step.
A pleasing aspect is the familiar syntax the sub-steps have: they closely look to genuine steps of a scenario.
Sub-steps can also have macro arguments. For instance, the previous step sequence could have two arguments called userid and password:

  """  
  Given I landed in the homepage   
  And I fill in "Username" with "<userid>"  
  And I fill in "Password" with "<password>"  
  And I click "Sign in"  
  """

Using (invoking) a macro-step

A macro-step can only be invoked after its definition has been read by Cucumber.
The syntax rules for using a given macro-step in a scenario are pretty straightforward:

Follow closely the syntax of the quoted sentence in the macro definition.
Replace every <argument> in the phrase by its actual value between quotes.

Example 1:

Consider the following macro-step definition:

  Given I define the step "When I [log in as <userid>]" to mean: 
  """
  # Sub-steps come here...
  """

Its quoted sentence is "When I [log in as <userid>]", therefore the macro-step can be invoked in a scenario like this:

  Given I do this ...
  When I [log in as "jdoe"]
  And I do that...

Example 2:

Here is another -partial- macro-step definition:

  Given I define the step "When I [travel from <origin> to <destination> via <stop>]" to mean: 
  """
  # Sub-steps come here...
  """

This macro-step can occur in a scenario as:

  When I [travel from "San Francisco" to "New-York" via "Las Vegas"]

The actual values for the arguments origin, destination and stop are respectively San Francisco, New-York and Las Vegas.

Passing argument data via a table

Passing more than three arguments in the phrase becomes problematic for readability reasons. One ends up with lengthy and clumsy steps.
Therefore Macros4Cuke has an alternative way to pass data values via a Gherkin table.
To enable this mechanism for a given macro, ensure that in its definition the quoted sentence ends with a terminating colon (:) character.

The next example is based on one of the demo feature files:

  # Next step has a colon ':'  after the ']': data can be passed with a table
  Given I define the step "When I [enter my address as follows]:" to mean:
  """
  When I fill in firstname with "<firstname>"  
  And I fill in lastname with  "<lastname>"  
  And I fill in street with "<street_address>"  
  And I fill in postcode with "<postcode>"  
  And I fill in locality with "<city>"  
  And I fill in country with "<country>"  
  """

This step can be used like this:

  When I [enter my address as follows]:"  
  |lastname|Doe|  
  |firstname|John|  
  |street_address| Main Street, 22|  
  |city| Old White Castle|  
  |postcode|JK345|

Here are few observations worth noticing:

The data table has two columns.
Each row is of the form: |argument name| actual value|. For instance, the argument street_address takes the value "Main Street, 22".
Data rows don't have to follow strictly the order of the arguments in the sub-step sequence.