Specification By Example

If the company you work for is like mine, your specifications are a word document produced by someone who barely knows the technology, or by someone who knows the technology and not the business. Also, after a time, the specifications become out of date. If there are samples within the specification, these become out of date as well.

So, how do you know if a specification is out of date? Well, usually you have to manually check these, which usually does not happen.

Another problem I have come across where specifications are done through word documents is that the examples given are inaccurate. This can make things difficult for the developer to know what the requirement is. They then “guess” an interpret the specification in their own way.

Written specifications are up for interpretation.

For example, I tried Gojko’s Star experiment with my team. As expected, everyone in the team answered 10. When I asked “Why not 5?” an arguement ensured, but a few got the point. “Specifications can be subjective!”

So how do you get away from the subjectiveness? Well, there are a lot of different practices at the moment, Test Driven Development (TDD), Behaviour Driven Development (BDD), and Acceptance Test Driven Development (ATDD). There are probably a few more that I have left out, but all these methods have something in common. They document your specification by using tests. Tests are verifiable and measurable. If a test fails, the specification is not met. (You can get into the case that the test is wrong in the first place, but that is for a later discussion).

The documentation of these tests can also take different forms. For example with TDD, tests are specified using traditional means such as using JUnit for Java. These tests/specifications are tightly coupled to the code they are testing/designing. This is fine if the audience such as other developers are the target, but for business analysts, project managers and other management are the audience, they may get a little bamboozled.

This is where ATDD and BDD come in. These methodologies use natural language, be it English or any other native language to describe the the specification. Bridging code known as a fixture then takes these specifications, takes the examples written within the spec and executes tests.

Screen Shot 2015-08-28 at 9.20.07 am

This methodology provides two way verification. You can check if your system meets the specification. You can also see if the specification accurately describes the system.

Any changes that create a failing test,  immediately lets you know if the system has a changed or the specification has changed.

So, how are these types of specifications written?

There are a number of methods, but the major types are…

  • Gerkin based, these are used by products such as JBehave, Cubumber, EasyB etc. These use the “Given, When, Then” terminology used to describe user stories in text files and then have a bridge to convert the scenarios to tests.
  • Table Based, these are used by Fitnesse and Concordion. Fitnesse uses a wiki to write the specification using 2 types of languages. The older FIT and the newer SLIM. Concordion uses HTML and the <span> tag to mark entries to be used by the fixtures.

I haven’t had a chance yet to play with the Gerkin based products as yet. But I have done a couple of POCs with Fitnesse and Concordion.

Each had their own advantages and disadvantages, but overall my impression was that these provided a better means to get better specifications than a simple word document.


Short one this time…

I was looking at getting myself a linux box where I could try playing around with Docker, when I wondered if its possible to get an online virtual linux box without a credit card.

That is when I found http://www.koding.com.

It gives you a free virtual machine, no credit card required. The only drawback is that the machine only remains on while you are logged in.

Great for learning, not so great for running, but then again, they do have plans where you can get a running machine.


Koding.com has a number of guides to get you started. These can be found at http://learn.koding.com/guides/

Happy Playing!


DFDL is a modelling language currently under development to describe the format of non-xml data. For example –

  • Delimited (CSV)
  • Fixed width
  • Binary etc

DFDL uses XML schema notation to describe data formats. In order to do this, it uses a subset of the xml schema constructs. When implemented, it will provide a means to describe non-xml data using well formatted, valid XML.

Take note, it describes data that is NOT xml.

Source: https://redmine.ogf.org/dmsf_files/8110?download=12653


5 digit house number 10 Character street 10 character suburb 3 character state

Similarly for CSV data

Where the data is comma separated

Sources: http://www.ogf.org/dfdl/


It is still early days. There are a couple of implementations available, mainly open source, but the idea is promising. Hopefully

Daffodil – Open Source

Defuddle – Open Source

  • written iin java
  • early stages or abandoned.
  • Last updated 2/4/22013


IBM – IBM Integration Bus (formerly IBM Websphere Message Broker)

  • Paid (But a free developers edition is available)

Test Data Builder Pattern

The test data builder pattern is a pattern as the name implies, is to build test data. It works on the principle of setting the details in teh constructor and then have a method that builds (returns) the built object. Default values are set in the constructor and the methods are then used to override those defaults.

As you can see, the code is a little different to your usual getter and setter code. By using the with methods. The with method return the current object, so it allows you to chain with statements together.

For example:

Also, by indenting the statement over multiple lines, it makes it more readable. It also gives the advantage that you can comment out certain with lines to debug or change the data without affecting the execution.


As a first post to this blog (See the about page for links to my previous blogs) I would like to go though my journey of Documentation technologies that I have tried.

I have worked in the IT sector for many years and it seems that the default method of doing documentation has always been Microsoft Word documents, which I’m sure a lot of you and myself included are still using today. This is because Businesses tend to use this as the default method of documenting anything.

So what is wrong with Word documents. Not a lot really, it does what it is suppose to do. Which is replicate the printed page on the screen.

To me, this seemed like an archaic method of doing documentation, there must be other means. This is when I came across Tiddly Wiki. This was about 10 years ago, it seemed very easy to use, I started playing around with it, but I could not use it because business wants Word Documents. So I dropped it. I have just started using Tiddly Wiki again for my personal notes. Adding Dropbox and I have my personal notes everywhere I go.

A little while later, I came across DocBook. DocBook is an documentation format in XML. I tried writing a post back in 2011, Message Tracking. I liked the idea of DocBook. You can write your content in the XML and use css to change the format. You can then output the document as either HTML, PDF, word and most likely several other formats. I haven’t really touched on it since, but I do like the idea. It means that your documentation format is decoupled from the format. Maybe one of these days I’ll look into it again.

The next format I started looking at which is more common is the Wiki. I think the humble wiki is probably the best method to do your documentation. There are many open source wiki’s available on different platforms, but the one I like most is from a company in my home country, Atlassians Confluence. Everyone can collaborate on a wiki. No need to email documents around (Yes, I know you can use something like SVN to keep the store documents in a common area, but it is still difficult to navigate and search.)

I had been searching for a better way to do Specification documents. I was trying to find a template on the Internet. I didn’t quite like the way that our company did them. There seemed to be too much fluff and not enough content. This is when I got exposure to the whole Specification by example movement. From this, I came across Fitnesse and Concordion. These two products allow you to create executable documents. Documents that can be used to test your applications that you have developed. Fitnesse uses a wiki to hold the documentation portion and Concordion uses HTML pages. These seem the best methods I have come across to document your systems. They are always up to date as they are part of the testing process. The only downside I have come across with these products is… they don’t use Word, so it makes it hard for business types to accept. Oh well. I have done some proof of concepts with both Fitnesse and Concordion. At some point I’ll put up a tutorial on how to use them.

The final type of documentation technology I would like to talk about isMarkdown. Markdown is a text format that can be rendered with the right software to HTML. I like it because it is easy to read as a text file, but can also be rendered to HTML. For example, this blog post is being written in Markdown. As a proof of concept I have used Markdown for comments in SoftwareAG’s WebMethods. I then wrote a python script that takes those comments and renders it to HTML. With extensions, which included adding the js-sequence-diagram.js library, I was able to add sequence diagrams to the output.

That is it for the first post. I have lots of topics I would like to cover, unfortunately I don’t have a lot of time. Hopefully I’ll be able to keep up the content.

Thoughts, Tutorials and Learnings specifically with regards to Agile, DevOps and SOA/EAI