BDD Living Documentation with Yard-Cucumber

Shashikant Jagtap

Yard Cucumber

Living documentation is very essential when working in the collaborative way with technology and business people. Behaviour Driven Development  [BDD]methodology enforces communication between business and technology. Any Documentation with nice web interface can be easily understood by the business people.

There are some tools like Relish(@relishapp) where you can host your living documentation but Yard-Cucumber is the nice and cool interface to host your living documentation locally.

The Yard-Cucumber is a RubyGem that creates documentation. The Yard-Cucumber is the cool and free solution to generate documentation locally. This plugin is developed by Frank Webber. Previously “Yard” can generate documentation with Class List, Method List and Tag List and README file but Yard-Cucumber add things like ‘Features’ and ‘Step-Definitions’.

Using Yard-Cucumber

Installation

I assume, you are using latest version of Ruby. Here is Ruby 2.0.0. In your existing Cucumber project, Just install Yard-Cucumber Gem. You may need ‘redcarpet’

$ gem install yard-cucumber
$ gem install redcarpet

Or in your Gemfile. Add the following Gems  you don’t have already

gem "yard-cucumber"
gem "redcarpet"

 

Now, install bundler with to use those Gems

$ bundle install

Now you are good to use Yard-Cucumber.

Configuration

Now, Let’s configure Yard Cucumber. Just run following commands from your project

$ mkdir ~/.yard
$ yard config load_plugins true
$ yardoc 'example/**/*.rb' 'example/**/*.feature'

Now, Let’s use inbuilt Rake Task to run Yard-Cucumber. If you don’t have rake then install it.

$ gem install rake

Let’s create a Rake task in the Rakefile

require 'yard'

YARD::Rake::YardocTask.new(:yard) do |t|
t.files   = ['features/**/*.feature', 'features/**/*.rb']
end

Now we have success fully configured Yard-Cucumber in our project.

Use Yard-Cucumber

Let’s use Yard-Cucumber with our rake task.

$ bundle exec rake yard

This will create a all documentation in the ‘/doc’ direcory. Now you will have .yarddoc and ‘doc’ directory in your project.

$ ls -a
 .git         Gemfile      README.md    browser.json doc          report.html .bundle      .yardoc      Gemfile.lock Rakefile     cucumber.yml features     report2.html

$ open doc/index.html

My iTerm window look like this:

yard-cucumber

 

How Documentation will Look Like?

This documentation contains list of all Features, Classes, Tags and Methods. It’s very handy to toggle between Features, Tags and Classes Or Methods.

It looks like this for example project:

doc_index

 

Source-Code on GitHub

There is a example project available on my GitHub account. Cuke_Experiment 

You can Clone and Try it

$ git clone https://github.com/Shashikant86/Cuke_Experiment
$ cd Cuke_Experiment
$ rvm use 2.0.0
$ bundle install
$ bundle exec rake yard

 

Enjoy Living Documentation and Share it with your Team. !

HAPPY BDD.