Sunday, November 15, 2009

GivWenZen and FitLibrary Part 4

I did not see this topic going any further; however, I had a question about turning the test green and I think I should explain how to do this and why I do it the way I do.

Please see the other posts if this post has no context for you read part1, part2, and part3.

So let's start with the simple part, the how.  To turn a test step green or red your step method must return a boolean.


@DomainStep(“my business domain step”)
public boolean myStep() {
  return isTrue();

If the method returns true the step is turned green and if it returns false the step in turned red. (see the image from the previous post) Only the first column in the row is turned green/red.  In our given-when-then test this means the given, when or then column is turned red (and steps are turned green/red too).  Remember that we still have a table it is just not visible to the user.  From a technical standpoint a step written as ‘given the application is in some state’ is a two column table with ‘given’ in the first column and ‘the application is in some state’.  FitLibrary does the magic of turning our plain text into a table by looking for methods in our system under test and/or our fixture.

Now the more difficult part of the post.  Why do I only make the ‘then’ steps in the test turn green?  The simple answer is the ‘then’ step is the only ‘test’ of the actions the test has performed. So first let’s talk about the steps in a BDD test.   My reasons are influenced by and I will borrow heavily from Dan North and Cucumber’s Aslak Helles√ły in this section.  Please read there descriptions as they are much more knowledgeable that I am on this subject.

I am going to describe each step from two points of view.  First I will describe the step as part of a specification or acceptance criteria.  I think this is the most important because in BDD we are first describing the business value we are delivering to the customer.  Then I will describe the step from a test point of view (i.e. what should the methods do when executed as part of a test).

Given specification steps are meant to describe the starting state of the application in order for the actions in the current scenario (the 'when' steps) to be performed.  Given test steps are meant to put the application in to the state described so that the 'when' step can execute successfully (once the application is written correctly :) ).  I do not turn these steps green.  It is my assumption that this part of the application is working and covered in another spec/test.  If something goes wrong here then an exception should be thrown.  Of course, since all your test were passing when you started you should create a new spec that describes how and test that the application can be put into the desired state.

When specification steps are meant to describe an action that is valid or invalid based on the current application state as described in the given steps.  When test steps perform the described action.  If something goes drastically wrong here I like to throw an exception that describes where the problem is in the system.  Why would I turn this step green/red?  What does it mean?  Really it can only mean that the action was performed and no exception was thrown.  Maybe that is enough but usually it is not which leads us to the ‘then’ steps.  It should be impossible for this step to be green if any of the ‘then’ steps are red so I think it is best to not color this step and throw an exception on serious failures.

Then specification steps tell us what is expected after the action of the when steps occur.  Do I expect the application to be in a new state?  Do I expect the action to fail?  Do I expect a message to be sent?  Then test steps verify that thee expected outcomes are true.  These steps must be turned green or red because they are the tests.

The problem with turning the 'given' and 'when' steps green is it gives some false impression that the expected outcomes of the test are true.  It is very likely when you are adding new functionality or changing existing functionality in an existing system that the 'given' and 'when' steps will be green the day the specification is written.  And in the case of FitNesse it will say you have N number of passing assertions and in reality you have not asserted anything.

In conclusion I must ask you to please read Dan North’s articles on BDD and check out the Cucumber pages as they have some good stuff (even if you cannot use Cucumber which is why I wrote GivWenZen).  Please let me know what you think about this method of doing BDD with FitNesse/FitLibrary.

Saturday, November 14, 2009

GivWenZen and FitLibrary Part 3

I mentioned in the previous post that I liked the plain text but really would like to write plain text without the indicator, '- ', that it is plain text.  In my continued testing of and improving the usage of GivWenZen with FitLibrary I have tweaked the ParseUtility class in FitLibrary to look for BDD keywords given, when, then and and.  This allows the same simple test we have been looking at to be written like the following.

A bit cleaner, in my oppinion, that prefixing each line with '- '.

I have done an override of the fitlibrary.utility.ParseUtility class. Unfortunately it is not extensible because it is mostly static methods. :( My override of this class simply changes the place that looks for '- " to look for one of the GivWenZen/BDD keywords, given, when, then or and. Here is the part I changed/added.  I added the static int isGivWenZenLine(String html)method and replaced a line that was simply looking for '- ' with a call to the new method. See ParseUtility is the example source.

When the test is run the then line is turned green on a failure. (more about this later)

In reality there are tables when the plain text test runs. FitLibrary is still running this as if each line were tables and magically creates the tables at run time. I have a custom CSS to stop the tables from showing after the test runs. Below are the CSS values I have overridden in my fitnesse.css. table, td, th { border: none; }

Monday, November 9, 2009

GivWenZen and FitLibrary Part 2

Yesterday I showed an example of using GivWenZen with FitLibrary.  I was pleasantly surprised with how simple it was.  It seemed much easier than using FitNesse/SLiM alone.

Today I want to continue with the FitLibrary and show you a new feature that I really like, plain text specification / test.  Again, I was amazed at how easy it was to do.  To use plain text we can use the same Fixture we used yesterday.  And we simple change the test to look like the following:


- 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

For the test you simple write the sentence and prefix it with a '- '. No special CSS needed to make the table go away. Very nice. It would be nice if the '- ' was not required. I would prefer an assumption that a line is a specification step and require a special character to indicate a comment. However, I do like the feature and it is a step in the right direction toward plain text.

Sunday, November 8, 2009

GivWenZen and FitLibrary

My previous examples of using GivWenZen to write BDD style tests with FitNesse were done with the SLiM test system.  This was mostly due to an issue getting FitLibrary to run with the latest version of FitNesse.  However, Rick Mugridge has released a new version that fixes this issue as well as a few other nice enhancements.  Fixing of autowrapping of booleans, Strings, and other native java types was also big benefit to helping the BDD test read better.

Using GivWenZen with FitLibrary is very easy.  Create your own fixture that extends DoFixture, or any of the related type fixtures, and set the system under test to your instance of the GivWenZenExecutor.  The following is a simple example with a DoFixture extension.

import fitlibrary.DoFixture;

public class GivWenZenDoFixture extends DoFixture {

    public GivWenZenDoFixture() {
        super(new GivWenZenExecutor());

This will allow you to have a FitLibrary specification/test like the following:


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

I am looking at enhancing this using the FitLibrary pluggability to change how methods are looked up. Hopefully, I will have a new post on this soon.

Thanks for the FitLibrary update Rick!