Test Your Scenario's Readability

A few weeks back, I learned from Jeff Morgan about a gem called cuke_sniffer.  As described on their github page, it is "Tailored for identifying critical problems as well as general improvements to your project/features/scenarios/step definitions".  For those with Microsoft Word, this is equivalent to Word's Readability Tool, which is based on the Flesch Reading Ease score and Flesch-Kincaid Grade Level tool that can be found in Microsoft Word's Readability Tool.

For those who have not heard of cucumber, it is a framework that lets software development teams describe how software should behave in plain text.  I have seen teams get carried away with this and cuke_sniffer is here to keep teams focused on delivering software.  

Let's start with a simple feature file and see what happens.  I've written a simple scenario for a login feature of an application.

Feature:  As A User, I would like to log into my application, so that I can use it

Scenario Outline:  As a user, I would like to log in as a valid user

Given I am on the login page
  And I see the username text box
  And I see the password text box
  And I see the submit button
  And I see the "Remember Me" check box
When I enter my username in the username text box
  And I enter my password in the password text box
  And I click on the submit button
Then I am on the home page
  And I see my username on the screen

Seems pretty straightforward and understandable.  Now, let's run cuke_sniffer and see what we get:

$ cuke_sniffer.rb features/cuke_sniffer.feature 

Features:
.
Step Definitions:

Cataloging Step Calls: 

Assessing Score: 
Suite Summary
  Total Score: 121
    Features /demo)
      Min: 121 (/demo/features/cuke_sniffer.feature)
      Max: 121 (/demo/features/cuke_sniffer.feature)
      Average: 121.0
    Step Definitions (/demo)
      Min:  ()
      Max:  ()
      Average: 
  Improvements to make:
    (4)Implementation word used: text box.
    (2)Implementation word used: page.
    (2)Implementation word used: button.
    (1)Implementation word used: check box.
    (1)Implementation word used: click.
    (1)Implementation word used: screen.
    (1)Scenario Outline with no examples table.
    (1)Scenario with too many steps.
Completed Sniffing.

Interesting, now I have a score and cuke_sniffer has provided some suggestions.   


Scenario Outline with no examples table

This improvement is the easiest to address.    Scenario outlines are designed to allow us to express a scenario as a template with placeholders.  Since, I am not really attempting to this scenario several times with various username and password combinations, all I have to do is remove the "Outline" from my scenario.

Scenario  with too many steps

This is rather a subjective number.  What constitutes as too many steps?  When I look at source code of cuke_sniffer, I see that the maximum number of steps is set to 7.  I have 10 steps in my scenario, which is not that much more, since it clearly describes what I am doing to log into my application.  So what is cuke_sniffer trying to tell me.

Implementation word used

The whole idea behind cucumber (and BDD) is that you describe what you want to achieve and not how you achieve it.  Cuke_sniffer searches for the following words in your scenarios:  page, site, url, button, drop down, drop down, select list, click, text box, radio button, check box, xml, window, pop up, pop-up, and screen.

Let's rewrite:


Feature:  As A User, I would like to log into my application, so that I can use it

Scenario:  As a user, I would like to log in as a valid user

Given I can log into my application
When I log into the application
Then I am ready to use the application

And the results...
Features:
.
Step Definitions:

Cataloging Step Calls: 

Assessing Score: 
Suite Summary
  Total Score: 0
    Features (/Users/melvinlaguren/github/demo)
      Min: 0 (/Users/melvinlaguren/github/demo/features/cuke_sniffer.feature)
      Max: 0 (/Users/melvinlaguren/github/demo/features/cuke_sniffer.feature)
      Average: 0.0
    Step Definitions (/Users/melvinlaguren/github/demo)
      Min:  ()
      Max:  ()
      Average: 
  Improvements to make:
Completed Sniffing.


Wow!.  A perfect 0?  Actually, with what was written, when you dive through the code of cuke_sniffer, 0 is a good score to have.

In conclusion

This is a great tool to implement as part of your BDD process.  Other nice things about cuke_sniffer is that it integrates with Continuous Integration.  It will also evaluate your step definitions (will cover in a later post).  Overall, a great start to what promises to be a useful gem in writing living requirements.

Great Job, Robert!