{{announcement.body}}
{{announcement.title}}

Realizing User Story With Storyboard

DZone 's Guide to

Realizing User Story With Storyboard

The author proposes an interactive storyboard technique for analyzing and designing user stories.

· Agile Zone ·
Free Resource

people storyboarding in a conference room

Learn more about the proper way to use storyboards!

In this article, I'm going to propose to use an interactive storyboard technique for analyzing and designing user stories.

How do you write test scenarios for automated acceptance tests? In agile development, user story and acceptance criteria feature level is given by the customer, and we start analyzing the story and create test scenarios.

You may also like: Best Practices to Succeed With User Stories

user story chart

Scenario-based acceptance criteria, which are described in Given-When-Then format, look like a test scenario already. Hence, we may misread it executable which can be converted into an executable test script. Actually, at this moment, the customer has just captured what they need based on business values. Hence, they only considered whether or not the story is needed for their business compared to alternative options.

On the other hand, test scenarios are expected to be detailed at the coding level which each step represents a user operation or system behavior. In this phase, we analyze the story and design classes and screens with logical thinking, which is a different approach from the one to define user story and acceptance criteria.

requirements gathering and analysis and design

This article proposes to use an interactive storyboard technique for analyzing and designing stories. And I introduce “storydoc” as a storyboard tool to experience screen flow and generate test scenarios and related documents from stories. Below shows storyboard HTML and storydoc document generated from the HTML:

storyboard HTML

Product Search Story

In this article, I will use a Product Search story as a sample user story. The story defines a feature that the user searches a product by its model name. On a search form, the user enters a model name and clicks the Search button. Then the system opens a product detail page with showing the product information.

The above feature can be captured as the following story and acceptance criteria:

C




x


 
1
As a website user,
2
I want to search products by a model name
3
so that I can find the information on the product.



C




xxxxxxxxxx
1


 
1
Given I open the website
2
When I search by model name
3
Then the system shows the product information



The acceptance criteria look like an executable test scenario already, but it is not. I have created test scenarios, as shown below, based on the given story:

C




xxxxxxxxxx
1
16


 
1
Main Scenario:
2
       Given I open the website
3
       When I enter an exact model name
4
       Then the system shows the product information
5
 
          
6
Alternative Scenario:
7
       Given I open the website
8
       When I enter a partial model name
9
       Then the system shows a list of products
10
       When I select a product
11
       Then the system shows the product information
12
 
          
13
Exception Scenario:
14
       Given I open the website
15
       When I search with an empty keyword
16
       Then the system shows an error message



In the real world, we could find more scenarios, but I only trawled typical alternative and exception cases in addition to the main scenario to simplify the sample code.

Differences Between Acceptance Criteria and Test Scenarios

To know what has to be done in the analysis and design process, it is a good idea to see what has been changed and added in the sample test scenarios compared to the given acceptance criteria.

At first, we see that two scenarios (Alternative and Exception scenarios) are newly added in test scenarios. The alternative scenario shows another course that the system finds multiple products. The exception scenario shows an error course that the user enters an invalid keyword.

Next, we can see small differences even in the main scenario. Acceptance criteria say, “When I search by model name”, while test scenario says, “When I enter an exact model name”. This is caused by the alternative scenario that the system returns multiple products. To distinguish from it, we have to clearly say “an exact model name” instead. Also, when we are writing the test scenario, we have already clarified the screen flow and design.

We know there are an input field and Search button on the page. That is why I changed to use the expression “enter”, which is tightly related to the user’s action, instead of “search”. In general, we often see more expressions related to HTML elements, such as “enter a keyword”, “click a button” in test scenarios rather than acceptance criteria due to the reason. Here are the things added in test scenarios:

  • Changed to use expressions based on User Interface.
  • Added alternative scenarios.
  • Added exception scenarios (error courses).

From the above changes, we can see that the following activities will be done in the analysis and design process:

  • Clarify screen flow and HTML elements on each screen.
  • Find possible alternative courses.

Storyboarding

Now we know what to do for realizing a story, which is to find screens and alternative scenarios. Although you can draw screen images with presentation software like PowerPoint, I here propose to use a storydoc tool to analyze stories.

You simply need to create HTML files and define screens and actions with using <screen> and <action> tags. The search form page can be represented as shown below:

HTML




xxxxxxxxxx
1


 
1
<screen>
2
  <input> 
3
  <button>Search</button>
