“Specification by Example” or how to have updated documentation

Hello!
In this article I will try to explain some trick how to work with updated documentation. I think that almost on all the project (which is working by Waterfall) happens the situation, that specification is not updated according to functionality. That test cases are obsolete. And when it’s happening – need to review all the documentation, create new one. And it takes a lot of time.
So, how to avoid this?
Start to use approach “Specification by Example (SbE)”. What is it? (From Wikipedia) Specification by example (SBE) is a collaborative approach to defining requirements and business-oriented functional tests for software products based on capturing and illustrating requirements using realistic examples instead of abstract statements. It is applied in the context of agile software development methods, in particular behavior-driven development. This approach is particularly successful for managing requirements and functional tests on large-scale projects of significant domain and organisational complexity.

Specification by example is also known as example-driven development, executable requirements, acceptance test-driven development (ATDD or A-TDD), Agile Acceptance Testing.

Successful application of Specification by example on large scale projects requires frequent validation of software functionality against a large set of examples (tests). In practice, this requires tests based on examples to be automated. A common approach is to automate the tests but keep examples in a form readable and accessible to non-technical and technical team members, keeping the examples as a single source of truth. This process is supported by a class of test automation tools which work with tests divided into two aspects – the specification and the automation layer. The specification of a test which is often in a plain text or HTML form and contains the examples and auxiliary descriptions. The automation layer connects the example to a software system under test.

The most known framework for SbE are:

• Concordion
• Cucumber
• FitNesse
• JBehave

These tools allow to collect all the examples, test steps, stories in txt or html files. After creation of examples engineer can use these files in code. What the benefits?

• Test cases, stories are always up to date
• Non-technical employees are able to read stories and tests. And if need – do the changes
• All the stories are independent
• Test engineer and business analytics could easy collaborate in creation of SbE and test cases.

How it looks like on practice?
Next examples are for Jbehave.

1. Story file with extension *.story

Scenario:  trader is alerted above threshold

Given a stock of symbol STK1 and a threshold of 10.0

When the stock is traded at 11.0

Then the alert status should be ON

2. Java class for implementation of this story:

public class TraderSteps {

    private Stock stock;

    @Given("a stock of symbol $symbol and a threshold of $threshold")

    public void aStock(String symbol, double threshold) {

        stock = new Stock(symbol, threshold);

    }

    @When("the stock is traded at $price")

    public void theStockIsTradedAt(double price) {

        stock.tradeAt(price);

    }

    @Then("the alert status should be $status")

    public void theAlertStatusShouldBe(String status) {

        ensureThat(stock.getStatus().name(), equalTo(status));

    }

 }

If change something in story file – need to change also the same in Java class to avoid errors.

I recommend to use this approach if You want to avoid any problems with not-updated documentation.

In my next article I will show how to make automation framework for Web UI testing with using Selenium, JUnit, Concordion and Maven.

Thanks for reading this article.

Cheers.