erran-r7 / cucumber-style-guide

Rapid7's ControlsInsight teams cucumber style guide

Cucumber Style Guide

Table of Contents

1. Requirements
2. References
3. Gherkin
4. Step Definitions
5. Hooks
6. Code Portability
7. Tags

Requirements ↩

Ruby Environment Management

rvm - Wide support (use this is you're new to Ruby)

• Mac OS X + Ubuntu instructions:
  • \curl -L https://get.rvm.io | bash -s stable
  • source ~/.rvm/scripts/rvm
  • rvm install 2.0.0-p353
• Ensure that you load RVM as a function on login:
  • Add source ~/.rvm/scripts/rvm to your profile (~/.bashrc or ~/.bash_profile)

rbenv - Less magic than RVM, and more control over your environment

• Mac OS X instructions:
  • brew install rbenv ruby-build
  • rbenv install 2.0.0-p353
• Ubuntu instructions:
  • Perform a basic git checkout.
• To setup shims, completions, auto-rehash shims, and install the sh dispatcher do either:
  • Add eval "$(rbenv init -)" to your profile (~/.bashrc or ~/.bash_profile)
  • Follow rbenv's neckbeard install steps

Cucumber suite

1. Clone your cucumber/automation repository from SCM.
2. cd ~/path/to/your/suite
3. gem install bundler
4. bundle install
5. If installing gems such as nokogiri, you may need to install these dependencies on non-Mac (Ubuntu/Debian) systems:

• sudo apt-get install libxslt-dev libxml2-dev

1. Set up your environment (. ./scripts/env.sh)
2. Update to whatever branch you use
3. Use prefixes such as your products name so you can easily grep for your environment variables.

• env | grep '^YOUR_PREFIX_'

1. Run your first test using: bundle exec cucumber features/ui/login.feature

References ↩

1. Learn Ruby ecosystem in Y minutes
2. Learn Ruby in Y minutes
3. Capybara - The DSL
4. RSpec Expectations - Built in matchers

Gherkin ↩

A Gherkin file is a file that describes a set of expectations about product features in plain text. The Gherkin file extension is .feature.

User Stories

User stories are, just that, a story that details the use case in the user's perspective. User stories follow the format:

Feature: Trending
    As a controlsinsight customer
    I want to see trending of security controls and trend grades
    In order to see daily, weekly, and monthly improvements

Scenario

Anatomy of a Scenario

1. Steps
2. Examples

Steps

The following table describes which step keywords to use and when to use them.¹

Step (keyword)	Purpose	Verb tense
Given	To ensure that a precondition is met.	Past imperfect
When	To get into a desired state (to be used to make assertions).	Present
Then	To make assertions about the current state.	Future
And	To prevent conjunction steps.	Dependent on which step keyword is being replaced.
But	To prevent conjunction steps.	Dependent on which step keyword is being replaced.

#### Scenario/Steps Example

Scenario: I click random buttons
  Given I have put the system in the known state
    And I have also tweaked a random configuration
  When I compare the last known state with the current state
  Then I should see that the last and current states are different

Examples:
  |   user  | password |
  | janedoe | notpass! |
  | jdoe    | sEcrEt34 |

Gherkin Example

# features/ui/login.feature
@ui
Feature: Login page
  As a controlsinsight user
  I want to visit the login page
  In order to gain access to information on my security controls

  Scenario: Invalid user and password login
    Given I have opened the controlsinsight login page
    When I try to login as "johndoe" with the password "Secret123"
    Then I should see the error:
      """
        Sorry. Those credentials did not work. Please try again.
      """

  Scenario Outline: Invalid users attempt to login
    Given I have opened the controlsinsight login page
    When I try to login as "<user>" with the password "<password>"
    Then I should see the error:
      """
        Sorry. Those credentials did not work. Please try again.
      """
    
    Examples:
      |   user  | password |
      | janedoe | notpass! |
      | jdoe    | sEcrEt34 |

Step Definitions ↩

# features/support/env.rb
require 'rspec'
require 'rspec/expectations'
require 'capybara/cucumber'

# features/step_definitions/login_steps.rb
Given /^I have opened the controlsinsight login page$/ do
  visit '/'
end

When /^I try to login as "([^"]+)" with the password "([^"]+)"$/ do |username, password|
  fill_in 'username', :with => username
  fill_in 'password', :with => password

  click_link 'Log on'
end

Then /^I should see the error:$/ do |expected_error|
  expect(find('div.alert').text).to eq(expected_error)
end

Hooks ↩

# features/support/hooks.rb
require_relative './hooks/capybara/'

Code Portability ↩

# lib/helpers/ui_helpers.rb
module UIHelpers
  def login(username, password)
    visit '/'
    
    expect(find('.login-wrapper').text).to eq('Welcome to ControlsInsight by Rapid7 LOG ON')

    fill_in 'username', :with => username
    fill_in 'password', :with => password

    click_on 'Log on'
  end
end

World(UIHelpers)

# features/step_definitions/login_steps.rb
Given /^I have logged into controlsinsight$/ do
  login ENV['CONTROLS_USERNAME'], ENV['CONTROLS_PASSWORD']
end

Tags ↩

Gherkin Example

# features/ui/login.feature
  @ui @wip
  Scenario: Session timeout
    Given I have logged into controlsinsight
    When I allow my session to timeout
    Then I should see the error:
      """
        The current session has expired. Please enter your credentials to continue.
      """

Tagged Hooks

# features/support/hooks.rb
After '@ui,@wip' do |scenario|
  $stdout.puts "\a\nPaused on '#{scenario.name}'. Press enter/return to continue to the next test."
  $stdin.gets
end

---

1. For more about verb tenses see English verb tenses on Purdue OWL. Return to steps ↩