Story Driven Development With Cucumber

Editor's Notes

• #4: The root cause of so many problems in software projects is miscommunication.
• #5: 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.
• #6: In the course of a project, it’s often hard to tell what’s really important to its success...
• #7: ...and who said what, and why you should care.
• #8: Bottom line, miscommunication is wasteful - in time, money, energy and relationships.
• #9: Miscommunication causes you to build the wrong feature...
• #10: ... or to build it incorrectly ...
• #11: ... or to build unnecessary features.
• #12: 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.
• #13: 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.
• #14: 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?
• #15: 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.
• #16: The focus of SDD is to keep your software lean and to create value with every new feature.
• #17: That is, at each step you’ll be doing the minimum to satisfy the requirements specified by the story...
• #18: ...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).
• #19: The path to finding the business value in each new feature is to pop the “why” stack.
• #20: 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.
• #21: 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”.
• #22: With story-driven development, you can start to bridge Martin Fowler’s “yawning crevasse of doom” between the developers and the suits.
• #23: 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.
• #24: Furthermore, your user stories are executable tests that can be used to verify your software. Hooray for TDD!
• #25: 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...
• #26: 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.
• #27: Cucumber is also, unsurprisingly, a Ruby library that runs the stories as tests against your application.
• #28: 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.
• #29: So here’s a pretty typical Cucumber story; this one happens to be about signing up to use the application.
• #30: 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.
• #31: 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.
• #32: 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.
• #33: 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.
• #34: 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.
• #35: So, since this is a Rails app, we’ll use script/generate to create the User model and migrate the database.
• #36: 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!
• #37: 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...
• #38: ... 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.
• #39: 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.
• #40: 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.
• #41: 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.
• #42: 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!
• #43: 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”.
• #44: 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.
• #45: 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]
• #46: 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.
• #47: 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.
• #48: 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.
• #49: 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.
• #50: 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?
• #51: You want to reveal intention. Your user doesn’t care about how the software is implemented unless they are directly affected.
• #52: 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).
• #53: 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.
• #54: 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.
• #55: A common “story smell” in features are conjunctive statements. This is best illustrated in an example.
• #56: 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.
• #57: 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.
• #58: 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.
• #59: Cucumber provides a few more features in the DSL that let you keep your stories terse and cover corner or edge cases efficiently.
• #60: 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).
• #61: Finally, we have Scenario Outlines, which are really great for quickly specifying scenarios across a range of possibilities, including edge or corner cases. Cucumber will run the outline against every row of the table that you specify in the “Examples” section, and apply the values in the table to the angle-bracketed items.
• #62: So, that’s the overview of Cucumber, and now here comes some shameless self-promotion.
• #63: 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.
• #64: Now that that’s over...
• #65: Do you have any questions?