Branston

A user story tracker that generates gherkin files and step definitions for use with the cucumber testing framework.

After installation, Branston acts as both a server and a client. The server allows you to create accounts, log in, create user stories, and group them into iterations and releases. Individual user stories can be given acceptance conditions so that the geeks developing them know when they’re done.

Once a user story has been given acceptance conditions, it’s possible to write a cucumber test for it. On a developer machine, the Branston client allows a developer to auto-generate cucumber tests from the user stories on the server.

Installation

There’s a bit of a dependency chain needed to get things running. Cucumber has a dependency on Nokogiri, which itself has some libxml related dependencies including a dependency on a C compiler. On a clean Debian/Ubuntu box, this…

sudo apt-get install libxml-ruby  libxml2-dev libxslt-ruby libxslt-dev build-essential sqlite3 libsqlite3-ruby libsqlite3-dev
sudo gem install branston

…currently does the trick.

Example Usage

First, initialize a branston server:

branston -i

Initialization will make a hidden folder in the present working directory (called “.branston”) and make a sqlite3 database and necessary config files.

Then, start the server:

branston -s

This will start the Branston server on port 3970. By default, the server binds to the IP 0.0.0.0, so don’t do this on a public-facing box unless you want to make your Branston server available to the entire internet.

Writing stories is a two-step process. Stories are laid out so that they look somewhat like the recipe cards we use in our agile processes; on the front of the card, we write the user story itself, on the “back” of the card are the testing scenarios for the story. Start off by writing the basic story as your first step.

Once the story itself is done, you can write one or more scenarios for the story. Each testing scenario describes a concrete test involving a user, some preconditions, and one or more testable outcomes for the story.

Once you’ve got some stories with acceptance conditions, you can make your Rails app and start generating cucumber test code. Try this:

rails test
cd test
rake db:migrate
ruby script/generate cucumber

Now, let’s assume you’ve got a story called “add video”. You want to turn the scenarios for that story into executable cucumber test code, so click on the little “clippy” swf next to your story title, and you’ll get the generator code copied onto your clipboard. It might look like this:

branston -g -f add-video -p 3970 -b 192.168.0.43

Change directory into the root of your Rails project, paste that generator code into your terminal and hit enter. The Branston client will generate the cucumber steps for that user story. Then you can run:

rake cucumber:all

You’ll see some failures. Implement the steps and code to make your cucumber tests pass.

Known problems

Generating cucumber code for a story twice, or step definition files with identical names, will wipe out any customizations you did the first time through. This sucks and is no fun. We’ll get around to fixing it unless you get around to fixing it first (pull requests welcome).
The security is at present somewhat ludicrous, anyone can sign up and automatically get access to the stories. We use our Branston server on a private intranet and haven’t bothered to get it ready for public-facing use yet. In general we only use the user accounts to see who did what.
There is no multi-project support yet.

Help options

Running

branston -h

will show a basic help message. To get help on any of the top-level options, you add “-h” after that option, e.g.

branston -s -h

will list out the help options for the branston server.

Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don’t break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. If you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull.
Send me a pull request. Bonus points for topic branches.

Copyright

See LICENSE for details.

Credits

Dan Garland, Dave Hrycyszyn, Steve Laing