Get Even More Visitors To Your Blog, Upgrade To A Business Listing >>

The Cheezy Internet: Composing tests using Cucumber and Gherkin

This is fourth in a series of blog posts. Care to go back to the beginning?

Following along with Jeff "Cheezy" Morgan's eBook, "Cucumber and Cheese: A Tester's Workshop" (2017), after setting up a development environment, we started creating in Ruby + Watir the basic building blocks for an automated test framework, as we saw in the last Adventures in Automation blog entry. 

Instead of going into great detail testing against the complex test site Jeff uses in Chapter 4: Cucumbers and Puppies of is book, with Sally's Puppy Adoption Agency, we are using the simpler test site, The-Internet https://the-internet.herokuapp.com/login, by Dave Haeffner. 

This blog post will explore scaffolding a site and composing acceptance tests using Cucumber and Gherkin. 

Scaffolding a Site Using TestGen

It's always a challenge for me when creating a new project to figure out where everything should go. What should the folder and file structure be? Luckily, Jeff Morgan created a Ruby gem called "testgen" which solves all of these problems. 
  • Change the directory to the src folder in your home directory: cd ~/src
  • Pick a name for your project, such as "cheezy_internet"
  • Install Jeff Morgan's Ruby gem testgen on your local machine: gem install testgen 
  • Use the Ruby gem testgen to create a new file hierarchy: testgen project cheezy_internet 

The following files will be created:
PS C:\Users\tmaher\src> testgen project cheezy_internet  
create cheezy_internet
create cheezy_internet/cucumber.yml
create cheezy_internet/Gemfile
create cheezy_internet/Rakefile
create cheezy_internet/features
create cheezy_internet/features/support
create cheezy_internet/features/step_definitions
create cheezy_internet/features/support/env.rb
create cheezy_internet/features/support/hooks.rb
create cheezy_internet/features/support/pages
  • Go into the new project folder that was created: cd cheezy_internet
  • Install everything with: bundle install

You can then use VS Code to open the new "cheezy_internet" folder. 

Creating New Test Features in Cucumber

From Cucumber.io / Docs / Overview: "Cucumber is a tool that supports Behaviour-Driven Development(BDD). If you’re new to Behaviour-Driven Development read our BDD introduction first.

"Cucumber reads executable specifications written in plain text and validates that the software does what those specifications say. The specifications consists of multiple examples, or scenarios. [...]

"Each scenario is a list of steps for Cucumber to work through. Cucumber verifies that the software conforms with the specification and generates a report indicating ✅ success or ❌ failure for each scenario. In order for Cucumber to understand the scenarios, they must follow some basic syntax rules, called Gherkin.

"[...] Step definitions connect Gherkin steps to programming code. A step definition carries out the action that should be performed by the step. So step definitions hard-wire the specification to the implementation".

Features Craft Step Definitions

"The purpose of the Feature keyword is to provide a high-level description of a software feature, and to group related scenarios.

"The first primary keyword in a Gherkin document must always be Feature, followed by a : and a short text that describes the feature.

"You can add free-form text underneath Feature to add more description.

"These description lines are ignored by Cucumber at runtime, but are available for reporting (they are included by reporting tools like the official HTML formatter)". - Cucumber.io / Gherkin Reference

Let's say we want to write about the Login feature of The-Internet. We can create a new file under the "features" folder called "Login.feature".

Login.feature
Feature: User Logging into Secure Area

    As an authorized user
    I want to be able to log im
    So that I can access the secure area

    Scenario: Valid User
        Given I arrive on the Login screen
        When I log in using valid credentials
        Then I should arrive at the Secure Area


We can run this features, if we are on the main "cheezy_internet" folder from the command line:

  • cucumber features\Login.feature
Since we don't yet have any step_definitions yet, it gives us samples to go by. If you wanted to you could create a new Ruby file under "step_definitions", and copy and paste the Given, When and Then. 

 1 scenario (1 undefined)  
 3 steps (3 undefined)  
 0m1.906s  
 You can implement step definitions for undefined steps with these snippets:  
 Given('I am on the Login screen') do  
  pending # Write code here that turns the phrase above into concrete actions  
 end  
 When('I log in using valid credentials') do  
  pending # Write code here that turns the phrase above into concrete actions  
 end  
 Then('I should arrive at the Secure Area') do  
  pending # Write code here that turns the phrase above into concrete actions  
 end  

Refine The Feature File


Let's say we wanted to explicitly feed in the username and password into the test, so that we could share the test among many different sets of valid credentials, we could rewrite the feature file: 

Feature: Logging into Secure Area

    As an authorized user
    I want to be able to log im
    So that I can access the secure area

    Scenario: Valid User Login
        Given I am on the Login screen
        When I log in using "tomsmith" and "SuperSecretPassword!"
        Then I should arrive at the Secure Area
        And I should see "Welcome to the Secure Area"

Running the test, and copying-and-pasting into a new file called "login_steps.rb" under the "step_definitions" folder, we get: 

login_steps.rb
Given('I am on the Login screen') do
    pending # Write code here
  end
 
  When('I log in using {string} and {string}') do |string, string2|
    pending # Write code here
  end
 
  Then('I should arrive at the Secure Area') do
    pending # Write code here
  end
 
  Then('I should see {string}') do |string|
    pending # Write code here
  end


Parts of a Step Definition File

Cucumber.io / Gherkin Reference: "Given steps are used to describe the initial context of the system - the scene of the scenario. It is typically something that happened in the past.

