story driven development with cucumber

Story-Driven Development

with Cucumber

Sean Cribbs

Wednesday, January 6, 2010

who am i

•Freelance Web Consultant

•Radiant Lead Dev

•Ruby, Javascript, Erlang

•Open-source contributor github.com/seancribbs


miscommunication


The root cause of so many problems in software projects is miscommunication.

abstract


This is largely because so much of software development is abstract - that is, it happens in your brain. Nontechnical people also have ideas and desires about what software can do that are equally abstract.

what’s important


In the course of a project, it’s often hard to tell what’s really important to its success...

who said what


...and who said what, and why you should care.

miscommunication=

waste


Bottom line, miscommunication is wasteful - in time, money, energy and relationships.

wrong


Miscommunication causes you to build the wrong feature...

incorrectly


... or to build it incorrectly ...

unnecessarily


... or to build unnecessary features.

“Agile”


I bet you’re saying, “hey, aren’t you using an Agile process?” Why yes, I am, thanks. Agile methodologies have a few tools that we can use to help alleviate these miscommunication problems.

user stories


The first is user stories. For any feature that needs to be developed, you create a persona and write a story about how that person will use your software, and what things that person will want to accomplish.

Test-Driven Development


Agile also gives us one of the top buzzes of the Ruby community since its adoption in the West- TDD. TDD encourages us to write tests for our software before we write the software, often resulting in better designs and greater flexibility as the project evolves. So what if we put these two techniques together?

Story-Driven Development


When you do, you get what I call Story-Driven Development. Your agile user stories become the tests for your software. You’ll see more of what I mean in a little bit.

stay leancreate value


The focus of SDD is to keep your software lean and to create value with every new feature.

minimum to satisfy


That is, at each step you’ll be doing the minimum to satisfy the requirements specified by the story...

make, protect, savemoney


...and that story will be designed so that it directly affects your project’s ability to make new revenue, protect existing revenue, control costs, or alleviate user pain and increase utility (basically protecting revenue).

pop the “why”stack


The path to finding the business value in each new feature is to pop the “why” stack.

who are the stakeholders?


That is, the person writing the story will query the business expert who is requesting the feature with pointed “why” questions until the result comes down to money. Along the way, you’ll identify who the stakeholders are and what value they receive. We’ll see more about how this fits into the process later.

improves communication


By expressing the tests for your software first as user stories, you are greatly increasing the ability for the technical people to communicate with the business people. You start to develop a “ubiquitous language” for the problem your software addresses that will assist as the project progresses. See also Eric Evans’ “Domain Driven Design”.

bridge thecrevasse of doom


With story-driven development, you can start to bridge Martin Fowler’s “yawning crevasse of doom” between the developers and the suits.

living functional spec


Your stories become a living functional specification and documentation for your software. Rather than requirements being handed down etched in a stone tablet, the stories become conversation pieces between all parties in the process -- customers, project managers, designers, and developers.

stories = tests


Furthermore, your user stories are executable tests that can be used to verify your software. Hooray for TDD!

http://cukes.info/


So how can you implement this process in a Ruby project? You use Cucumber!

Now what I’ve described before this point is 75% or more of what you’ll do in Story-Driven Development. Cucumber is just a tool to take you the last 25% from concept to implementation. So this next section is going to be a little more about the “how” and not the “why”. But first, more about Cucumber...

http://cukes.info

http://cukes.info

business-readableDSL


Cucumber’s first component is a business-readable DSL curiously called “gherkin”. This is a loose format for structuring your user stories so that they will easily translate to executable tests. Note that I didn’t say “business-writable”! The DSL is meant to be written by somebody who works with the biz person, but is also aware of the technical side.

a Ruby library


Cucumber is also, unsurprisingly, a Ruby library that runs the stories as tests against your application.

integration tests


Cucumber stories are intended to exercise your application from top-to-bottom, or more accurately, from the perspective of the user. So if you had to classify them, they’d be considered integration tests.

Feature: Standard Signup In order to begin using the application As a new user I want to create an account

Scenario: Signup with valid email/password combination Given I do not have an account When I signup with email and password Then I should be logged in And my profile details should be filled in


So here’s a pretty typical Cucumber story; this one happens to be about signing up to use the application.




The only portions of the story that Cucumber cares about are shown here in bold, so you’re pretty free to write the stories as make sense for the domain. “Scenario” signifies the beginning of a new story, Given/When/Then specify preconditions, user actions, and post-conditions respectively. You can also use “And” or “But” to make your story read well.

$ cucumberFeature: Standard Signup In order to begin using the application As a new user I want to create an account


1 scenario (1 undefined)4 steps (4 undefined)0m0.754s


So let’s execute that story. Cucumber parses the story and attempts to run the Given/When/Then steps that we defined. Since we haven’t written any code yet, all of the steps are pending.

You can implement step definitions for undefined steps with these snippets:

Given /Î do not have an account$/ do pendingend

