SitePrism

A Page Object Model DSL for Capybara

SitePrism gives you a simple, clean and semantic DSL for describing your site using the Page Object Model pattern, for use with Capybara in automated acceptance testing.

Find the pretty documentation here: https://rdoc.info/gems/site_prism/frames

Make sure to add your project/company to https://github.com/site-prism/site_prism/wiki/Who-is-using-SitePrism

Support

Support us with a monthly donation and help us continue our activities by supporting us as a backer

Become a sponsor and get your logo on our README on Github with a link to your site. How to Sponsor SitePrism?

Free Open Source software can only be maintained with the support of you. If you and/or your company find value in SitePrism and would like to contribute financially to its ongoing maintenance and development, then please do so. Visit the OpenCollective links above for more details.

Developing / Contributing to SitePrism

We love it when people want to get involved with our Open Source Project.

We have a brief set of setup docs HERE

Supported Rubies / Browsers

SitePrism is built and tested to work on Ruby 2.4 - 2.7. Ruby 2.4 (Now EOL), is supported but this version will be removed from the Support Matrix in the coming months. If you are using SitePrism with Ruby 2.4 it is highly advisable to upgrade to a more modern Ruby such as 2.7, if for any other reason, to get a noticeable speed boost!

SitePrism should run on all major browsers. The gem's integration tests are run on Chrome and Firefox.

If you find you cannot integrate nicely with SitePrism, please open an issue request

Synopsis

Here's an overview of how SitePrism is designed to be used:

# define our site's pages

class Home < SitePrism::Page
  set_url '/index.htm'
  set_url_matcher(/google.com/?/)
  element :search_field, 'input[name="q"]'
  element :search_button, 'button[name="btnK"]'
  elements :footer_links, '#footer a'
  section :menu, Menu, '#gbx3'
end
class SearchResults < SitePrism::Page
  set_url_matcher(/google.com/results?.*/)
  section :menu, Menu, '#gbx3'
  sections :search_results, SearchResults, '#results li'
  def search_result_links
    search_results.map { |result| result.title['href'] }
  end
end
define sections used on multiple pages or multiple times on one page
class Menu < SitePrism::Section
  element :search, 'a.search'
  element :images, 'a.image-search'
  element :maps, 'a.map-search'
end
class SearchResults < SitePrism::Section
  element :title, 'a.title'
  element :blurb, 'span.result-description'
end
now for some tests
When(/^I navigate to the google home page$/) do
  @home = Home.new
  @home.load
end
Then(/^the home page should contain the menu and the search form$/) do
  @home.wait_until_menu_visible # menu loads after a second or 2, give it time to arrive
  expect(@home).to have_menu
  expect(@home).to have_search_field
  expect(@home).to have_search_button
end
When(/^I search for Sausages$/) do
  @home.search_field.set 'Sausages'
  @home.search_button.click
end
Then(/^the search results page is displayed$/) do
  @results_page = SearchResults.new
  expect(@results_page).to be_displayed
end
Then(/^the search results page contains 10 individual search results$/) do
  @results_page.wait_until_search_results_visible
  expect(@results_page).to have_search_results(count: 10)
end
Then(/^the search results contain a link to the wikipedia sausages page$/) do
  expect(@results_page.search_result_links).to include('http://en.wikipedia.org/wiki/Sausage')
end

Now for the details...

Setup

Installation

To install SitePrism:

gem install site_prism

Using SitePrism with Cucumber

If you are using cucumber, here's what needs requiring:

require 'capybara'
require 'capybara/cucumber'
require 'selenium-webdriver'
require 'site_prism'
require 'site_prism/all_there' # Optional but needed to perform more complex matching

The driver creation is identical to how you would normally create a Capybara driver, a sample Selenium one could look something like this...

Capybara.register_driver :site_prism do |app|
  browser = ENV.fetch('browser', 'firefox').to_sym
  Capybara::Selenium::Driver.new(app, browser: browser, desired_capabilities: capabilities)
end

Then tell Capybara to use the Driver you've just defined as its default driver
Capybara.configure do |config|
  config.default_driver = :site_prism
end

Using SitePrism with RSpec

If you're using rspec instead, here's what needs requiring:

require 'capybara'
require 'capybara/rspec'
require 'selenium-webdriver'
require 'site_prism'
require 'site_prism/all_there' # Optional but needed to perform more complex matching

And again, as above, a sample driver is no different to a normal driver instantiation in Capybara.

Introduction to the Page Object Model

The Page Object Model is a test automation pattern that aims to create an abstraction of your site's user interface that can be used in tests. The most common way to do this is to model each page as a class, and to then use instances of those classes in your tests.