4
</screen>
5
 
          
6
<action name="I search by model name"
7
        link="ProductDetail.html"/>



In the storyboard, the screen has to be as simple as possible, which is called “conceptual screen”. The conceptual screen is represented with action related HTML tags only. In this page, user needs a <input> and a <button> to enter a model name and submit. That is why only two tags are described in the <screen> tag.

Once you have created HTML, you can experience the screen flow with your browser. This is called storyboarding. From the URL below, you can storyboard the story customer-defined:

https://story-doc.github.io/SearchInitialStoryboard/index.html

Also, the link below shows the HTML source codes:

https://github.com/story-doc/js/tree/master/samples/SearchInitialStoryboard

Besides storyboarding, the storydoc tool can generate test scenarios and related documents from the HTML. Run the command below from a command line:

C




xxxxxxxxxx
1


 
1
C:> java -jar storydoc.jar index.html



It generates a storydoc.html in the same folder. The HTML can be seen from the URL below:

https://story-doc.github.io/SearchInitialStoryboard/storydoc.html

As you can see it, the storydoc HTML contains the following sections:

  • Use Case Diagram of the user story.
  • User Story Description (Main Scenario).
  • Navigation Map (State Diagram).
  • Test Scenarios.


C




xxxxxxxxxx
1


 
1
Story: [US01] Product Search
2
 
          
3
Main Scenario:
4
       Given I open the website
5
  M-1. When I search by model name
6
       Then the system shows the product information



Although some additional lines and labels are added in the above test scenario, it is essentially the same as the acceptance criteria this moment.

Find Alternative and Exception scenarios

By walking through the story with conceptual screens and actions on the storyboard, we will get a better understanding of how the story works, and it gives us more ideas about what actions else are possible to be taken. For example, the model name entered may not be a full name, and it results to get multiple products. Another example is that the user will get an error due to entering an invalid model name, e.g. an empty keyword.

For the newly found actions, you have to define as alternative (or exception) scenarios so that your application can handle all possible courses. We here found two new actions on Search Form:

  • I enter a partial model name.
  • I search with an empty keyword.

Also, to express the difference from the partial model name case, I changed the original action name “I search by model name” to

  • I enter an exact model name.

Now the three actions are defined in the Search Form page as shown below:

The above figure also contains two screens newly found:

  • Search Results page to display a list of products and
  • Error page to display an error message

I have revised storyboard with the new actions and screens:

https://story-doc.github.io/SearchStoryboard/index.html

Also, the link below shows the HTML source codes:

https://github.com/story-doc/js/tree/master/samples/SearchStoryboard

Run the storydoc tool again to re-generate storydoc HTML:

C




xxxxxxxxxx
1


 
1
C:> java -jar storydoc.jar index.html



The revised HTML can be seen from the URL below:

https://story-doc.github.io/SearchStoryboard/storydoc.html

In the document, you will see updated user story description, navigation map and test scenarios with the new actions and screens. For example, alternative and exception scenarios have been added in the navigation map as shown below:

You also see the alternative and exception scenarios in the generated test scenarios:

C




xxxxxxxxxx
1
20


 
1
Story: [US01] Product Search
2
 
          
3
Main Scenario:
4
       Given I open the website
5
  M-1. When I enter an exact model name
6
       Then the system shows the product information
7
 
          
8
Alternative Scenario 1:
9
       Given I open the website
10
  A1-1. When I enter a partial model name
11
       Then the system shows a list of products
12
  A1-2. When I select a product
13
       Then the system shows the product information
14
 
          
15
Exception Scenario 1:
16
       Given I open the website
17
  E1-1. When I search with an empty keyword
18
       Then the system shows an error message
19
  E1-2. When I go back to the search form
20
 #E1-3. Go back to M-1



This is the one we wanted to generate, as a goal of analysis and design process, from the customer’s story.

Conclusion

User stories at feature level are defined by focusing on core requirements. Hence, user interface and alternative courses are not considered yet. System analysts and developers need to analyze the stories and design in detail using a different approach from the defining stories.

Storyboarding is a recommended technique to analyze and design stories. By experiencing the screen flow, you will easily find more alternative scenarios. Also, by using the tool, your modifications to the documentation can be minimized whenever you refine the stories.


Further Reading

What Are User Stories, and Who Should Write Them?

The Magic of Small User Stories

What Is the Right Size for a User Story?

Topics:
agile design ,user story ,acceptance criteria ,test scenario ,agile

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}