GivWenZen – Behavior Driven Development for FitNesse

Wes Williams, http://weswilliamz.blogspot.com/, @weswilliamz

Getting started with GivWenZen

The website for GivWenZen has quite a bit of information for helping you get started with the tool. Of course you can download the tool but there are also links to documentation of all types including several presentations and screen-casts to help you get started and move into more complex areas. The version 1.01 is used in all examples in this article. I continually test it to make sure nothing is broken as new versions of FitNesse are released.

Main site: https://github.com/weswilliams/GivWenZen
License: MIT license.
Downloads: http://code.google.com/p/givwenzen/downloads/list
Documentation: https://github.com/weswilliams/GivWenZen/wiki
Support: http://groups.google.com/group/givwenzen_user

What is GivWenZen and why does it exists?

WARNING: Tools, GivWenZen or any other testing tool, cannot solve the poor communications between developers, testers and business people. Individuals still must talk to each other continuously. GivWenZen is only a tool to assist in the process of verifying the understanding of those conversations.

Around the 2003 time period I was working for a company which had been moving in an Agile direction since 2001. We were trying to find a way to drive better collaboration between developers, testers and our product owner as well as create automated acceptance tests. At the time we referred to this as Acceptance Test Driven Development (ATDD). We started by using a tool called FIT and then moved to FitNesse, a tool that made FIT specifications and tests more user friendly by allowing them to be created with wiki pages.

This was working well but we were finding the tests difficult to maintain and understand at times. This was not due completely to the tool, FitNesse, but due in large part to some bad practices that I will talk about later. Developers were also finding FitNesse and some of the 'plug-ins' we were using had a few tricky quirks to them that were difficult to troubleshoot.

This lead me on a search to find other tools that provided the same values of collaboration and verification as FitNesse but were easier to use. In 2008 I heard Dan North speak about a collaboration idea he was calling Behavior Driven Development (BDD). In BDD each specification is described with 3 key works given, when and then. 'Given' gives the state of the application before the tests exist. 'When' is the action performed that the specification/tests is defining and verifying. 'Then' is the expected result of the action based on the previous state.

Shortly after hearing this talk I read about a new tool in beta called Cucumber. Cucumber is a ruby based tool created to help teams do BDD. The specifications and tests that were created with the tool were easy to understand and implement. It had some similar ideas as FitNesse but had taken them in a bit of a different direction. The specifications were mostly textual although tables could be used in certain situations. I was up and running with the tool in a very short period of time, minutes. Within minutes I understood how to use the tool. Within a couple of hours I had it working with JRuby as well testing a small Java application I used for FitNesse training. I was very happy with what I had found.

I thought this article was about GivWenZen??? Well I quickly found my team mates were not as happy about the tool as I was. The complaints went like this: It is Ruby and we are doing Java; We have already invested a lot in FitNesse, we had 1000s of FitNesse tests. However, they did like the tests and the idea of BDD. This led me to try and add a similar set of features to FitNesse and to the tool that became GivWenZen.

Installing GivWenZen

The simplest way to get started is to download the zip file which includes GivWenZen and a recent version of FitNesse. Here are the steps:

1. Download the zip file found in the downloads section of the GivWenZen site, http://code.google.com/p/givwenzen/downloads/list, and extract it to the directory of your choice
2. Start the FitNesse server: from a command line change to the directory you unzipped too and run the command java -jar ./lib/fitnesse.jar (see note below)
3. Open a browser and navigate to the main FitNesse for the server instance you just started which can be found at http://localhost/.
4. From the web page that is displayed click on the SlimExamples link which takes you to the http://localhost/SlimExamples page.
5. On the SlimExamples page you will see a set of 'buttons' going down the left side of the page starting with, Suite, Edit, etc. Click the Suite button and all the tests in the suite will run.

