You’re almost cuking it…

In “You’re Cuking it Wrong”, Jonas Nicklas, shows several examples of bad scenarios (or acceptance tests whichever term you prefer) and demonstrates better approaches. This is an excellent post on common mistakes made when writing example scenarios with Cucumber.

I think, however, he could have gone further in one case. One of his examples of a bad scenario looks like this:

Scenario: Adding a subpage
Given I am logged in
Given a microsite with a Home page
When I click the Add Subpage button
And I fill in "Gallery" for "Title" within "#document_form_container"
And I press "Ok" within ".ui-dialog-buttonpane"
Then I should see /Gallery/ within "#documents"

(Dude – yep, seen these… I agree… not good). He goes on to suggest it should really look like this:

Scenario: Adding a subpage
Given I am logged in
Given a microsite with a home page
When I press "Add subpage"
And I fill in "Title" with "Gallery"
And I press "Ok"
Then I should see a document called "Gallery"

This is a massive improvement. It keeps the specifics that inform the reader and give them some context (like filling in the “Title” with “Gallery”) and takes them further away from the implementation. Although it gets closer to expressing customer intent, I think it could go further. At the moment, it is describing the ‘what’ and some of the ‘how’. This example makes complete sense if what we are exploring is the design of the UI. I’ve not found these scenarios to be a good place to do that, however.

Instead, in these specifications we want our examples to illustrate the customer intent. The ‘what’ not the ‘how’. There are other places we can capture the ‘how’ – i.e. in the step methods.

Instead, I would write it like this:

Scenario: Adding a subpage
Given a microsite with a home page
Given I am logged in
When I Add a Subpage with a Title of "Gallery"
Then I should see a document called "Gallery"

I’ve removed all the “Tasks” and left only “Activities”. This leaves the user experience completely open. This ensures that when there are UI changes, I only change the code that performs the tasks (clicking, pressing, etc.) and my scenarios evaluate whether the customer intent is still fulfilled – without having to go back and change a lot of files.

Otherwise – great post Jonas 🙂

  • James Martin

    Antony, under what circumstance would you consider it beneficial switching from the first to the third person narrative in these scenarios?

    I'm thinking of the Fitnesse Narrative example, where you used a descriptive name (e.g. Fitnesse User) in the third person throughout the acceptance test. Is that an important technique in ATDD or did it just make sense in the context of the metaphor you were using for NarrativeFixture?

  • Hey James,
    For me, I would generally use a role name from the outset. If we were working from story cards, then it would probably say something like “As a FitNesse User…” and I would then put that in straight away.
    However, if I was refactoring someone else's Cucumber tests from a mixture of Activities and Tasks to just Activities, I would probably preserve their narrative format. (I probably wouldn't change their tabs to spaces either 🙂 )

  • Andy's remark about refactoring someone else's test is exactly why I didn't change it from first to third person 🙂

    I made one other change while I was writing the post but reverted it because I didn't want to distract people from the main point of the post. The change was to use the Given to say who I am…

    Given I am logged in as an Editor


    Given I am an Editor
    and I have a microsite with a homepage
    When I Add a Subpage with a Title of “Gallery”
    Then I should see a document called “Gallery”

    OR, instead of “an Editor” I might use a persona name if we have well established personas on the project.

  • James Martin

    Thanks, guys.

    I've recently found that trying to use persona/actor names right from the very first acceptance test really helps when starting to write code (from the outside-in).

    Would be interested to know if it's as helpful for the non-programmers in an organisation. I suspect it would, at the very least, encourage the team to establish an ubiquitous language for their domain.

  • Pingback: (My) Cucumber best practices and tips | EggsOnBread()

  • Rakesh Loki

    Hello Antony, I agree with you – a scenario with tasks is more like a Test Scripts which should be updated when a change in UI.

  • Improved version … I think

    Given I am on my microsites home page
    When I add a “Gallery” subpage
    Then I should see the “Gallery” subpage

    There is no need to have two descriptions for one concept: subpage and document
    Do we really need to talk about “title” yet.

    Still have an issue with this which is:

    Where are we after we have added the subpage – on the home page, or on the subpage. Maybe its not yet important