Write better specifications with testing

Posted On October 1, 2019

Introduction

A specification written by the customer – often ends as incomplete, fragmented and with parts that contradict each other – makes it difficult to build for the engineers.

A specification written by the engineer – often ends with a focus on details than on needs, and to difficult for the business to read/understand.

So how to do it? By using Given, When, Then!

Understandable

Lego and IKEA have some of the best manuals/documentation, because they write them as test cases using “Given, When, Then”, mentioned in Write better documentation with testing

Documentation is about:

• What givens do I need to have
• and what when’s do I need to do
• to achieve my then’s (goals)”

A specification is almost the same, but with a different focus:

1. How do I build the given’s,
2. so the users can do the when’s 
3. to achieve their then’s (goals)

We think of specification and documentation as two different groups of documents, but they can technically be the same documents – if they are written as test cases.

Focus on needs than details

It is easy to forget the needs when the attention is on the details (read my 10 facts about details). In testing, there is something called a logical and physical test case, to split the design from the implementation.

Physical test case (operational steps)

A physical test case describes all the operational steps (given, when, then) to complete the test:

Given I open https://...com/webshop
And accept the "cookies information"
When I click the tab "tickets"
And I click button "Buy tickets"
And select dropdown "customer type" option "adult"
And click the "Continue" button
And move the slider to 7 zones
And click the "Continue" button
And rejects the special offer window
Then I should see the price of 18 €

The test case drowns in the operational details, and it becomes difficult to read, what the test case is actually testing.

Logical test case (business process)

A logical test case describes the business behavior (given, when, then) to only focus on what the test is about, and not on the implementation itself:

Given I am buying a ticket on the web shop
When buying a <child / adult / student / retired> ticket
And to travel <2 - 8> zones
Then the price should be <price> €

The logical test case describes the business rules (behavior), is easy to understand, and can be reused whenever a new version of the product needs to be implemented.

Logical test cases make it easier for the customer and supplier to understand each other.

Defragmented

We all know the situation when a developer and a customer agree verbally on something, and it gets implemented. Nobody wrote it down, so it will never end up in the specification and never in the documentation.

In Behavior Driven Development (BDD), the logical test case is written before the implementation. It might seem counter-intuitive, for how can we test something that doesn’t exist?

Logical test cases are our assumption of what the product should do, and can be used to measure the status of the implementation, and later be used as documentation.

Without contradictions

Sometimes two business processes can contradict each other and nobody will notice.

1. When the first process is implemented, then its test case will pass.
2. When the second process is implemented, then its test case will pass, but also make the first test case fail.
3. Fixing the first process, so its test case doesn’t fail anymore, will make the second test case fail.
4. Fixing the second process, so its test case doesn’t fail anymore, will make the first test case fail.
5. etc..

A specification written with test cases is executable and can catch contradictions in business processes.

Completeness

The customer can put the logical test cases in their end-to-end business flows, to see if every critical behavior is mapped. Should only be applied for critical behavior and not every behavior).

Missed or misunderstood business behaviors can always be added or updated on a later stage as a change request.

The specification will not be complete to begin with, but will become more and more complete over time.

It can later be used as documentation and reused as a specification when a new version of the product needs to be implemented.