Repository navigation
Tutorial
The examples in this tutorial will be using RSpec for the testing framework. However, any testing framework will do and should have similar configuration setup. You may need to take additional steps based on your framework of choice (e.g. cucumber scenarios & step definitions).
In your editor of choice, setup a new project with the following directory structure:

Update your Gemfile:
source 'https://rubygems.org' do
gem 'rspec'
gem 'huzzah'
gem 'watir-webdriver'
endNOTE: Although Huzzah is designed to be use with watir-webdriver, the two gems a decoupled. This allow you to choose the version of watir-webdriver that best suits your needs.
Perform a bundle install to get the gems.
Next, you will need create your Huzzah configuration. This should be done in the RSpec spec_helper.rb file.
require 'huzzah'
require 'watir-webdriver'
Huzzah.configure do |config|
config.path = "#{your_project_path}/lib/huzzah"
config.default_driver = ENV['BROWSER'] ||= 'firefox'
config.environment = ENV['AUTO_ENV'] ||= 'qa'
endSee Configuration for details about the path, default_driver & environment attributes.
See Defining Custom Drivers for more information about using a browser other than Firefox.
Add a file name bing_spec.rb under the spec directory and add the following code:
require_relative 'support/spec_helper'
describe 'Bing' do
before(:each) do
@role = Huzzah::Role.new
@role.browser.goto('http://bing.com')
end
after(:each) do
@role.browser.close
end
it 'performs keyword searches' do
@role.browser.text_field(id: 'sb_form_q').when_present.set('Huzzah')
@role.browser.button(id: 'sb_form_go').click
expect(@role.browser.link(href: 'https://en.wikipedia.org/wiki/Huzzah')).to be_present
end
endThe above example is a very simple, yet poorly implemented, test scenario. The first thing that needs to be addressed is the hard-coded watir locators. Let's take a look at Huzzah's implementation of the page-object model. Create a new file under your lib/huzzzah/pages driectory named bing_home_page.rb and add the following code:
module Bing
class HomePage < Huzzah::Page
locator(:search_box) { text_field(id: 'sb_form_q') }
locator(:search_button) { button(id: 'sb_form_go') }
end
endHuzzah uses a Module::Class pattern for organizing Sites & Pages. The module namespace, in this case Bing, is the Site. The class name (HomePage) is the Page. Your page-objects will inherit from the Huzzah::Page class, which gives you access to the locator method.
The locator method provides a shorthand way of defining and organizing how your test scenarios identify elements with the browser. It takes two arguments, a name and a block. The name is used to dynamically define a method with that name, which executes the block of code (the second argument).
For example, the locator:
locator(:search_box) { text_field(id: 'sb_form_q') }Is equivalent to:
def search_box
text_field(id: 'sb_form_q')
endLet's refactor our test scenario to use our new page-object:
require_relative 'support/spec_helper'
describe 'Bing' do
before(:each) do
@role = Huzzah::Role.new
@role.browser.goto('http://bing.com')
end
after(:each) do
@role.browser.close
end
it 'searches by keywords' do
@role.bing.home_page.search_box.when_present.set('Huzzah')
@role.bing.home_page.search_button.click
expect(@role.browser.link(href: 'https://en.wikipedia.org/wiki/Huzzah')).to be_present
end
endWith the addition of the page-object, the syntax now becomes role.site.page.element.action. At this point, it is important to note that we have done nothing but define a class. Huzzah 'wires things together' for you auto-magically. In fact, the only object you ever have to instantiate is the Huzzah::Role. In the above example, the bing and home_page methods are dynamically generated based on the module namespace and class name of your page object (converted to snake case).
Let's add a second page-object to represent the Bing search results. Create a new file named bing_search_results.rb under you 'pages' directory.
module Bing
class SearchResults < Huzzah::Page
locator(:wikipedia_result) { link(href: 'https://en.wikipedia.org/wiki/Huzzah') }
end
endThere are a few other important things to note about the locator method. First, within the block of code, you do not need to reference the browser. Huzzah knows that you are calling a method on the browser, which reduces boilerplate coding. Second, for clarity, Huzzah will NOT let you use a name for your locator that matches a name of any method found in the Watir::Container class (e.g. table, link, etc.). Lastly, the block of code can be used for anything (it's just Ruby code after all), but we highly recommend that you only use it for locating elements. If you need to do something else, write a method for it.
Let's update out Bing spec to use this new page-object:
it 'searches by keywords' do
@role.bing.home_page.search_box.when_present.set('Huzzah')
@role.bing.home_page.search_button.click
expect(@role.bing.search_results.wikipedia_result).to be_present
end