Paul Hammant's Blog: TodoMVC and given-when-then scenarios
Business Analysts, in my opinion, are the best owners of Behavior Driven Development (BDD) initiatives. For “good” BDD-using stories, I am like former Supreme Court justice Potter Stewart in that I know it when I see it. I see so much bad BDD though, it is demoralizing.
Rather than point out some bad Given/When/Then usage, I thought I’d take an application that did not use BDD and reverse engineer some for discussion. That application is the famous TodoMVC. Click on any of the examples to play with it, but I’m going to do screenshots in line too.
The specification for the app is here. Addy Osmani started with one solution, made as much ‘reusable’ as he could (particularly the CSS), then encouraged others to fit the structure, style, and behaviors of the application for each different JavaScript solutions then made. Amongst other things, it would make them comparable. Indeed, I have previously focused on Addy’s initial crop of implementation for a ‘lines of code’ comparison in 2013. So then, the spec is not written for a team that is going to write the TodoMVC application from scratch. No matter - we can make a bunch of BDD acceptance criteria for a hypothetical team that could make it from scratch, MVP style.
TodoMVC Scenarios
Anyway, can somebody follow this posting with a Cucumber (etc) solution with the max amount of reused steps for the above, assuming I got the scenarios right - suggestions for those too are welcome :)
Scenario: Empty list can have item added
Given an empty Todo list
When I add a Todo for ‘Buy cheese’
Then only that item is listed
And the list summary is ‘1 item left’
And the list’s filter is set to ‘All’ with ‘Completed’ & ‘Active’ unset
And ‘Clear completed’ is unavailable
Scenario: Empty list can have two items added
Given an empty Todo list
When I add Todos for ‘Buy cheese’ & ‘Wash the car’
Then only those items are listed
And the list summary is ‘2 items left’
And the list’s filter is set to ‘All’ with ‘Completed’ & ‘Active’ unset
And ‘Clear completed’ is unavailable
Scenario: Item completion changes the list
Given a Todo list with items ‘File taxes’ & ‘Walk the dog’
When the first item is marked as complete
Then only the second item is listed as active
And the list summary is ‘1 item left’
And ‘Clear completed’ is available
Scenario: Completed items should not be visible in active filter
Given a Todo list with items ‘File taxes’ & ‘Walk the dog’
And the first item is completed
When the filter is set to ‘Active’
Then only the second item is listed
And the list summary is ‘1 item left’
And ‘Clear completed’ is available
And the route is /active
Scenario: All completed items should not be visible in active filter
Given a Todo list with items ‘File taxes’ & ‘Walk the dog’
And the first item is completed
And the second item is completed
When the filter is set to ‘Active’
Then nothing is listed
And the list summary is ‘0 items left’
And ‘Clear completed’ is available
And the route is /active
Scenario: Uncompleted items should not be visible in the completed filter
Given a Todo list with items ‘File taxes’ & ‘Walk the dog’
And the first item is completed
When the filter is set to ‘Completed’
Then only the first item is listed
And the list summary is ‘1 item left’
And ‘Clear completed’ is available
And the route is /completed
Scenario: Items can be cleared
Given a Todo list with items ‘File taxes’ & ‘Walk the dog’
And the first item is completed
When ‘Clear completed’ is clicked
Then only the second item is listed
And the list summary is ‘1 item left’
Scenario: clear all works when none completed
Given a Todo list with items ‘File taxes’ & ‘Walk the dog’
When the clear all items affordance is toggled
Then both items are listed
But nothing listed is active
And the list summary is ‘0 items left’
Scenario: clear all works when one of two completed
Given a Todo list with items ‘File taxes’ & ‘Walk the dog’
And the first item is completed
When the clear all items affordance is toggled
Then both items are listed
But nothing listed is active
And the list summary is ‘0 items left’
Scenario: Clear all un-clears when two of two completed
Given a Todo list with items ‘File taxes’ & ‘Walk the dog’
And the first item is completed
And the second item is completed
When the clear all items affordance is toggled
Then both items are listed
And both are active
And the list summary is ‘2 items left’
Scenario: Items can be straight removed
Given a Todo list with a single item ‘File taxes’
When the item is removed
Then nothing is listed
Scenario: Initiation of editing takes away delete and complete affordances
Given a Todo list with single item ‘File taxes’
When the item is selected for edit
Then the item cannot be completed
And the item cannot be removed
Scenario: Editing can change the text of an item
Given a Todo list with a single item ‘File taxes’
When the item is selected for edit
And the Todo is changed to ‘Apply for 6-month tax extension’
Then only the revised item is listed
Scenario: Editing can be abandoned
Given a Todo list with a single item ‘File taxes’
And that item is being edited
When editing is abandoned
Then only that item is listed
And the list summary is ‘1 item left’
Thoughts
Actual Stories and INVEST
I have just done a dump of the scenarios I could identify. Either the BA on their own, or with a project manager and lead developer, you would want to make stories. It won’t be 14 stories. Nor will it be 3. It will be somewhere in between, and the [INVEST](https://en.wikipedia.org/wiki/INVEST_(mnemonic) principle should apply when deciding how many. Ideally, none of those stories takes longer than a day, including QA. Just because a TODO list is simpler than your domain, you don’t get permission from the Agile Alliance to make average story sizes that are closer to a week than a day. If you are heading that way, apply INVEST again to make them smaller or critically look at a bunch of factors that would hinder small stories.
Classic mistakes
With a focus on automation rather that clarity for requirements capture is a common BDD mistake. Teams over focus on lengthy setups (the Given line), when in reality they should hit the tersest yet most expressive Givens they can. We have two in the scenarios above: 1) The list starts empty, 2) the list starts with something in it. Two perfectly valid preconditions. We know the app needs to have stuff entered into it in order to get to a place where #2 can begin, but we should not let that pre-condition detail leak into the Given lines for those scenarios.
An Obsession with being “logged in” is common for BDD + Selenium teams. “Given I am logged in” and some code behind the scenes to
actually do a login. Dev teams should help here. For pre-QA environment builds, have a way of bringing up the SUT
on localhost, and allowing the test suites to bypass the login screen and go directly to the rectangle in question.
Muddling Given and When. Sometimes you see interactivity expressed in the ‘Given’ lines, and tests expressed in the When lines. Nope - Given is setup/precondition and should mask any interactivity to get there. When is the interaction with the SUT, and the ‘Then’ is the verification/tests.
Who, when?
So we know that stories that leverage BDD acceptance criteria (narrative or description aside) and better for developers to understand as they begin developing a story. That means reducing the need to pester the BAs for clarity. Not that we should ever make BAs unavailable. It means less rework when test-engineer teammates find defects. Similarly, the work of test engineers is made simpler too - less misunderstanding on their part. Even if teams are manually testing software during the development cycle, there is still a benefit from the BDD style acceptance criteria, defined earlier in a timeline.
Business language only
Also when we get busy with BDD, we should try to use the language of the business exclusively. In doing that we avoid the language of “click”, and allude to a UI rather than call it out with every step. You will see that I could not manage to excise click-centric language above. I’m sure someone else will be able to do better.
Accompanying documents
We perhaps need a glossary for all those business terms (nouns, roles, top level activities). That will help newbies get acclimated to a project too. Similarly, a UX “style guide” will help. Like the glossary, it is a cross-cutting document. Here’s a single line from that pertinent to one of our scenarios above, maybe:
- “Text fields - editing - leaving editing can be performed by clicking away, and by hitting escape.”
Tune for developer throughput
We should remember that as developers form the majority of a dev team, they are nearly always the expensive group we tune everything else for. Time spent getting stories right before development starts pays off, many times. If everything else is going right. it stretches the viable life of software into a decade.
Footnotes and Regret
Me and BDD
I got into BDD in 2008. That was late, really, because I used to hang out Dan North, Chris Matts and Chris Stevenson in ThoughtWorks in London in 2002/3/4 when they were pioneering to science. In 2008 I became a committer on the JBehave project that Dan started. Dan and Liz Keogh stepped back from it, and Mauro Talevi has lead the project since. JBehave was the first BDD framework. Mauro and I presented at Agile 2009 on Selenium and JBehave together, but that was with a QA rather than BA perspective. Sadly the Agile Alliance only has a placeholder presently for the 2009 site.
These days, Cucumber is more popular than JBehave. Aslak Hellosøy (the creator of Cucumber) was also a house guest of mine for a month when he first joined ThoughtWorks in London in 2002 - but the pair of us were more into Dependency Injection back then. In ThoughtWorks too, I worked with Dave Astels on a project L.A in 2004, but it was cancelled after a week, so I did not really get to hang with him, though I would bump into him again at Google in 2007/8 where I started paying attention to the topic.
So I know the movers and shakers, and regret not listening intently enough between 2002 and 2008.
TodoBackend’s specs
OK, that aside, there’s one more thing you may want to look at. Pete Hodgson (as nearly everyone mentioned in this article, ex ThoughtWorks) made TodoBackend.com. He made ‘specs’ to verify the wire-API between the browser app and any backend that would be compatible with his modified Backbone.js TodoMVC app. Modified from Addy’s version, that is.
You can see those specs running against a Sintra instance - http://todobackend.com/specs/index.html?https://todo-backend-sinatra.herokuapp.com/todos. Pete is able to verify any of the solutions from a centralized script runner (you have to turn on CORS for the app). The BDD specs of this solution are in Dan’s original “it should” design (the first crop of BDD frameworks like RSpec focused on this). The Given/When/Then style is effectively BDD v2. If you were interested.