Note: If you get an error similar to 'Port 80 is already in use' change the command to use a different port. (i.e. java -jar ./lib/fitnesse.jar -p8080 ) This will require the URLs in the steps above to include this port number. (i.e. http://localhost:8080/)

Understanding the Specification/Test

From the SlimExamples page navigate to the first test, AddTwoNumbers, http://localhost/SlimExamples.AddTwoNumbers. Starting at the top of the page there is a line that reads Included page: .SlimExamples.SetUp (edit). Every test can have a SetUp page that is executed before the rest of the tests are executed. This is a good place to start the GivWenZen fixture and other common tasks that multiple tests will need.

I just used a new term, fixture, so let me define that real quick before continuing with GivWenZen. Fixtures are the code that ties a test page to the application being tested. Each test page can use 1 or more Fixtures. There are also multiple types of fixtures allowed with FitNesse SliM, more info can be found at http://fitnesse.org/FitNesse.UserGuide.SliM. GivWenZen supplies a simple script fixture named GivWenZenForSlim.

Expand the setup section by clicking the ? symbol and you will see the contents of the page. Click the edit button and it will open the page in edit mode. The page looks a bit different in edit mode. Remember FitNesse is a wiki server so we are now seeing some special wiki syntax, but do not worry; like all wikis the syntax is simple and minimal. The page you see is something like the following:

|import|
|org.givwenzen|
-|script|
|start|giv wen zen for slim|

The first line |import| tells fitnesse what java package(s) the fixtures for this page can be found. In the case of our tests we only need one import line as we are using a single fixture found in the package org.givwenzen as seen on the second line.

The next two lines of the SetUp page tell FitNesse to start a specific script fixture. In the case of our test this is the org.givwenzen.GivWenZenForSlim fixture. Notice that Slim allows for spacing to be introduced in the names that come from code. In our case GivWenZenForSlim can be written giv wen zen for slim. The '|' character is a table column delimiter as used by most wiki syntax. There is one special wiki syntax character that is unique in this example and it is the '-' character. This character is used to hide the first row of a table which in FitNesse slim usually describes the type of test table being used. In most cases this is unimportant for understanding the test so I like it hidden.

So far we have allowed the environment to be set for our tests by telling FitNesse where the fixture(s) are located and starting a fixture. Now let's look at the test itself.

After navigating back to the AddTwoNumbers test page click the edit button in the left side menu. This will display text similar to the following partial page text showing only the first scenario and leaving off descriptive text.

-|script|
|given|i turn on the calculator|
|and|i have entered 50 into the calculator|
|and|i have entered 75 into the calculator|
|when|i press add|
|then|the total is 125|
|show|then|what is the total|

The GivWenZen fixture is where the environment is set up

The first row of the test table is just like the SetUp table that started the GivWenZen fixture. The remaining table rows all start with a column that contains a GivWenZen keyword (BDD language) given, when, then or a linking 'and' keyword with the exception of the last row that starts with the show FitNesse Slim keyword. These keywords are method names in the GivWenZenForSlim fixture that take a string parameter. The second columns all have a sentence or text that describes a step in the test. Here is a snippet from the GivWenZenForSlim fixture:

public Object given(String methodString) throws Exception {
return executor.given(methodString);
}

The keywords can also start with a capital letter. i.e. Given. The last row in the table uses a keyword called show which simply creates an extra column at the end of the row when the test is run and puts the return value of the test in that column.

GivWenZen step classes start tying the test to the application

GivWenZen must now find the method associated with the text in each step. e.g. the 'i turn on the calculator' portion of a step. GivWenZen does this by looking for java classes in a specific set of packages, by default this is bdd.stpes. The class for this example is bdd.steps.ExampleSteps. Here is a snippet from the class for the 'i have entered 50 into the calculator' step.

@DomainSteps
public class ExampleSteps {
…
@DomainStep("i have entered (\\d+) into the
calculator")
public void enterNumber(int number) throws Exception {
numbers.add(number);
}}

Step classes must be annotated with the @DomainSteps annotation as seen in the first line of the example above. Step methods are annotated with the @DomainStep annotation and contain text that is a regular expression. In this example (\\d+) captures the number in the step and passes it as the first parameter to the enterNumber method.

Turning the test step green or red

One important part of a test is knowing if it was successful. FitNesse indicates this by turning a step green or red when it is executed to indicate success or failure. In GivWenZen simply have your test methods return a boolean to indicate success or failure.

@DomainStep("the total is " + SOME_NUMBER)
public boolean theTotalIs(int exepectedTotal) throws
Exception {
// simple example calling another step
return givWenZen.then("what is the
total").equals(expectedTotal);
}

Displaying a value in the test

Displaying a value in a test is not a GivWenZen specific feature because this, like many other nice features, is built into FitNesse Slim. If a method returns an Object of any type FitNesse will display that value if the step begins with the keyword show.

(snippet from the test)

|show|then|what is the total|

(snippet from the code)

@DomainStep("what is the total")
public Integer getTotal() {
return total;
}

Principles to keep specifications maintainable

No matter how good the tool is or how easy it is to use does not keep you from causing yourself a lot of long term support issues. Many places I have worked have started to meet a goal of having some type of automated testing and in most cases they have ended up with something that is hard to maintain and ends up in a state that the tests are no longer used.

Dale H. Emery wrote a great article called 'Writing Maintainable Automated Acceptance Test' (pdf) http://dhemery.com/pdf/writing_maintainable_automated_acceptance_tests.pdf and Bob Martin followed this with a great screen-casts example of how to meet these principles in http://blog.objectmentor.com/articles/2009/12/07/writing-maintainable-automated-acceptance-tests. In the article Dale introduces the idea, or at least reminds us, that test automation is software development and with software development we should expect maintenance costs. Change in requirements and internal structure is required in order for the software to continue to meet the needs of the customer so the tests must change as well.

Dale goes on to give some principles to help reduce the maintenance costs. The first principle is keep incidental details out of the tests. That is keeping details out of the tests that are unimportant to the concept being tested out of the test. e.g. If I am verifying the system does not let me schedule an event in the past the only important detail I need to know about the event is that the start date is not earlier than the current date.

The next principle he discusses, and one I have seen broken a lot, is avoid duplication. Duplication will lead to changes trickling through many of your tests.

The last principle he gives is name ideas to indicate their purpose. If we were verifying the event that is in the pass could not be created we could name the bad date date_before_today.

Given an event with a date before today

When the event is saved

Then an error occurs indicating the date must be today or later

These are good principles that will help you avoid many of the issues that make teams fail when automating tests. Following them will help you keep the tests easier to maintain. At the end of the article there are some additional resources that expand of these basic principles.

Wrapping it up

This article shows the basics of getting started with GivWenZen and FitNesse as well as a few pitfalls to avoid. At this point you should be able to start FitNesse with GivWenZen and create a simple test and step class. However, this is only the beginning so read through more of the examples and play with them for a while. You will have more questions so check out the Changing the Defaults section in the GivWenZen documentation, http://code.google.com/p/givwenzen/wiki/ChangingTheDefaults.

Further reading

Don't stop with this article! Take a look at these great resources in order to learn more.

'Specification by Example' by Gojko Adzic: http://manning.com/adzic/

'The Secret Ninja Cucumber Scrolls' by Gojko Adzic: http://cuke4ninja.com/

'The RSpec Book' by David Chelimsky, et al.: http://www.pragprog.com/titles/achbd/the-rspec-book

'The Reality of Automated Acceptance Testing' by George Dinwiddie with links to other blogs discussing issues with automated acceptance testing - http://blog.gdinwiddie.com/2010/03/01/the-reality-of-automated-acceptance-testing/

---

More Software Testing and Agile Testing content

• Software Testing Magazine
• Software Testing Tutorials Videos

---

Click here to view the complete list of tools reviews

This article was originally published in the Spring 2011 issue of Methods & Tools