FROM STAKEHOLDER EXAMPLES TO LIVING DOCUMENTATION

Specification-By-Example with Gherkin

Christian Hassa - ch@techtalk.ch - Twitter: @chrishassaSwiss Requirements Day 2013, June 19th 2013

TechTalk Team

5

•Describe user needs or features•Unit of planning/prioritization

Help to say “Not now” – instead of “No”• Future options for evolving the system• Reminder for a conversation• Deferring detail to the

last responsible moment

What makes user stories agile?

6

RefiningUser Stories

7

Impact Mapping

Story Mapping

Specification-By-Example

Establishing a shared understandingWhy?

How?Code

Epics

Deliverables, Outputs

Impacts, Outcomes

Easier to define upfront Harder to define upfront

User Activities

User Stories

Goals

AcceptanceCriteria

Bugreports

Isolated,formalizedexamples

Examples

Reminderfor aconversation

8

Collecting Acceptance Criteria

“I would try to put a book into the shopping cart …”

“I would try to remove a book from the shopping cart…”

“I’d check whether the shopping cart is empty, when I enter the shop …”

Books can be added to shopping cart.

Books can be removed from shopping cart.

Shopping cart should be empty when entering the shop.

... ? …

As a potential customerI want to collect books in a shopping cartSo that I can order several books at once.

“Imagine this story is already implemented:

how would you verify it?”

“I would try to add 1000 books to the shopping cart …”

9

Usingexamples

11

UI wire frames,existing UI

rules, key examples

existing artifacts,samples

Different models of examples

12

Discussing examples …

public void TestInitialOrderDiscount()

{

Customer newCustomer = new Customer();

Order newOrder = new Order(newCustomer);

newOrder.AddBook(

Catalog.Find(“ISBN-0955683610”)

);

Assert.Equals(33.75,

newOrder.Subtotal);

}

Register as “bart_bookworm”Go to “/catalog/search”Enter “ISBN-0955683610”Click “Search”Click “Add to Cart”Click “View Cart”Verify “Subtotal” is “$33.75”

We would like to encourage new users to buy in our shop.Therefore we offer 10% discount for their first order.

Original idea for the illustration: George Dinwiddiehttp://blog.gdinwidiee.com

13

Specification-by-Example

Examples …• make abstract descriptions

better understandable

However …• examples are usually not formally

exchanged or documentedBrian Marick

Examples Tests

Requirements

consist of

describe verifyfulfillment of

14

Exploring a user need with examples

Books in catalogue:

Title Author

Specification-By-Example Gojko Adzic

Impact Mapping Gojko Adzic

Explore It! Elisabeth Hendrickson

Competitive Engineering Tom Gilb

… I want to find books in the catalogue by author and title

Search for … Books found …

Spec Specification-By-Example

Hend Explore It!

et Explore It!, Competitive Engineering

Context

ActionAssertion

15

Key examples: Breaking the model

Books in catalogue:

Title Author

Specification-By-Example Gojko Adzic

Impact Mapping Gojko Adzic

Explore It! Elisabeth Hendrickson

Competitive Engineering Tom Gilb

… I want to find books in the catalogue by author and title

Search for … Books found …

Spec Specification-By-Example

Hend Explore It!

et Explore It!, Competitive Engineering

What happens, if I search for “Explore Specification”?

Can I search for single characters, e.g. “e”?

Is the number of search results limited, or paged?

Is the search also performed in the sub-title of a book?

16

Discussion of acceptance criteria

public void TestInitialOrderDiscount()

{

Customer newCustomer = new Customer();

Order newOrder = new Order(newCustomer);

newOrder.AddBook(

Catalog.Find(“ISBN-0955683610”)

);

Assert.Equals(33.75,

newOrder.Subtotal);

}

Register as “bart_bookworm”Go to “/catalog/search”Enter “ISBN-0955683610”Click “Search”Click “Add to Cart”Click “View Cart”Verify “Subtotal” is “$33.75”