If a class represents a page then each element of the page is represented by a method that, when called, returns a reference to that element that can then be acted upon (clicked, set text value), or queried (is it enabled? / visible?).

SitePrism is based around this concept, but goes further as you'll see below by also allowing modelling of repeated sections that appear on multiple pages, or many times on a page using the concept of sections.

Pages

As you might be able to guess from the name, pages are fairly central to the Page Object Model. Here's how SitePrism models them:

Creating your first Page using the Page Object Model

The simplest page is one that has nothing defined in it. Here's an example of how to begin modelling a home page:

class Home < SitePrism::Page
end

The above has nothing useful defined, so to start with lets give it some properties.

Adding a URL

A page usually has a URL. If you want to be able to navigate to a page, you'll need to set its URL. Here's how:

class Home < SitePrism::Page
  set_url 'http://www.mysite.com/home.htm'
end

If you've set Capybara's

app_host

class Home < SitePrism::Page
  set_url '/home.htm'
end

Note that setting a URL is optional - you only need to set a url if you want to be able to navigate directly to that page. It makes sense to set the URL for a page model of a home page or a login page, but probably not a search results page.

Parametrized URLs

SitePrism uses the

addressable

class UserProfile < SitePrism::Page
  set_url '/users{/username}'
end

...and a more complex example:

class Search < SitePrism::Page
  set_url '/search{?query*}'
end

See https://github.com/sporkmonger/addressable for more details on parameterized URLs.

Navigating to the Page

