Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Examples and matchers for Cucumber testing with Watir

branch: master
README.rdoc

Web Testing with Cucumber and WATIR

This is a great way to test web sites or automate web processes using the descriptive Cucumber language called Gherkin. You can use plain-text stories like this one:

Feature: Search for code
  In order to implement a Javascript image rollover
  As a developer
  I want to be able to search for code by description

  Scenario: Find a rollover solution
    Given I go to "http://www.snippetstash.com/"
      And I fill in "q" with "rollover"
     When I press "Search"
     Then I should see a link to "Simple Prototype image rollover"

to drive your web browser. It's a great way to automate or to drive your development process.

See the sample features in this project for more:

Installation

We'll need to install Ruby and some additional libraries.

Windows

You'll need to install both the Rubyinstaller and the devkit. Installer: rubyforge.org/frs/download.php/69033/rubyinstaller-1.8.6-p398-rc2.exe

Devkit: wiki.github.com/oneclick/rubyinstaller/development-kit

gem install cucumber win32-process --no-ri --no-rdoc
gem install selenium-webdriver -v=0.0.28 --no-ri --no-rdoc
gem install rspec -v=1.3.0
gem install watir-webdriver --pre

Internet Explorer

If you want to use IE you need to

gem install watir --no-ri --no-rdoc

Colored Output

You can get colored output by installing win32console

gem install win32console --no-ri --no-rdoc

Mac

(Use sudo if you're not using RVM)

gem install cucumber safariwatir --no-ri --no-rdoc
gem install selenium-webdriver -v=0.0.28 --no-ri --no-rdoc
gem install rspec -v=1.3.0 --no-ri --no-rdoc
gem install watir-webdriver --pre --no-ri --no-rdoc

Usage

Write stories in plain English using the provided watir_matchers set, or write your own custom matchers.

How to write them

Stories always have a feature and a reason for the feature. Follow the

In order to ...
  As a ...
I want to ...

If you can't think of a reason, the feature may not be that important.

Next, write scenarios to drive the browser.

Scenario: Filling out the signup form
  Given I go to "http://foo.com/signup"
   When I fill in "Name" with "Brian Hogan"
    And I fill in "Email" with "nospam@gmail.com"
    And I fill in "City" with "Eau Claire"
    And I fill in "State" with "WI"
    And I uncheck "Send me updated news"
    And I select "Male" from "Gender"
    And I press "Sign up"
   Then I should see "Thank you for signing up!"

Included matchers:

These matchers are available for use in your stories. Each one can be used interchangeably with Given, When, Then, or And.

[urls] When I visit "http://www.twitter.com/"
[urls] When I go to "http://www.twitter.com/"
[links] When I click "Apply Now"
[links] When I click "Apply Now"
[links] Then I should see a link to "Our blog" with the url "http://www.foo.bar.com/"
[links] Then I should see a link that contains the text "Our blog" and the url "http://www.foo.bar.com/"
[links] Then I should see a link to "Sign up!"
[links] Then I should see a link with the url "http://www.foo.bar.com/"
[general] Given I see "Record added successfully"
[general] Then I should see "Record added successfully"
[general] Then I should not see "You don't have access to that feature"
[image] When I click the "Apply now" image  (uses ALT text)
[text fields] When I fill in "Username" with "Foo"
[select box] When I select "English" from "Languages"
[check box] When I check "Remember me"
[check box] When I uncheck "Remember me"
[check box] Then the "Remember me" checkbox should be checked
[check box] Then the "Remember me" checkbox should not be checked
[radio button] When I choose "Remember me"
[radio button] Then the "Remember me" option should be chosen
[radio button] Then the "Remember me" option should not be chosen
[buttons] When I press "Submit" 
[buttons] When I press "Submit" and wait for a new page
[buttons] When I press "Submit" and wait 5 seconds
[Waiting] When I wait 10 seconds
[DIVs] Then I should see a div with the id "navbar"
[DIVs] And I wait until I see a div with the id "dialog"
[Forms] Then I should see a form that goes to "http://www.foo.bar.com/signup"
[browser] I should be at "http://www.foo.com/"
[browser] The browser's URL should be "http://www.foo.com/"
[browser] The browser's URL should not be "http://www.foo.com/"
[browser] The browser's URL should contain "https:"
[browser] The browser's URL should not contain "https:"
[files] When I attach the file at "c:/foo/bar.exe" to "Your mugshot"
[JS] When I move the mouse over the div containing "more information"
[General] I should see an element with id of "cs_env_status"
[General] I should NOT see an element with id of "cs_env_status"
[General] The element with id of "cs_PageModeContainer" contains "Read" 
[General] The element with id of "cs_PageModeContainer" and NOT contains "Read"

Looking up fields

You may notice that the features seemed to read very wel.

When I fill in "Name" with "Brian Hogan"

The matcher for this step actually uses the label tag to locate the form. Here, we're specifying the label's text. We assume this code exists on the form:

<label for="user_name">Name</label>
<input type="text" id="user_name" name="user[name]" />

However, sometimes it's not that easy. Sometimes the form was coded wrong, or there's no matching label tag. So, these matchers support lookup by id

When I fill in "user_name" with "Brian Hogan"

Or by name

When I fill in "user[name]" with "Brian Hogan"

This works for buttons, select lists, checkboxes, and radio buttons.

Additionally, buttons can be found by their value.

When I press "Submit"

Read through the matchers. You'll learn tons.

Running stories

Run all of your feature stories with

rake cucumber

or just

rake

On Windows, it will use IE by default. On the Mac, it'll use Firefox. You can override this

rake cucumber BROWSER=firefox
rake cucumber BROWSER=chrome

Running a story

You can run a specific story with

rake cucumber FEATURE=features/twitter.feature

Safari users

Safariwatir is in a pretty sad state. It doesn't have the ability to

* find checkbox fields by label
* find fields by name with nested names (user[first_name])

as well as other things. Be aware of these limitations if you choose to use it. The default on Apple platforms is to use Firefox

Writing your own matchers

Matchers get written as regular expression matchers. Generally, steps you haven't created are presented to you when you run Cucumber. To implement the bodies of the steps, use the Watir API.

http://wtr.rubyforge.org/rdoc/

Place your steps in step_definitions/. The filename should be suffixed with _steps.rb. Don't add to the existing watir_steps file. Make your own.

Displaying steps

The rake task

rake steps

will display any steps available. To get your custom steps to show up, simply code a matcher and comment it with three hash marks and this task will parse it out for you.

This one will show up:

### [radio button] Then the "Remember me" option should be chosen
Then /^the "([^\"]*)" option should be chosen$/ do |field|
  field = find_radio(field)
  field.should be_checked
end

This one will not.

# Then the "Remember me" option should not be chosen
Then /^the "([^\"]*)" option should not be chosen$/ do |field|
  field = find_radio(field)
  field.should_not be_checked
end

The task simply finds all lines starting with ###. This way you can have other comments in your matcher files.

Project structure

features

- my_web_site.feature
- another_form.feature
- step_definitions
  - my_web_site_steps.rb
  - watir_steps.rb
- support
    - env.rb

License

Watir matchers copyright 2009 Brian Hogan Everything else is part of the Cucumber or Watir project All under the MIT license.

This package came from github.com/napcs/cucumber_watir

Other references: cukes.info/ wtr.rubyforge.org/rdoc/1.6.5/ github.com/jarib/watir-webdriver

Acknowledgements

This was based of the Cucumber samples. The Watir matchers are built by Brian Hogan

Something went wrong with that request. Please try again.