Branston¶ ↑

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

Branston allows you to create accounts, log in, create user stories, and group them into projects, 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. (see github.com/steventux/branston-client)

Installation¶ ↑

Branston is now split into two distinct applications, the Branston Rails webapp and the Branston-client cli tool. You can run the Rails app on a centralised server then cut the Gherkin generation commands from your story cards with old clippy.

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

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

steventux / branston