Generating cucumber yard BDD Documentation automagically with Jenkins

When I first read about BDD documentation cucumber-yard here, I fell in love. I then decided to try it out and write my experience in setting it up. That worked great, however I always thought that cucumber-yard would add even more value if I could automate the process of generating BDD documents on fly and host it somewhere. The search began and I decided to setup a Jenkins job which can poll for changes to my git repository, run cucumber yard and publish documents automagically. That way team can refer to an always up-to-date living, runnable BDD documentation.

So I decided to play with Jenkins. Any change to automation Github repo, will trigger a job that will generate cucumber-yard docs.  My initial attempts to run ruby commands in shell failed because Jenkins runs all of its jobs with user “jenkins” and the ruby version for “jenkins” user was not compatible with cucumber-yard. After further research I came across RVM plugin for Jenkins which I thought would solve the ruby version issue. I further decided to use Rake plugin to invoke rake tasks and HTML Publisher plugin to publish cucumber yard docs on Jenkins. So to summarize, here is my Jenkins setup looked like,

1. RVM plugin – to select suitable ruby version for cucumber-yard
2. Rake Plugin- to invoke rake tasks
3. Publish HTML Reports – to publish cucumber yard docs on jenkins

This seemed straightforward to setup, however I stumbled upon a newer road block. I wasn’t able to use RVM plugin properly since “jenkins” user did not have enough privileges to install ruby in System directory. I got below errors at RVM step

[workspace] $ bash -c " source ~/.rvm/scripts/rvm && rvm use --install --create 2.0.0 && export > rvm.env"
ruby-2.0.0-p451 is not installed - installing.
Searching for binary rubies, this might take some time.
Found remote file
Checking requirements for osx.
ERROR: '/usr/local/bin' is not writable - it is required for Homebrew, try 'brew doctor' to fix it!

I solved this by giving “jenkins” user special permissions like

sudo chown –R jenkins:admin /usr/local/bin

Also make sure to configure Yard for your jenkins user like,

$ mkdir ~/.yard (create .yard in your home directory)
$ yard config load_plugins true
$ yardoc 'src/test/resources/features/*.feature'

After this, RVM plugin was able to install and switch to provided ruby version. After this was resolved, the rest of it was fairly straightforward and it worked great. Here are some sample screenshots of my Jenkins configuration to generate cucumber yard documents.

This entire setup is working great for my team and I hope this post helps you setup cucumber yard on Jenkins.

To goto cucumber yard reports, navigate to


cucumber yard Config  Jenkins

html report link

BDD Living Documentation using Yard-Cucumber

BDD Framework like Cucumber aims to bridge gap between business and technology. In BDD we describe behavior of software as plain text in .feature file. Cucumber helps us wrap business language around test code so that there is better visibility and tests are not lost in code. Sharing documentation within and across teams is an important aspect and there are currently different solutions available to host and share .feature files. I have used Relish in the past for hosting feature files online. also looks promising for collaboration. I came across a post from Shashikant here about living documentation using Yard-Cucumber and wanted explore more.  Yard-Cucumber is  a free tool which can be used to generate documentation interface to view features, tags etc. It generates HTML files and is a nice interface to search/view features and tags. In his blog post Shashikant shows how to use Yard-Cucumber for a ruby cucumber project. I attempted to use Yard-Cucumber for a cucumber-jvm project and share my experience in this blog post. Here are the steps,

Make sure you have ruby 2.0.0 installed

Go to your project and install bundle if its not installed already.

gem install bundle
bundle init

This will create a Gemfile in your project. Add gems below,
gem "yard-cucumber"
gem "redcarpet"
gem "rake"

Then execute,
bundle install

Now lets create Rakefile and add contents below,

require 'yard' do |t|
t.files = ['src/test/resources/features/**/*.feature', 'src/test/java/**/*.java']

Now Yard-Cucumber is configured successfully and now you should be able to run the tool to generate reports,
bundle exec rake yard

Now you should see doc folder under your project. index.html should be the launching pad. My sample project is hosted on github here and you can take a look at my docs over here (give it a few seconds to load).

Some images from my project are like,