When /Î signup with email and password$/ do pendingend

Then /Î should be logged in$/ do pendingend

Then /^my profile details should be filled in$/ do pendingend


Now, you were probably wondering how we can implement one of those steps. Well, Cucumber gives us a hint whenever we have unimplemented steps. You can copy and paste any or all of those blocks out of the terminal into your favorite editor.

Given /^I do not have an account$/ do User.count.should == 0end


So let’s implement the first step. Given represents preconditions, so in this case, we’re just doing a paranoid check that there are no registered users. If this statement makes you uncomfortable, don’t worry just yet. Let’s run the story again.


Scenario: Signup with valid email/password combination Given I do not have an account uninitialized constant User (NameError) ./features/step_definitions/signup_steps.rb:2:in `/^I do not have an account$/' features/signup.feature:7:in `Given I do not have an account' When I signup with email and password Then I should be logged in And my profile details should be filled in

Failing Scenarios:cucumber features/signup.feature:6 # Scenario: Signup with valid email/password combination

1 scenario (1 failed)4 steps (1 failed, 3 undefined)0m0.136s


Well, it failed, DUH! We haven’t defined the User class yet. So let’s go “down a gear” and implement what we need to make that step pass.

$ script/generate model User email:string password:string exists app/models/ exists test/unit/ exists test/fixtures/ create app/models/user.rb create test/unit/user_test.rb create test/fixtures/users.yml create db/migrate create db/migrate/20090912024901_create_users.rb$ rake db:migrate db:test:prepare== CreateUsers: migrating =========================-- create_table(:users) -> 0.0016s== CreateUsers: migrated (0.0017s) ================


So, since this is a Rails app, we’ll use script/generate to create the User model and migrate the database.



1 scenario (1 undefined)4 steps (3 undefined, 1 passed)0m0.136s


Now if we run the story again, we see that the step passed. Before we did that, we might want to write some test/unit tests or RSpec examples to exercise our User model. However - remember we’re always trying to do the minimum amount possible to make the feature pass. If it wasn’t asked for, don’t build it!

rinse and repeat


So once you have created a step matcher, written what needs to be written to exercise the application, and filled in your lower layers of tests, you repeat that process until you get...



1 scenario (1 passed)4 steps (4 passed)0m0.138s


... all green! At this point, you would pass the feature to other stakeholders who will evaluate and hopefully approve the work. But let’s first talk about some more of the features that Cucumber gives you that’ll make story-driven development a snap.

Before do # do before each scenarioend

After do # do after each scenarioend

AfterStep do # do after each Given/When/Then/And/But stepend

Before("@tagged") do # do before scenarios tagged with @taggedend


Every testing framework pretty much needs lifecycle hooks, and Cucumber doesn’t disappoint. You can define blocks that will be executed before or after each scenario, after each step, or applied to only specific scenarios or features you have tagged.

# features/support/time.rbmodule TimeHelpers def set_zone(zone_name) Time.zone = zone_name endend

World(TimeHelpers)

# features/step_definitions/user_steps.rbGiven /^I am in the "([^"]*)" time zone$/ do |zone| set_zone(zone)end


One feature I use a lot is to extend the Cucumber “World”, which is the object within which all of your steps execute. Just define a module and pass it to the global “World” method, and then the module’s methods will be available within any step or callback. There are quite a few plugins for Cucumber that use this technique.

good stories are hard to write


So far, I’ve been speaking about how great this process is. But the ugly truth is that good user stories are really hard to write.

start with the value proposition


So how do you begin? You first write the value proposition. This is the most important part of your story and should answer why you need the described feature at all!

Feature: Name or theme


I start by writing “Feature:” and then a descriptive name for the thing that this story will describe, or a vertical aspect of the application that might not have a specific name -- for example, “Admin privileges”.

Feature: Name or theme In order to make, protect, or save money As a stakeholder I want to have some feature


The next part is to “pop the why stack”, identifying the value in the feature. I usually write the value proposition in this three-line format, but there are no restrictions on how you write it. I just find that this format helps me focus on the business value of the feature.

Feature: School account management In order to maximize revenue by offering our product to multiple schools at once As the site owner I want to provide individual accounts to each school and manage them


So here’s an example from an app I worked on earlier this year. We identified the value, who would be taking the action in the story, and what the software would do to provide that value. This story describes a feature of an application for student goal and competency management in primary and secondary schools. [describe the value prop]

Feature: School account management In order to maximize revenue by offering Schoolbinder to multiple schools at once As the site owner I want to provide individual accounts to each school and manage them

Scenario: List accounts Scenario: Create an account Scenario: Revoke an account Scenario: List admin users for accounts Scenario: Change subdomain for account


Next, I create a list of the various things the stakeholder/user can do. Each of these things becomes a scenario within the feature story.


Scenario: List accounts Then I should see a list of accounts


