The elements of (cucumber) style

Originally posted on testingwithvision, moving content here for completeness.

I’m rather pedantic when it comes to writing English like Cucumber steps; so here’s some of my style guidelines I’ve developed the last few months. Some of my sources of inspiration include: You’re Cuking it Wrong, (My) Cucumber best practices and tips, and You’re Almost Cuking it.

Never write code in steps

When I click button with id "NameEditForm.Save Button" within table with id "NameDetails00001"

instead write something like

When I click the "Save" button in the "Name Details" section

Use double quotes in steps to indicate it’s an imperative (literal) step

As a rule of thumb, anything that is literally specified should be in double quotes, otherwise it should be specified within the sentence.

For example – an imperative style step

I set the field labeled "First Name" to "John"

As opposed to a declarative style step that still has parameters but doesn’t use double quotes.

I enter the details for user John

Cater for a/an where needed

Given I have found an active user
Given I have found a cancelled user

Matching step definition

^Given I have found an? (\w+ \w+)$

Use multi-line step arguments when checking multiple things

For example use:

Then I should see a form with fields: | First Name | | Surname | | Date of Birth |

instead of

Then I should see a form with fields "First Name, Surname, Date of Birth"

Make tables look like real tables

  • Line up the columns;
  • Put a single space at the beginning of each cell;
  • Don’t use double quotes for contents; and
  • Put a single colon (:) on the end of the preceding line.
Then I should see a form with fields: | First Name | Joe | | Surname | Heinzenburgersteinington | | Date of Birth | 01/01/1900 | 

Instead of

 Then I should see a form with fields: |"First Name"|"Joe"| |"Surname"|"Heinzenburgersteinington"| |"Date of Birth"|"01/01/1900"|

Cater for support for 1st, 2nd, 3rd etc. values in step defintions

For example:

I click the 3rd button labelled "Save"

Matching step definition

^I click the (\d+)\w\w button labelled "([^"]*)"$


These are some elements of style that I have found to be useful. What has worked for you? Do you have your own elements of style?

Author: Alister Scott

Alister is an Excellence Wrangler for Automattic.

4 thoughts on “The elements of (cucumber) style”

  1. I’ll chime in on the declaritive/imperitive debate above.

    I am desperately trying to stamp out the practice of talking about UI elements in cucumber tests ( as usually the UI implementation is irrelevant to the thing you are trying to test)

    This seems to come from a misguided sense of re-use: “Hey if I write enough generic steps like those in cucumbers web-steps, then I can write almost my whole cucumber suite without having to write any step definitions!”

    The problem with this is
    a) as Nat says, it only really works if you write your tests post-implementation so that “you know what buttons to click and what text fields to fill in”
    b) If you want to change the UI you suddenly find that you acceptance suite has assumptions about the UI scattered all the way through it. This leads to the anti-pattern of not writing acceptance tests until the UI has “settled down”
    c) All this clicking and filling in etc makes the script hard to read – what am I actually doing?


    1. Chiming in late, but I very much agree. Unless it’s really important (e.g. part of the purpose of the story) to describe the workflow/steps in detail, then that stuff should be left out of your features. The better path to re-use would seem to be having the declarative steps implemented via calling a number of more generic imperative steps, Provided such steps are implemented via more than a single line of ruby code such as login_page.password = @user.password, in which case you already have an abstraction layer and re-use means and invoking it via a generic step would just be redundant.


Comments are closed.