Gem Version Build Status Coverage Dependency Status Code Climate

test-page helps you to write easily maintainable integration tests by implementing Page Objects pattern.

Page Objects may be objects representing whole pages like LoginPage, ProfilePage or part of the pages like LoginForm, Header etc.

test-page can be described like:

  • Is framework agnostic - you can use it with any library you want - Watir, Selenium, Capybara etc.
  • Has really easy API - you can start testing right away instead of spending too much time to learn new framework.
  • Has really small codebase - even if you can't remember that small API you can dig right into the code - it's less than 100 lines!
  • Despite of its name you may use it with RSpec, Test::Unit or any other testing library.


Add this line to your application's Gemfile:

gem 'test-page'

And then execute:

$ bundle

Or install it yourself as:

$ gem install test-page


The following example uses Watir with RSpec, but you can use whichever library you like.

Check out Selenium example instead, if that's your flavor of choice.

This is the spec we are trying to run:

# spec/search_spec.rb
require "test/page"
require "watir"
require File.expand_path("search_page", File.dirname(__FILE__))

describe "Bing" do

  let(:browser)     { Watir::Browser.new }
  let(:search_page) { SearchPage.new }

  before { Test::Page.browser = browser }
  after  { browser.close }

  it "finds Google" do
    results_page = search_page.search "google"
    results_page.should have(10).results
    results_page.results[0].should =~ /google/i

  it "finds Bing itself" do
    results_page = search_page.search "bing"
    results_page.results.should be_any { |result| result =~ /Bing/ }

Let's create the SearchPage object:

# spec/support/page/search_page.rb
require File.expand_path("results_page", File.dirname(__FILE__))

class SearchPage < Test::Page
  element { browser.div(:id => "sbox") }

  def setup
    browser.goto "http://bing.com"

  def search(term)
    text_field(:id => "sb_form_q").set term
    button(:id => "sb_form_go").click
    redirect_to ResultsPage, browser.ul(:id => "wg0")

Let's create the ResultsPage object:

# spec/support/page/results_page.rb
class ResultsPage < Test::Page
  def results
    lis(:class => "sa_wr").map(&:text)

There you have it, a fully functional spec using two page objects. Reference to the API documentation for more usage information.


Copyright (c) Jarmo Pertman ([email protected]). See LICENSE for details.