Then you start formulating the scenario. The best way to do this is to write the outcome or “Then” step first, making sure that the desired outcome directly relates to the value proposition stated at the top. In this story, we want to manage school accounts, so seeing a list of the existing accounts would help toward that goal.


Scenario: List accounts When I go to the accounts page Then I should see a list of accounts


After you have the outcome, you decide what action the user takes to achieve that outcome, or the “When” steps. In this case, our user is navigating to the accounts page in our web app.


Scenario: List accounts Given I am logged in as the site owner When I go to the accounts page Then I should see a list of accounts


Finally, you write the preconditions for the user to be able to take that action, or the “Given” steps. We want this functionality only accessible to the site owner and not normal users, so we specify that the user must be logged in as the owner.

descriptive > imperative


So how did I decide to write the story in that fashion? A good rule of thumb to use is that descriptive stories are generally better than imperative stories. Why?

intention > implementation


You want to reveal intention. Your user doesn’t care about how the software is implemented unless they are directly affected.

# descriptiveWhen I create a new account for "ms218"

# imperativeWhen I follow "New account"And I fill in "Name" with "ms218"And I submit the form


Here’s an example from our previous feature of how descriptive steps and imperative steps differ. In the first we’re talking about a holistic action (WHAT), whereas in the second we specify the nitty-gritty detail (HOW).

descriptive storiesare flexible


Descriptive stories are more flexible than imperative stories. Why? The user interface of your software is the most brittle portion - you don’t want your whole suite of tests to break if the designer changes the wording of a single button, link, or field without changing the core functionality of the app.

strike balancetoo implicit = vague


However, you still need to strike a balance. It’s easy to be too vague and have a story cover huge swaths of functionality without intending it. Or the story might be unclear about which of several alternatives to take. Try to be descriptive without being ambiguous.

Also, sometimes, especially early in the story-writing process, it’s a good thing to have imperative stories. When no code has written, when no design has been drawn, having that extra step-by-step may help flesh out more difficult details. You can always go back and rewrite those stories once everyone has a better grasp on the domain.

avoid conjunctive statements


A common “story smell” in features are conjunctive statements. This is best illustrated in an example.

# conjunctiveWhen I change my name to "Sean" and my password to "foobar"

# independentWhen I change my name to "Sean"And I change my password to "foobar"


Conjunctive steps like the first one shown here tend to conflate two separate user actions. Independent steps, however, make the story more readable and the steps reusable within other stories. Remember that we’re trying to develop a ubiquitous language for our domain -- reusability is key to that goal.

strive for single passes


Another “story smell” are multi-pass scenarios, or scenarios where multiple precondition-action-outcome groups occur. These are especially tempting to write if you are thinking imperatively about the problem.

# conflated scenarios, multiple passes Scenario: Bulk comment on short term goals Given I have set all short-term goals for "ELA > Writing > Organization" for class "601" When I follow "Edit" for long-term goal "Organization" And I follow "Comment" for short-term goal "Coherence" Then I should see all students that pertain to this short-term goal And I should see the standard comment box and "Post new comment" button When I type in the comment box And I follow "Post" Then I should see that my comment was posted

# single scenario, single pass Scenario: Bulk comment on short term goals Given I have set all short-term goals for "ELA > Writing > Organization" for class "601" When post a comment for short-term goal "Coherence" Then I should see that my comment was posted And all students in class "601" should receive my comment


The solution to multi-pass scenarios is to split them into multiple scenarios, or to abstract conditions and actions that are covered by another scenario. In this case, we’ve abstracted the concept of posting a comment, encompassing the steps the user took to get to that point. If you’ve already defined the offending steps for other stories, Cucumber lets you call them directly from within another step definition, so you can just subsume the steps that you want to abstract out.

stay tersecover corner cases


Cucumber provides a few more features in the DSL that let you keep your stories terse and cover corner or edge cases efficiently.

Background: Given an account for subdomain "ms217" And these administrators for subdomain "ms217":

| email | name | | [email protected] | Joe Smith | | [email protected] | Jane Doe | And this welcome message for subdomain "ms217": """ Welcome back, students! - The principal """


In this slide I’m showing three of those features. The first is Background, which looks like Scenario, but is defined at the top of a feature file and applies to all of the scenarios in that file -- basically like a “Before” block with multiple steps. The second is a table - which you can access within the definition for the step before the table. You can treat the table as a simple array, or an array of hashes using the headers in the first row. The last feature is a multi-line string or “py_string” (as in Python).

mailto:[email protected]




<self:promotion>


So, that’s the overview of Cucumber, and now here comes some shameless self-promotion.


You might have seen that little head in my second slide - which is from our app Lowdown. Lowdown is a collaborative story-writing tool for Cucumber that we created for the Rails Rumble last year, and we were lucky to win the prize for Appearance and User interface. I’d be willing to give a demonstration of Lowdown in the questions period.

</self:promotion>


Now that that’s over...

questions?


Do you have any questions?

story driven development with cucumber

Technology