Over a million developers have joined DZone.

Reporting bugs in a precise and readable way using Fail-Stories

DZone 's Guide to

Reporting bugs in a precise and readable way using Fail-Stories

· Agile Zone ·
Free Resource

UserStories and Scenarios used in agile methodologies are an excellent and easy-to-use way to gather requirements and to define the expected behaviour of the system in a precise and readable manner.

But gathering requirements is only one side of the medal. During an applications life cycle a significant proportion of system change requests will be triggered by bug reports. And this leads to the question, why not to use a similar method for the recording of bugs?

Let's have a look on an example (with which I was more or less confronted in practice):

A classic bug reports may look like this:

Since the last update scrolling with the mouse wheel in tables is not working any more. It has to be fixed as soon as possible, because our customer is suffering greatly from this problem.

The problem is urgent and seems to be clear. No further questions ... let us fix the bug. No further questions ... really?

If we take a closer look, we will see that this bug report is missing some important information. To name just a few:

  • first of all, this bug report tells us what function is broken, but nothing about the actual consequences for our customer
  • it doesn't tells us in which situations the broken function is used
  • and it doesn't tells us who is using this function

To make it better, I would like to suggest a format that I call 'FailStory' and that might look something like this:

In order to look for special entries in a large table efficiently
As a normal user
I want to use the mouse wheel in all tables for scrolling

But since the last update it behaves as follows:

	Given, for example, more than 10 orders in the order pool

	When I open the order pools overview table

	Then I'm not able to scroll with the mouse wheel in the table
	And I'm forced to use the scrollbar to find the order I'm looking for

What is inefficient and not very ergonomic for me

The first part of the FailStory is a UserStory that tells us the 'what', the 'who' and the 'why' of the broken function. The second part describes at least one real scenario that is in contradiction to the UserStory. Obviously, the FailStory above still has some weaknesses. For example, it was not possible to describe the user role exactly. But compared to the classic bug report it represents a clear improvement.

In detail the format of a FailStory looks like this:

	In order to <achieve some value>
	As a <type of user>
	I want <some functionality>

	But it behaves as follows:

		Given <some context>
		When <some action>
		Then <some behaviour/result>

		What <some consequences>


Using a FailStory allows us to record bugs in the same precise and readable way we are gathering requirements. For this we don't need to introduce any new concepts, we just have to combine familiar concepts. The UserStory leads us to understand the users perspective and gives us information about the context. The Scenario allows us to reproduce the bug, makes it testable and helps us to avoid regression (ideally, we automate the Test-Scenario).

Perhaps we have to attach more information (OS, Browser etc.) to the FailStory to understand the problem in its entirety, but we should not start with these details, as we are often used to.


Opinions expressed by DZone contributors are their own.

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

{{ parent.tldr }}

{{ parent.urlSource.name }}