We would like to encourage new users to buy in our shop.Therefore we offer 10% discount for their first order.

Original idea for the illustration: George Dinwiddiehttp://blog.gdinwidiee.com

17

… illustrated with formalized examples

Given the user has not ordered yet

When the user adds a book with the price of EUR 37.5

into the shopping cart

Then the shopping cart sub-total is EUR 33.75.

Original idea for the illustration: George Dinwiddiehttp://blog.gdinwidiee.com

18

Discover hidden assumptions

Actually, this is not quite right:Books on sale should be excluded.

Original idea for the illustration: George Dinwiddiehttp://blog.gdinwidiee.com

19

Collaboration: 3 amigos

“HappyPath”

Technical feasability

Exceptions, border cases

Original idea for the illustration: George Dinwiddiehttp://blog.gdinwidiee.com

20

Abstract acceptance criteria

As a shop visitorI want to collect books in my shopping basketso that I can purchase multiple books at once.

Books can be added to the shopping basket

Books can be removed from the shopping basket

Shopping basket is initially empty

The same book can be added multiple times to the shopping basket

21

Examples in Gherkin

As a shop visitorI want to collect books in my shopping basketso that I can purchase multiple books at once.

Books can be added to the shopping basket

Given my shopping basket is empty

When I add the book “Harry Potter” to my shopping basket

Then my shopping basket should contain 1 copy of “Harry Potter”

22

As a shop visitorI want to collect books in my shopping basketso that I can purchase multiple books at once.

Books can be added to the shopping basket

Examples in Gherkin

Given my shopping basket contains 1 copy of “Harry Potter”

When I add the book “Harry Potter” to my shopping basket

Then my shopping basket should contain 2 copies of “Harry Potter”

The same book can be added multiple times to the shopping basket

23

The same book can be added multiple times to the shopping basket

Structure of examples

Given my shopping basket contains 1 copy of “Harry Potter”

When I add the book “Harry Potter” to my shopping basket

Then my shopping basket should contain 2 copies of “Harry Potter”

Title: Describes intention/abstract acceptance criterion

Arrange: Context, initial state of the system

Act: Execution of the feature

Assert: Assertion of observable behaviour

And I should see the warning: “Book already existed in basket”

Triple-Aconstraint“Checks”

Chainingup steps

24

Life time of

examples

25

Purpose of the examples

• Shared understanding:acceptance criteria

•Documentation:system details

• Regression-tests:violated assumptions

26

Continuous validation with automation

Given my shopping basket contains 1 copy of “Harry Potter”

When I add the book “Harry Potter” to my shopping basket

Then my shopping basket should contain 2 copies of “Harry Potter”

System

„Step Definitions“ are binding individual stepsto an automatable interface of the application.

Automatableinterface

UIAutomation

Automation does not necessarily have to bind to the UI.

Automatability of system is supported/evolving with development.

27

Demo

http://www.specflow.org

Gherkin automation for .NET• Visual Studio plugin (VS-Gallery)•NuGet Package

32

Livingdocumentation

33

Living documentation

Drill into Details(Gherkin scenarios)

Overview(Story Map)

42

Summary

43

Conclusions

• Examples• Illustrate abstract requirements• Trigger new questions: collaborative discovery• Shared understanding

• Living documentation• Automatically validated examples• Business readable regression tests• Reliable source of truth

• Gherkin based automated examples• Open source, cross-platform• Requirement details versioned with source code• Similar tools: Fit/Fitnesse, Robot Framework, JBehave

44

Gherkin based automation tools

www.cukes.info

www.behat.org

Ruby, Java, JavaScript, C++

www.specflow.org

.NET, Mono, Silverlight, WP7

PHP

45

Books

Gojko AdzicBridiging theCommunication Gap

Gojko AdzicSpecification byExample

Elisabeth HendricksonExplore IT!

46

47 Christian Hassa: ch@techtalk.ch - @chrishassa