"When Cucumber executes a Given step, it will configure the system to be in a well-defined state, such as creating and configuring objects or adding data to a test database.

"The purpose of Given steps is to put the system in a known state before the user (or external system) starts interacting with the system (in the When steps). Avoid talking about user interaction in Given’s. If you were creating use cases, Given’s would be your preconditions [...]

"When steps are used to describe an event, or an action. This can be a person interacting with the system, or it can be an event triggered by another system.

"It’s strongly recommended you only have a single When step per Scenario. If you feel compelled to add more, it’s usually a sign that you should split the scenario up into multiple scenarios. [...]

"Then steps are used to describe an expected outcome, or result.

"The step definition of a Then step should use an assertion to compare the actual outcome (what the system actually does) to the expected outcome (what the step says the system is supposed to do).

"An outcome should be on an observable output. That is, something that comes out of the system (report, user interface, message), and not a behaviour deeply buried inside the system (like a record in a database)".

Fill Out The Step Definition


Let's say we enter the browser test code we came up with in the last blog entry, we get:

login_steps.rb
Given('I am on the Login screen') do
    @browser = Watir::Browser.new :chrome
    @browser.goto 'https://the-internet.herokuapp.com/login'
  end
 
When('I log in using {string} and {string}') do |username, password|
  @browser.text_field(id: 'username').set(username)
  @browser.text_field(id: 'password').set(password)
  @browser.button(value: 'Login').click
end
   
Then('I should see {string}') do |text|
    fail "Expected text not found: #{text}" unless @browser.text.include? text
end


Hrm. The "Then" clause could be better.  Let's use the "expect" RSpec matcher:

Then('I should see {string}') do |expected|
    expect(@browser.text).to include expected
end

Going back to the Given and When clause, we can also replace the parentheses and single quotes with regular expressions and Capture groups.

What are Capture Groups in Cucumber?


Jeff Morgan's "Cucumbers and Cheese":

"Cucumber has something called Capture Groups. This is simply anything that is surrounded by
parentheses. Whatever matches the capture group is placed into a variable passed to the block.
Let’s look at an example. In the previous chapter we had the following step:

"When /^I enter "([^"]*)" in the address field$/ do |address|

"The capture group is ([^"]*) and the value found there is placed in the address parameter.

"We forced this to happen by placing the double quotes around the value in the feature file and
cucumber took this as a clue to create the capture group. The truth is that there is really no need for
the double quotes. If you remove them from both the feature file and step definition you will see
that it works exactly the same.

"The last capture group and regular expression ([^"]*) is somewhat complex. Let’s spend a little
time and see what we can do to simplify it. Here are a few simple things to learn to help you write
simple regular expressions for cucumber.

• "The . character will match any character. For example .. matches “at” and “on” but it doesn’t
match “off” since it is three characters.
• "The * character means zero or more of the previous element so ab* matches “ab”, “abb” and
“a”. a.* matches “a”, “ab”, “abb”, “ac”, etc.
• "The + character means one or more of the previous element so ab+ matches “ab”, “abb” but
does not match “a”. a.+ matches “ab”, “abb”, “ac” but does not match just “a”.
• "Character classes are any set of characters contained within []. For example, [0123456789]
matches any number. [0-9] is shorthand for this example. Another common character class
is [A-Za-z] to represent any alpha character.
• "There are shorthand expressions for character classes. Here are a few: \d is equal to [0-9], \w
is equal to [A-Za-z0-9_], \s is equal to [ \t\r\n\v\f]".

"[^"]*"matches something (or nothing) in double quotes

login_steps:
Given /^I am on the Login screen$/ do
    @browser = Watir::Browser.new :chrome
    @browser.goto 'https://the-internet.herokuapp.com/login'
  end
 
When /^I log in using "([^"]*)" and "([^"]*)"$/ do |username, password|
  @browser.text_field(id: 'username').set(username)
  @browser.text_field(id: 'password').set(password)
  @browser.button(value: 'Login').click
end
   
Then /^I should see "([^"]*)"$/ do |expected|
    expect(@browser.text).to include expected
end

Create a Scenario Outline

What if there were many different valid usernames and passwords you could pick and choose from? 

From Cucumber.io / docs / gherkin: "The Scenario Outline keyword can be used to run the same Scenario multiple times, with different combinations of values [...]. Copying and pasting scenarios to use different values quickly becomes tedious and repetitive [...] We can collapse [...] similar scenarios into a Scenario Outline.

"Scenario outlines allow us to more concisely express these scenarios through the use of a template with -delimited parameters"

Cucumber allows us to create a Scenario Outline, where data can be fed into the test, executing once per row of test data. 


Feature: Logging into Secure Area

    As an authorized user
    I want to be able to log in
    So that I can access the secure area

    Scenario Outline: Valid User Login
        Given I am on the Login screen
        When I log in using "" and ""
        Then I should see "Welcome to the Secure Area"

    Examples:
        | username | password             |
        | tomsmith | SuperSecretPassword! |  



Now, we have a (mostly) complete feature file, and an improved step definition file. 

With the next blog article, we will explore adding Page Objects into our little project. 


Happy Testing!

-T.J. Maher
Sr. QA Engineer, Software Engineer in Test
Meetup Organizer, Ministry of Testing - Boston

Twitter | YouTube | LinkedIn | Articles


This post first appeared on Adventures In Automation, please read the originial post: here

Share the post

The Cheezy Internet: Composing tests using Cucumber and Gherkin

×

Subscribe to Adventures In Automation

Get updates delivered right to your inbox!

Thank you for your subscription

×