“Specification by Example” or how to have updated documentation

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) {

    @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.


Way to QA

Way to QA

Nowadays a lot of people believe that QA (tester, test engineer) – the lightest engineering position in the IT sector. A few years ago on this post really was quite easy to get. It was enough to know English at a level below the average, to understand the PC at the level of average user .. well, actually that’s all. Of course, there were projects where the requirements were much higher, depending on the project. Over the years, the IT market is overflowed by “engineers” who can communicate in English at the secondary level and know how to go to “regedit”. And now to become on the position QA / QC – need to know much more and need to expand their horizon of knowledge.

         So, what you need to know / be able to become a test engineer at the present time. 

  • Foreign languages. Often test engineers need to serve as project manager. As you know, outsourcing it’s mainly foreign customers, who will be very happy if somebody from the teams which will serve their request, be able to communicate in their own language. Of course, English is №1 list of required languages, as it is the language of all meetings, discussions, etc.
  • Knowledge of basic (but preferably all) concepts ISTQB. Candidate for the position of QA Engineer obliged to understand such concepts as Test Design, Test Case Design Technique, Test Plan, Test Case, Test Coverage, QA, QC, Quality, Bug and all artifacts that relate Test Case or Bug. The candidate should also understand why knowledge of these concepts are important to the project. After QA – this is the man on the project, who decides whether application is ready to go to the end user or not.
  • It is necessary knowledge and skills то use systems such as Test Tracking System, Bug Tracking System (this is not a specific application names. Examples of these programs can be Jira, TestLink, Bugzilla, HP Quality center, etc.)
  • Not do without the knowledge management operating systems. And not only the family of Windows, but * NIX systems too. Test engineer will need to customize his own test environment not only once. As a rule, none of the team does not want to do it, so expect a big help is not necessary. Better to be able to adjust everything.
  • Recently on QA engineers also “voluntarily requested” basic knowledge in automation testing as simple cover car test application, rather than hire 100500 testers. And this, of course, need to have a basic concept in OOP and additional platforms that will be used for testing. Described in more detail in another article here.
  • Also test engineer is required to be able to analyze problem areas found in the application and in the software development process.
  • And most importantly – a desire to be a test engineer not because of good salary but because the work is really like. Because if testers do not like his work, then do not look for high quality software.

So, here described such a requirement for genuine Software Test Engineer, whose companies wish to employ and do not want to let go. To acquire such knowledge – takes about 3-4 months very hard work on yourself.
Thanks to all who read this article. Stay tuned, write comments or private mails, I will try to answer all.