Once the URL has been set (using

set_url

#load

@home_page = Home.new
@home_page.load

Navigating to a page with a parameterized URL

The

#load

class UserProfile < SitePrism::Page
  set_url '/users{/username}'
end

@user_profile = UserProfile.new
@user_profile.load #=> /users
@user_profile.load(username: 'bob') #=> loads /users/bob

...and...

class Search < SitePrism::Page
  set_url '/search{?query*}'
end

@search = Search.new
@search.load(query: 'simple') #=> loads /search?query=simple
@search.load(query: {'color'=> 'red', 'text'=> 'blue'}) #=> loads /search?color=red&text=blue

This will tell whichever capybara driver you have configured to navigate to the URL set against that page's class.

See https://github.com/sporkmonger/addressable for more details on parameterized URLs.

Verifying that a particular page is displayed

Automated tests often need to verify that a particular page is displayed. SitePrism can automatically parse your URL template and verify that whatever components your template specifies match the currently viewed page. For example, with the following URL template:

class Account < SitePrism::Page
  set_url '/accounts/{id}{?query*}'
end

The following test code would pass:

@account_page = Account.new
@account_page.load(id: 22, query: { token: 'ca2786616a4285bc' })

expect(@account_page.current_url).to end_with('/accounts/22?token=ca2786616a4285bc')
expect(@account_page).to be_displayed

Calling

#displayed?

Capybara.default_max_wait_time

@account_page.displayed?(10) # wait up to 10 seconds for display

Specifying parameter values for templated URLs

Sometimes you want to verify not just that the current URL matches the template, but that you're looking at a specific page matching that template.

Given the previous example, if you wanted to ensure that the browser had loaded account number 22, you could assert the following:

expect(@account_page).to be_displayed(id: 22)

You can even use regular expressions. If for example, you wanted to ensure that the browser was displaying an account with an id ending with 2, you could do:

expect(@account_page).to be_displayed(id: /2\z/)

Accessing specific matches from a templated URL in your tests

If passing options to

displayed?

url_matches

@account_page = Account.new
@account_page.load(id: 22, query: { token: 'ca2786616a4285bc', color: 'irrelevant' })

expect(@account_page).to be_displayed(id: 22)
expect(@account_page.url_matches['query']['token']).to eq('ca2786616a4285bc')

Falling back to basic regexp matchers

If SitePrism's built-in URL matching is not sufficient for your needs you can override and use SitePrism's previous support for regular expression-based URL matchers by it by calling

set_url_matcher

class Account < SitePrism::Page
  set_url_matcher(/accounts/\d+/)
end

Testing for Page display

SitePrism's

#displayed?

Then(/^the account page is displayed$/) do
  expect(@account_page).to be_displayed
  expect(@some_other_page).not_to be_displayed
end

Getting the Current Page's URL

SitePrism allows you to get the current page's URL. Here's how it's done:

class Account < SitePrism::Page
end

@account = Account.new
@account.current_url #=> "http://www.example.com/account/123"
expect(@account.current_url).to include('example.com/account/')

Page Title

Getting a page's title isn't hard:

class Account < SitePrism::Page
end

@account = Account.new
@account.title #=> "Welcome to Your Account"

HTTP vs. HTTPS

You can easily tell if the page is secure or not by checking to see if the current URL begins with 'https' or not. SitePrism provides the

secure?

class Account < SitePrism::Page
end

@account = Account.new
@account.secure? #=> true/false
expect(@account).to be_secure

Elements

Pages are made up of elements (text fields, buttons, combo boxes, etc), either individual elements or groups of them. Examples of individual elements would be a search field or a company logo image; examples of element collections would be items in any sort of list, eg: menu items, images in a carousel, etc.

Individual Elements

To interact with individual elements, they need to be defined as part of the relevant page. SitePrism makes this easy:

class Home < SitePrism::Page
  element :search_field, 'input[name="q"]'
end

Here we're adding a search field to the Home page. The

element

Accessing the individual element

The

element

class Home < SitePrism::Page
  set_url 'http://www.google.com'

  element :search_field, 'input[name="q"]'
end

... the following shows how to get hold of the search field:

@home = Home.new
@home.load

@home.search_field #=> will return the capybara element found using the selector
@home.search_field.set 'the search string' #=> search_field returns a capybara element, so use the capybara API to deal with it
@home.search_field.text #=> standard method on a capybara element; returns a string

Testing for the existence of the element

Another method added to the Page class by the

element

has_?

class Home < SitePrism::Page
  set_url 'http://www.google.com'

  element :search_field, 'input[name="q"]'
end

... you can test for the existence of the element on the page like this:

@home = Home.new
@home.load
@home.has_search_field? #=> returns true if it exists, false if it doesn't

...which makes for nice test code:

Then(/^the search field exists$/) do
  expect(@home).to have_search_field
end

Testing that an element does not exist

To test that an element does not exist on the page, it is not possible to just call

#not_to have_search_field

#has_no_?

@home = Home.new
@home.load
@home.has_no_search_field? #=> returns true if it doesn't exist, false if it does

...which makes for nice test code:

Then(/^the search field exists$/)do
  expect(@home).to have_no_search_field #NB: NOT => expect(@home).not_to have_search_field
end

Waiting for an element to become visible

A method that gets added by calling

element

wait_until__visible

@home.wait_until_search_field_visible
# or...
@home.wait_until_search_field_visible(wait: 10)

Waiting for an element to become invisible

Another method added by calling

element

wait_until__invisible

@home.wait_until_search_field_invisible
# or...
@home.wait_until_search_field_invisible(wait: 10)

CSS Selectors vs. XPath Expressions

While the above examples all use CSS selectors to find elements, it is possible to use XPath expressions too. In SitePrism, everywhere that you can use a CSS selector, you can use an XPath expression.

An example:

class Home < SitePrism::Page
  # CSS Selector
  element :first_name, 'div#signup input[name="first-name"]'

Identical selector as an XPath expression
  element :first_name, :xpath, '//div[@id="signup"]//input[@name="first-name"]'
end

Summary of what the element method provides:

Given:

class Home < SitePrism::Page
  element :search_field, 'input[name="q"]'
end

Then the following methods are available:

@home.search_field
@home.has_search_field?
@home.has_no_search_field?
@home.wait_until_search_field_visible
@home.wait_until_search_field_invisible

Element Collections

Sometimes you don't want to deal with an individual element but rather with a collection of similar elements, for example, a list of names. To enable this, SitePrism provides the

elements

class Friends < SitePrism::Page
  elements :names, 'ul#names li a'
end

Just like the

element

elements

Accessing the elements

Just like the

element

elements

class Friends < SitePrism::Page
  elements :names, 'ul#names li a'
end

You can access the element collection like this:

@friends_page = Friends.new
# ...
@friends_page.names #=> [<:element>, <:element>, <:element>]

With that you can do all the normal things that are possible with arrays:

@friends_page.names.each { |name| puts name.text }
@friends_page.names.map { |name| name.text }

Or even run some tests ...

expect(@friends_page.names.map { |name| name.text }).to eq(['Alice', 'Bob', 'Fred'])
expect(@friends_page.names.size).to eq(3)

Testing for the existence of the element collection

Just like the

element

elements

has_?

true

false

class Friends < SitePrism::Page
  elements :names, 'ul#names li a'
end

Then the following method is available:

@friends_page.has_names? #=> returns true if at least one `name` element is found

This in turn allows the following nice test code

Then(/^there should be some names listed on the page$/) do
  expect(@friends_page).to have_names #=> This only passes if there is at least one `name`
end

Waiting for the elements to be visible or invisible

Like an individual element, calling the

elements

wait_until__visible

wait_until__invisible

@friends_page.wait_until_names_visible
# and...
@friends_page.wait_until_names_invisible

It is possible to wait for a specific amount of time instead of using the default Capybara wait time:

@friends_page.wait_until_names_visible(wait: 5)
# and...
@friends_page.wait_until_names_invisible(wait: 7)

Checking that all mapped elements are present on the page

Throughout my time in test automation I keep getting asked to provide the ability to check that all elements that should be on the page are on the page. Why people would want to test this, I don't know. But if that's what you want to do, SitePrism provides the

#all_there?

true

false

@friends_page.all_there? #=> true/false

and...
Then(/^the friends page contains all the expected elements$/) do
  expect(@friends_page).to be_all_there
end

You may wish to have elements declared in a page object class that are not always guaranteed to be present (success or error messages, etc.). If you'd still like to test such a page with

all_there?

expected_elements

all_there?

class TestPage < SitePrism::Page
  element :name_field, '#name'
  element :address_field, '#address'
  element :success_message, 'span.alert-success'

  expected_elements :name_field, :address_field
end

And if you aren't sure which elements will be present, Then ask SitePrism to tell you!

class TestPage < SitePrism::Page
  element :name_field, '#name'
  element :address_field, '#address'
  element :success_message, 'span.alert-success'
end

and... Only address_field is on the page
@test_page.elements_present #=> [:address_field]

If you are specifying a highly nested set of sections inside a Page and need to recurse through them to find out if all of your items are present then you can also do this.

Simply pass a recursion parameter to the

#all_there?

:none

:one

Passing

:none

:one

site_prism

section

sections

Work alongside developing this functionality further is being continued in the siteprism-allthere repo. So head on over there if you're interested in how this feature will work going forwards

NB: At the moment a "primitive" but working copy of this is hosted inside this gem. But if you wish to use the bleeding edge version of the logic. Then simply set the following configuration parameter

`require 'site_prism/all_there'`

SitePrism.use_all_there_gem = true

Getting the list of missing elements

If

#all_there?

#elements_missing

If you do not provide a list of

expected_elements

class Home < SitePrism::Page
  element :name, '#name'
  element :address, '#address'
  element :success_message, 'span.alert-success'

  expected_elements :name, :address
end
and... Only address is on the page
@test_page.elements_missing #=> [:name]

Sections

SitePrism allows you to model sections of a page that appear on multiple pages or that appear a number of times on a page separately from Pages. SitePrism provides the Section class for this task.

Individual Sections

In the same way that SitePrism provides

element

elements

section

sections

section

Defining a Section

A section is similar to a page in that it inherits from a SitePrism class:

class Menu < SitePrism::Section
end

At the moment, this section does nothing.

Adding a section to a page

Pages include sections that's how SitePrism works. Here's a page that includes the above

Menu

class Home < SitePrism::Page
  section :menu, Menu, '#gbx3'
end

The way to add a section to a page (or another section - which is possible) is to call the

section

You can define a section as a class and/or an Anonymous section. This will then allow you to have some handy constructs like the one below

class People < SitePrism::Section
  element :footer, 'h4'
end

class Home < SitePrism::Page
section people_with_block will have headline and
footer elements in it
  section :people_with_block, People do
    element :headline, 'h2'
  end
end

The 3rd argument (Locators), can be omitted if you are re-using the same locator for all references to the section Class. In order to do this, simply tell SitePrism that you want to use default search arguments.

class People < SitePrism::Section
  set_default_search_arguments '.people'
end

class Home < SitePrism::Page
  section :people, People
end

Accessing a Page's section

The

section

element

section

# the section

class Menu < SitePrism::Section
end
the page that includes the section
class Home < SitePrism::Page
  section :menu, Menu, '#gbx3'
end
the page and section in action
@home = Home.new
@home.menu #=> <menusection...>
</menusection...>

When the

menu

@home

Menu

section

section

The following shows that though the same section can appear on multiple pages, it can take a different root node:

# define the section that appears on both pages

class Menu < SitePrism::Section
end
define 2 pages, each containing the same section
class Home < SitePrism::Page
  section :menu, Menu, '#gbx3'
end
class SearchResults < SitePrism::Page
  section :menu, Menu, '#gbx48'
end

You can see that the

Menu

Home

SearchResults

Menu

Adding elements to a section

This works just the same as adding elements to a page:

class Menu < SitePrism::Section
  element :search, 'a.search'
  element :images, 'a.image-search'
  element :maps, 'a.map-search'
end

Note that the locators used to find elements are searched for within the scope of the root element of that section. The search for the element won't be page-wide but it will only look in the section.

When the section is added to a page ...

class Home < SitePrism::Page
  section :menu, Menu, '#gbx3'
end

...then the section's elements can be accessed like this:

@home = Home.new
@home.load

@home.menu.search #=> returns a capybara element representing the link to the search page
@home.menu.search.click #=> clicks the search link in the home page menu
@home.menu.search['href'] #=> returns the value for the href attribute of the capybara element representing the search link
@home.menu.has_images? #=> returns true or false based on whether the link is present in the section on the page
@home.menu.wait_until_images_visible #=> waits for capybara's default wait time until the element is visible in the page section

This then leads to some pretty test code ...

Then(/^the home page menu contains a link to the various search functions$/) do
  expect(@home.menu).to have_search
  expect(@home.menu.search['href']).to include('google.com')
  expect(@home.menu).to have_images
  expect(@home.menu).to have_maps
end

Accessing section elements using a block

You can execute a block within the context of a Section. This is similar to Capybara's

within

Then(/^the home page menu contains a link to the various search functions$/) do
  @home.menu.within do |menu|
    expect(menu).to have_search
    expect(menu.search['href']).to include('google.com')
    expect(menu).to have_images
    expect(menu).to have_maps
  end
end

Note that on an individual section it's possible to pass a block directly to the section without using

within

Section

within

Then(/^the home page menu contains a link to the various search functions$/) do
  @home.menu do |menu|  # possible, but prefer: `@home.menu.within`
    expect(menu).to have_search
  end
end

Getting a section's parent

It is possible to ask a section for its parent (page, or section if this section is a subsection). For example, given the following setup:

class DestinationFilters < SitePrism::Section
  element :morocco, 'abc'
end

class FilterPanel < SitePrism::Section
  section :destination_filters, DestinationFilters, 'def'
end
class Home < SitePrism::Page
  section :filter_panel, FilterPanel, 'ghi'
end

Then calling

#parent

@home = Home.new
@home.load

@home.filter_panel.parent #=> returns @home
@home.filter_panel.destination_filters.parent #=> returns @home.filter_panel

Getting a section's parent page

It is possible to ask a section for the page that it belongs to. For example, given the following setup:

class Menu < SitePrism::Section
  element :search, 'a.search'
  element :images, 'a.image-search'
  element :maps, 'a.map-search'
end

class Home < SitePrism::Page
  section :menu, Menu, '#gbx3'
end

...you can get the section's parent page:

@home = Home.new
@home.load
@home.menu.parent_page #=> returns @home

Testing for the existence of a section

Just like elements, it is possible to test for the existence of a section. The

section

has_
?

has_?

class Menu < SitePrism::Section
  element :search, 'a.search'
  element :images, 'a.image-search'
  element :maps, 'a.map-search'
end

class Home < SitePrism::Page
  section :menu, Menu, '#gbx3'
end

You can check whether the section is present on the page or not:

@home = Home.new
#...
@home.has_menu? #=> returns true or false

Again, this allows pretty test code:

expect(@home).to have_menu
expect(@home).not_to have_menu

Waiting for a section to become visible or invisible

Like an element, it is possible to wait for a section to become visible or invisible. Calling the

section

wait_until__visible

wait_until__invisible

@home = Home.new
@home.wait_until_menu_visible
# and...
@home.wait_until_menu_invisible

Again, as for an element, it is possible to give a specific amount of time to wait for visibility/invisibility of a section. Here's how:

@home = Home.new
@home.wait_until_menu_visible(wait: 5)
# and...
@home.wait_until_menu_invisible(wait: 3)

Sections within sections

You are not limited to adding sections only to pages; you can nest sections within sections within sections within sections!

# define a page that contains an area that contains a section for both
# logging in and registration. Modelling each of the sub-sections separately

class Login < SitePrism::Section
  element :username, '#username'
  element :password, '#password'
  element :sign_in, 'button'
end
class Registration < SitePrism::Section
  element :first_name, '#first_name'
  element :last_name, '#last_name'
  element :next_step, 'button.next-reg-step'
end
class LoginRegistrationForm < SitePrism::Section
  section :login, Login, 'div.login-area'
  section :registration, Registration, 'div.reg-area'
end
class Home < SitePrism::Page
  section :login_and_registration, LoginRegistrationForm, 'div.login-registration'
end
how to login (fatuous, but demonstrates the point):
Then(/^I sign in$/) do
  @home = Home.new
  @home.load
  expect(@home).to have_login_and_registration
  expect(@home.login_and_registration).to have_username
  @home.login_and_registration.login.username.set 'bob'
  @home.login_and_registration.login.password.set 'p4ssw0rd'
  @home.login_and_registration.login.sign_in.click
end
how to sign up:
When(/^I enter my name into the home page's registration form$/) do
  @home = Home.new
  @home.load
  expect(@home.login_and_registration).to have_first_name
  expect(@home.login_and_registration).to have_last_name
  @home.login_and_registration.first_name.set 'Bob'
...
end

Anonymous Sections

If you want to use a section more as a namespace for elements and are not planning on re-using it, you may find it more convenient to define an anonymous section using a block:

class Home < SitePrism::Page
  section :menu, '.menu' do
    element :title, '.title'
    elements :items, 'a'
  end
end

This code will create an anonymous section that you can use in the same way as an ordinary section:

@home = Home.new
expect(@home.menu).to have_title

Section Collections

An individual section represents a discrete section of a page, but often sections are repeated on a page, an example is a search result listing - each listing contains a title, a url and a description of the content. It makes sense to model this only once and then to be able to access each instance of a search result on a page as an array of SitePrism sections. To achieve this, SitePrism provides the

sections

The only difference between

section

sections

Adding a Section collection to a page (or other section)

Given the following setup:

class SearchResults < SitePrism::Section
  element :title, 'a.title'
  element :blurb, 'span.result-description'
end

class Home < SitePrism::Page
  sections :search_results, SearchResults, '#results li'
end

It is possible to access each of the search results:

@home = Home.new
# ...
@home.search_results.each do |result|
  puts result.title.text
end

This allows for pretty tests ...

Then(/^there are lots of search_results$/) do
  expect(@results_page.search_results.size).to eq(10)

  @home.search_results.each do |result|
    expect(result).to have_title
    expect(result.blurb.text).not_to be_empty
  end
end

The css selector that is passed as the 3rd argument to the

sections

#results li

SearchResults

li

search_results

SearchResults

li

Accessing Within a Collection of Sections

When using an iterator such as

each

within

  @home.search_results.first do |result|
    # This block is silently ignored.
    expect(result).to have_title
  end

Instead use

within

  @home.search_results.first.within do |result|
    # This block is run within the context of the Section.
    expect(result).to have_title
  end

Anonymous Section Collections

You can define collections of anonymous sections the same way you would define a single anonymous section:

class Home < SitePrism::Page
  sections :search_results, '#results li' do
    element :title, 'a.title'
    element :blurb, 'span.result-description'
  end
end

Testing for existence of Sections

Using the example above, it is possible to test for the existence of the sections. As long as there is at least one section in the array, the sections item is said to exist. The

sections

has_?

So given the example below, we can do the following ...

class SearchResults < SitePrism::Section
  element :title, 'a.title'
  element :blurb, 'span.result-description'
end

class Home < SitePrism::Page
  sections :search_results, SearchResults, '#results li'
end

Here's how to test for the existence of the section:

@home = Home.new
# ...
@home.has_search_results? #=> Only returns `true` if there is 1 or more results

This allows for some pretty tests ...

Then(/^there are search results on the page$/) do
  expect(@home).to have_search_results
end

Waiting for sections to appear/disappear

The last methods added by

sections

wait_until__visible

wait_until__invisible

For example:

class SearchResults < SitePrism::Section
  element :title, 'a.title'
  element :blurb, 'span.result-decription'
end

class Home < SitePrism::Page
  sections :search_results, SearchResults, '#results li'
end

... here's how to wait for one the section items to become visible:

@home = Home.new
# ...
@home.wait_until_search_results_visible
@home.wait_until_search_results_visible(wait: 3) #=> waits for 3 seconds instead of the default capybara timeout

... and how to wait for the sections to disappear

@home = Home.new
# ...
@home.wait_until_search_results_invisible
@home.wait_until_search_results_invisible(wait: 6) #=> waits for 6 seconds instead of the default capybara timeout

Load Validations

Load validations enable common validations to be abstracted and performed on a Page or Section to determine when it has finished loading and is ready for interaction in your tests.

For example, suppose you have a page which displays a 'Loading...' message while the body of the page is loaded in the background. Load validations can be used to ensure tests wait for the correct url to be displayed and the loading message is no longer present before trying to interact with the page.

Other use cases include Sections which are displayed conditionally and may take time to become ready to interact with, such as animated lightboxes.

Using Load Validations

Load validations can be used in three constructs:

• Passing a block to

  Page#load

• Passing a block to

  Loadable#when_loaded

• Calling

  Loadable#loaded?

Page#load

When a block is passed to the

Page#load

when_loaded

when_loaded

Example:

# Load the page and then execute a block after all load validations pass:
my_page_instance.load do |page|
  page.do_something
end

Loadable#when_loaded

The

Loadable#when_loaded

If any load validation fails, an error will be raised with the reason, if given, for the failure.

Example:

# Execute a block after all load validations pass:
a_loadable_page_or_section.when_loaded do |loadable|
  loadable.do_something
end

Loadable#loaded?

You can explicitly run load validations on a Loadable via the

loaded?

load_error

Example:

it 'loads the page' do
  some_page.load
  some_page.loaded?    #=> true if/when all load validations pass
  another_page.loaded? #=> false if any load validations fail
  another_page.load_error #=> A string error message if one was supplied by the failing load validation, or nil
end

Defining Load Validations

A load validation is a block which returns a boolean value when evaluated against an instance of the Page or Section where defined.

class SomePage < SitePrism::Page
  element :foo_element, '.foo'
  load_validation { has_foo_element? }
end

The block may be defined as a two-element array which includes the boolean check as the first element and an error message as the second element. It is highly recommended to supply an error message, as they are extremely useful in debugging validation errors.

The error message is ignored unless the boolean value is evaluated as falsey.

class SomePage < SitePrism::Page
  element :foo_element, '.foo'
  load_validation { [has_foo_element?, 'did not have foo element!'] }
end

Load validations may be defined on

SitePrism::Page

SitePrism::Section

Loadables

Skipping load Validations

Defined load validations can be skipped for one

load

with_validations: false

it 'loads the page without validations' do
  some_page.load(with_validations: false)
  some_page.loaded?    #=> true unless something has gone wrong
end

Load Validation Inheritance and Execution Order

Any number of load validations may be defined on a Loadable and they are inherited by its subclasses (if any exist).

Load validations are executed in the order that they are defined. Inherited load validations are executed from the top of the inheritance chain (e.g.

SitePrism::Page

SitePrism::Section

For example:

class BasePage < SitePrism::Page
  element :loading_message, '.loader'

  load_validation do
    [has_no_loading_message?(wait: 10), 'loading message was still displayed']
  end
end
class FooPage < BasePage
  set_url '/foo'
  section :form, '#form'
  element :some_other_element, '.myelement'
  load_validation { [has_form?, 'form did not appear'] }
  load_validation { [has_some_other_element?, 'some other element did not appear'] }
end

In the above example, when

loaded?

FooPage

1. The

   BasePage

   validation will wait for the loading message to disappear.
2. The

   FooPage

   validation will wait for the

   form

   element to be present.
3. The

   FooPage

   validation will wait for the

   some_other_element

   element to be present.

NB:

SitePrism::Page

page.displayed?

Using Capybara Query Options

When querying an element, section or a collection of elements or sections, you may supply Capybara query options as arguments to the element and section methods in order to refine the results of the query and enable Capybara to wait for all of the conditions necessary to properly fulfill your request.

Given the following sample page and elements:

class SearchResults < SitePrism::Section
  element :title, 'a.title'
  element :blurb, 'span.result-decription'
end

class Home < SitePrism::Page
  element :footer, '.footer'
  sections :search_results, SearchResults, '#results li'
end

Asserting the attributes of an element or section returned by any method may fail if the page has not finished loading the section(s):

@home = Home.new
# ...
expect(@home.search_results.size).to == 25 # This may fail!

The above query can be rewritten to utilize the Capybara

:count

@home = Home.new
@home.has_search_results?(count: 25)
# OR
@home.search_results(count: 25)

Now we can write pretty, non-failing tests without hard coding these options into our page and section classes:

Then(/^there are search results on the page$/) do
  expect(@results_page).to have_search_results(count: 25)
end

This is supported for all of the Capybara options including, but not limited to

:count

:text

class Home < SitePrism::Page
  element :footer, '.footer'
  element :view_more, 'li', text: 'View More'
  sections :search_results, SearchResults, '#results li', count: 5
end

Methods Supporting Capybara Options

The following element methods allow Capybara options to be passed as arguments to the method:

@results_page.(text: 'Welcome!')
@results_page.has_?(count: 25)
@results_page.has_no_?(text: 'Logout')
@results_page.wait_until__visible(text: 'Some ajaxy text appears!')
@results_page.wait_until__invisible(text: 'Some ajaxy text disappears!')

Test views with Page objects

It's possible to use the same page objects of integration tests for view tests, too, just pass the rendered HTML to the

load

require 'spec_helper'

describe 'admin/things/index' do
  let(:list_page) { AdminThingsListPage.new }
  let(:thing) { build(:thing, some_attribute: 'some attribute') }
  it 'contains the things we expect' do
    assign(:things, [thing])
render template: 'admin/things/index'

list_page.load(rendered)

expect(list_page.rows.first.some_attribute).to have_text('some attribute')
  end
end

iFrames

SitePrism allows you to interact with iframes. An iframe is declared as a

SitePrism::Page

Creating an iFrame

An iframe is declared in the same way as a Page:

class MyIframe < SitePrism::Page
  element :some_text_field, 'input.username'
end

To expose the iframe, reference it from another page or class using the

iframe

iframe

class PageContainingIframe < SitePrism::Page
  iframe :my_iframe, MyIframe, '#my_iframe_id'
end

Locating an iFrame

While the above example uses a CSS selector to find the iframe, it is also possible to use an XPath expression or the index of the iframe in its parent (a shortcut for an

nth-of-type

class PageContainingIframe < SitePrism::Page
  # XPath Expression:
  iframe :my_iframe, MyIframe, :xpath, '//iframe[@id="my_iframe_id"]'

Index (nth-of-type) Selector:
  iframe :my_iframe, MyIframe, 0
end

Testing for an iframe's existence

Like an element or section, it is possible to test for an iframe's existence using the auto-generated

has_?

@page = PageContainingIframe.new
# ...
@page.has_my_iframe? #=> true
expect(@page).to have_my_iframe

Interacting with an iframe's contents:

Since an iframe contains a fully fledged

SitePrism::Page

SitePrism::Page

# SitePrism::Page representing the iframe
class LoginFrame < SitePrism::Page
  element :username, 'input.username'
  element :password, 'input.password'
end

SitePrism::Page representing the page that contains the iframe
class Home < SitePrism::Page
  set_url 'http://www.example.com'
  iframe :login_frame, LoginFrame, '#login_and_registration'
end
cucumber step that performs login
When(/^I log in$/) do
  @home = Home.new
  @home.load
  @home.login_frame do |frame|
    #frame is an instance of the LoginFrame class
    frame.username.set 'admin'
    frame.password.set 'p4ssword'
  end
end

SitePrism Configuration

SitePrism can be configured to change its behaviour.

For each of the following configuration options, either add it in the

spec_helper.rb

env.rb

Using Capybara Implicit Waits

By default, SitePrism element and section methods utilize Capybara's implicit wait methodology and will return only once the shorter of the Capybara timeout limit has been reached or the required query has passed.

If you want to tweak the waiting time or disable it completely, configure it as per the code below

Capybara.configure do |config|
  config.default_max_wait_time = 11 #=> Wait up to 11 seconds for all queries to fail
  # or if you don't want to ever wait
  config.default_max_wait_time = 0 #=> Don't ever wait!
end

Note that even with implicit waits on you can dynamically modify the wait times in any SitePrism method to help work-around special circumstances.

# Option 1: using wait key assignment
@home.search_results(wait: 20) # will wait up to 20 seconds

Option 2: using Capybara directly, this will wait up to 20 seconds
Capybara.using_wait_time(20) do
  @home.search_results
end

Using SitePrism with VCR

There's a SitePrism plugin called

site_prism.vcr

Note that as of 2016 this plugin doesn't appear to have been under active development. Also it is still pinned to the

2.x

Epilogue

So, we've seen how to use SitePrism to put together page objects made up of pages, elements, sections and iframes. But how to organise this stuff? There are a few ways of saving yourself having to create instances of pages all over the place. Here's an example of this common problem:

@home = Home.new # 
The annoyance (and, later, maintenance nightmare) is having to create
@home
 and 
@results_page
. It would be better to not have to create
instances of pages all over your tests.

The way I've dealt with this problem is to create a class containing
methods that return instances of the pages. Eg:
# our pages

class Home < SitePrism::Page
  #...
end
class SearchResults < SitePrism::Page
  #...
end
class Maps < SitePrism::Page
  #...
end
here's the app class that represents our entire site:
class App
  def home
    Home.new
  end
  def results_page
    SearchResults.new
  end
  def maps
    Maps.new
  end
end
and here's how to use it
#first line of the test...
Given(/^I start on the home page$/) do
  @app = App.new
  @app.home.load
end
When(/^I search for Sausages$/) do
  @app.home.search_field.set 'Sausages'
  @app.home.search_button.click
end
Then(/^I am on the results page$/) do
  expect(@app.results_page).to be_displayed
end
etc...

The only thing that needs instantiating is the 
App
 class - from then on
pages don't need to be initialized, they are now returned by methods on 
@app
.

It is possible to further optimise this, by using Cucumber/RSpec hooks, amongst
other things. However the investigation and optimisation of this (and other
aspects of SitePrism), is left as an exercise to the Reader.

Happy testing from all of the SitePrism team!