Concordion, like Fitnesse is another Specification By Example tool which I like because of its free form structure.

Concordion uses HTML as its syntax to write specifications. With the HTML, it uses the <span> tag to specify commands. Just like Fitnesse, fixtures are required to interpret the specification and execute the tests. Tests are written in Java using ether JUnit or TestNG. Other languages are supported, but I haven’t tried them.

The basic functions of Concordion are:

Assert Equals : To assert whether a value is equal and return true or false.

Set : Sets a variables value.

Execute : Execute an instruction with a result. The result can be void.

Execute On A Table : Executes the same behaviour across a row on a table. This is good for verifying multiple input tests.

Verify Rows : Allows you to verify the results when multiple values are returned. For example when returning the results form a database query.

When you run a test, Concordion returns HTML which has been marked up with the test results.

Advantages

The advantages of using Concordion over Word documents (and even in some cases fitnesse) are

• It uses HTML. Be careful though using WYSIWYG HTML editors. The HTML generated may be complex and it might be easier to just hand code the HTML yourself.
• Concordion is simple to understand and implement.
• Just like Fitnesse, it is easy to see when your document is up to date and that the examples are correct.
• Integrates well with Jenkins. I had no troubles incorporating within Jenkins and just used the HTML report plugin to incorporate the results.

Disadvantages

Again, like Fitnesse, there are a number of disadvantages of using Concordion over a Word Document.

• Requires coding compared to a word document, but then again, the purpose of Concordion is different.
• There is no version control built in, but saying that, you can tie the HTML with your source code and check in at the same location. That is what I have done.
• Again, just like HTML (Well, it is actually…) images and attachments need to be stored in separate files.

I like Concordion for its simplicity. I haven’t tried Concordion with message formats such as XML, but I’m assuming that the same caveat with Fitnesse where you need to decode the XML still applies.

Saying that, I do have some ideas about using the test data builder pattern to generate my XML message based on a table of inputs.

Maybe one day I’ll get around to doing it.

Let me know in the comments which you prefer, Concordion or Fitnesse and especially if you are using these in any SOA/Integration space.

When I was much younger, I use to play the guitar. For my first guitar, I had bought it at an auction at a market. The pickups didn’t work, the nut was missing, no strings, but I was determined to learn. So I went to the nearest guitar shop that did repairs and took it to them.

Several parts later, I had a working monster, and it was a monster, but it got me started.

Not long after, I got a new guitar. Not much better, it was the cheapest one I could get. It had only 21 frets, and the amp I got was a cheap and nasty from Tandy at the time. What do you expect, I was a poor student at the time. That was when I really learned to play, and so I practiced every chance I got.

One thing I heard or read somewhere at the time that has stuck in my mind is that having a very expensive guitar like the one your favourite guitarist plays does not make a bad guitarist good, they will sound bad regardless, but a great guitarist can make a box and strings sound great and a good guitar sound amazing.

So where am I getting at, well… In my experience, companies go and fork out hundreds of thousands to even millions of dollars for tools or frameworks to help with their corporate development thinking it will save them lots of money, make things easier and or get them there sooner and a lot of the time, these projects generally fail, cost a lot more money, take forever to get off the ground as they wait for approval to spend the funds or end up not being what was envisioned in the first place.

In these circumstances, the time to practice, the time to learn the fundamentals of what this new product is meant to make easier, the time to iterate over your procedures to learn what is the best way to implement, the time to become a good player has not been put in.

My advice is to start learning the fundamentals today. Use open source software (it may surprise you), build your own stuff, cobble together scripts, read, learn, practice. Just workout your own sound. Learn to play with that box and strings and make it sound good so that when you get your new shiny tool, framework etc – you will just sound amazing!

As mentioned in my previous post, Fitnesse is a product used to describe specifications using the Acceptance Test Driven Devlopment or Behaviour Driven Development methodology.

Fitnesse was created by Robert C. Martin (Uncle Bob) about 10 years ago and originally was based on the FIT language created by Ward Cunningham.

Fitnesse uses a wiki to write your specifications and fixtures written in multiple languages, but originally in Java.

Fit provides the ability to create :

Column fixtures : Where the rows represent inputs and expected outputs

Rows Fixtures : Testing queries that return an exact set of values (Ordered independantly)

Action Fixture : Allows you to write a script that emulates a series of events.

Comment Tables : Allows tabular comments that are not executed as tests.

Slim, the other language used by Fitnesse provides a lot more functionality.

Decision Table : Supplies the inputs and outputs for decisions.

