Asier's thoughts

Blogging about software development

Leave a comment

Specification by example

Last week me and my colleague  Jorge went to Agilia conference in Brno, Czech Republic. The conference was on average good, but what we really enjoyed was the Specification by Example workshop we attended after the conference.

It was a 2-days course given by the great Gojko Adzic. He went through it with explanations of what Specification by Example is, how we should apply it at work and which are the benefits of it. We alternated that with several team exercises and many coffee breaks 🙂 We also learnt how to write good and bad specs. At the end of it he told us about the real software quality and even gave us an introduction to Impact mapping!


So what’s Specification by example?

Specification by example is a technique which brings together the requirements gathering and QA testing processes in the software development cycle. It is also knows as ATDD or even BDD, but I don’t really agree with the last terminology..

Basically it is a way of writing specifications collaboratively  which are then converted to automated  acceptance tests.

How does it work?

Testers, developers and business people will get together in one room and will write specifications for the new features that they want to implement. In order to do that they will get separated into different teams, get a white board each and write examples of how the system should be working after the new features have been implemented. Once all the teams are done they will get together and compare the examples, look for differences and agree in some common ones.

Spec in Gherkin format

Spec in Gherkin format

After the team workshop is over, testers will take those examples and automate them with a tool like cucumber or fitness. Developers will implement the features and will know they are finished when these tests pass. These tests will run against the actual system frequently. If tests got automated before the development work starts this is know as Acceptance Test Driven Development, the same as TDD but from a ‘higher’ point of view 🙂

It is not really necessary to do the whole team workshop, but it is the most effective way. However, sometimes it won’t be easy to get all those people at the same room and just bringing together one tester, one developer and somebody from business will do it – the three amigos way. At other occasions the team will be distributed, one person writing the spec and the another one or two reviewing it may work.

Which are the benefits?

The two main benefits brought by specification by example are having a single source of truth and getting a quicker feedback.

The examples are requirements and also tests. What is written in the requirements is automated as tests and run against the actual system. If a requirement changes the test will change and the system will have to, if we add a new requirement there will be a new test and the system will have to change to make it pass. Basically, what is specified in the requirements it is what the system does! No more requirements document and qa test that differ. The examples are the single source and we know they say the truth because they are automated and run against the system frequently. This is known as the Living documentation.

The good thing of bringing together business people, developers and testers is that we will spot things much earlier in the process. Instead of waiting to solve misunderstandings once the development work has been finished we can bring forward this feedback to the point were requirements are gathered. Handing over documents from Business Analyst to developers and then to testers is not the good way to do it, many times things will get lost and won’t be spotted till the testing phase or sometimes even production! Put everybody together before the development work starts and many communication issues will get solved in no time, rather than waiting till the end of the iteration.

Another key benefit of the workshops is that they will bring a better understanding of the actual system to everybody and will help modelling it. When writing the specs collaboratively everybody will get to a common language which then can be used when developing the system, documenting it or at any further discussions later on so there are no terminology misunderstandings – this is known as the Ubiquitous Language.


I kind of knew about specification by example before the course and we were already doing in it a certain way at work with the three amigos way, but not properly. I hadn’t heard about the team workshop and I find it quite interesting to be honest. I would like to try it. I just need to convince business people 🙂

As a feedback about the course I would say it was awesome! It was presented in a quite entertaining way. Challenging and fun team exercises in between engaging talks from Gojko with real life cases from his work as consultant. At the end we got a about 10-page document that summarizes everything. I am planning to get the book and learn more about it.

Maybe the one about Impact mapping too.. sounds quite interesting!



1 Comment

BDD is not automating acceptant tests

Over the years I have met many who think erroneously that BDD means writing acceptance test and then automating them with a tool like cucumber.

BDD or Behaviour Driver Development was brought by Dan North as a layer on top of TDD to emphasize that we should focus on behaviour when writing our tests.

There are two types of frameworks to do so. There are the ones based on  Gherkin syntax like JBehave, Cucumber or Specflow . And there are the ones based on context/specification syntax like RSpec, NSpec or MSpec.

Here two examples of both syntax:


Scenario 1: Account is in credit
Given the account is in credit
And the card is valid
And the dispenser contains cash
When the customer requests cash
Then ensure the account is debited
And ensure cash is dispensed
And ensure the card is returned

Context/Specifcation – Rspec

describe Bowling, "#score" do
  it "returns 0 for all gutter game" do
    bowling =
    20.times { bowling.hit(0) }
    bowling.score.should eq(0)

The point of these frameworks is too think on behaviour when writing a test case instead of just testing a method with certain inputs and expecting some other outputs.

Usually, the ones based on gherkin are used to write acceptance tests and the context/specification ones for the unit test level. Somehow, the first ones with cucumber have become more popular and when you talk to anybody about BDD they will think about Given-Then-When, cucumber and acceptance testing. But this is wrong!

BDD is not just for acceptance testing, we already had ATDD for our acceptance tests. BDD is a layer on top of both TDD and ATDD. And it’s intend is to focus on BEHAVIOUR so we can do good TDD. Don’t forget xSpec frameworks, they are also BDD frameworks! Don’t think BDD = ATDD or acceptance tests!

+ Info and sources:

There are a couple of good blog post on stack over flow talking about this matter:

And recently I watched the talk TDD, where did it all go wrong by Ian Cooper where he talks about the problem with TDD and that we should focus more on behaviour. I recommend to watch in it.