Dynamic Decision Table : Same as the decision table, but passes column headers as parameters for the fixture.

Query Table : Supplies the results of the query.

Subset Query Table : Supplies a subset of the results.

Ordered Query Table : Supplies the expected result of a query in a particular order.

Script Table : Allows scripting a series of actions and checks.

Table Table : Allows you to write a fixture that arbitrarily executes as specified.

Import : Add path to the fixture search path.

Comment : Add a comment

Scenario Table : A table that can be called from other tables.

Library Table : A Table that installs fixtures available to all test pages.

Define Table Type : A helper table that defines the default table for named fixtures.

Advantages

There are a number of advantages of using Fitness over using word for your specification documentation. These include…

• Built in Version Control. You do not need to add your specifications to a version control system. Adding is supported but not required.
• Its easy to see when your document is up to date. You simply run the test. If all is green, all is good.
• The wiki is rendered to HTML. So you can export to to HTML documents or Rich Text format for those who would like to use Word.
• You can use CSS to format your pages. So you can have everything company specific, team specific or however you like.
• Built in User Access Control, so only registered users can modify the documentation.
• There are a lot of plugins that can extend the functionality of Fitnesse.

Disadvantages

Consequently, there are a number of disadvantages of using Fitnesse over Word.

• Fitnesse requires coding to get the background tests done. None required by Word (given it can’t execute tests anyway).
• Adds another layer of complexity, but saying that, I would say the benefits are greater.
• When using XML messages as sample data, they are encoded to be visible within the wiki format. Therefore before you use them in your fixtures, you need to decode (ie change the &lt; &amp; etc characters) to get the original XML.
• You also get formatting issues with using XML. ie, leading and trailing spaces that needs to be fixed by the fixture.
• Editing the wiki text can be quite difficult if you have exotic formatting. I had some issues getting tables looking like they would in word where you have merged cells etc.
• Not everyone is comfortable with a wiki, epecially non technical people. This was the biggest argument I had with my team about Fitnesse. I don’t think it is founded. Mind you, we had the same argument about Mardown.
• Just like a wiki/HTML page, embedded images and attachments are stored in separate files.
• You are not able to make the document as pretty as a word document. But then again, that isn’t the purpose.

Fitnesse is a very powerful tool and I think using it for specifications is very advantageous especially if you are using free form documents for your specs.  If your organisation is  adverse to change, this may be one way to bring Specification By Example tools in while keeping a similar document format to your current word documents.

Getting started with Fitnesse is easy. The documentation is very well written and can get you started very quickly.

I would very much like to hear if anyone else is using Fitnesse, especially in the SOA/Integration space and how you document your message formats. Please let me know in the comments.

 

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

Example:

00100Fake St   Melbourne Vic

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

<xs:element name="address" dfdl:lengthKind="implicit">
  <xs:complexType>
     <xs:sequence dfdl:sequenceKind="ordered">
       <xs:element name="housenumber" type="xs:string" dfdl:lengthKinbd="explicit" dfdl:length="5"/>
       <xs:element name="street" type="xs:string" dfdl:lengthKind="explicit" dfdl:length="10"/>
       <xs:element name="suburb" type="xs:string" dfdl:lengthKind="explicit" dfdl:length="10"/>
       <xs:element name="state" type="xs:string" dfdl:lengthKind="explicit" dfdl:length="3"/>
    </xs:sequence>
 </xs:complexType>
</xs:element>

Similarly for CSV data

100,Fake St,Melbourne,Vic

Where the data is comma separated

<xs:element name="address" dfdl:lengthKind="implicit">
  <xs:complexType>
    <xxs:sequence dfdl:sequenceKind=="ordered" dfdl:separator"," dfdl:separatorPosition="infix">
      <xs:element name="houseNumber" type="xs:string" dfdl:lengthKind="explicit""/>
      <xs:element name="street" type=""xs:string" dfdl:lengthKind="delimited" />
      <xs:element name="suburb" type="xs:string" dfdl:lengthKind="delimited"/>
      <xs:element name="state" type="xs:string"" dfdl:lengthKind="delimited"/>
    </xs:sequence>
  </xs:complexType>
</xs:element>

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

Implementations

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

Daffodil – Open Source

• Written in scala
• Still in early stages
• In active development
• https://opensource.ncsa.illinois.edu/confluence/display/DFDL

Defuddle – Open Source

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

http://sourceforge.net/projects/defuddle

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

• Paid (But a free developers edition is available)

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.