SitePrism A Page Object Model DSL for Capybara SitePrism gives you a simple, clean and semantic DSL for describing your site using the Page…
SitePrism A Page Object Model DSL for Capybara SitePrism gives you a simple, clean and semantic DSL for describing your site using the Page…
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://www.rubydoc.info/github/site-prism/site_prism
Make sure to add your project/company to https://github.com/site-prism/site_prism/wiki/Who-is-using-SitePrism
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.
We love it when people want to get involved with our Open Source Project.
We have a brief set of contribution documents HERE
SitePrism is built and tested to work on Ruby 3.1 - 4.0
If you are using SitePrism with Ruby 3.1 it is highly advisable to upgrade to a more modern Ruby (v3.3+), if for any other reason, to get a performance improvement!
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
Here's an overview of how SitePrism is designed to be used:
# define our site's pages
class Home /users
@user_profile.load(username: 'bob') #=> loads /users/bob...and...
class Search loads /search?query=simple
@search.load(query: {'color'=> 'red', 'text'=> 'blue'}) #=> loads /search?color=red&text=blueThis will tell whichever capybara driver you have configured to navigate to the URL set against that page's class.
Automated tests often need to verify that a particular page is displayed. SitePrism can automatically parse your templated URL and verify that whatever components your template specifies match the currently viewed page. For example, with the following URL template:
class Account "http://www.example.com/account/123"
expect(@account.current_url).to include('example.com/account/')Getting a page's title isn't hard:
class Account "Welcome to Your Account"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? method that will return true if the current url begins with 'https' and false if it doesn't.
For example:
class Account true/false
expect(@account).to be_securePages 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.
To interact with individual elements, they need to be defined as part of the relevant page. SitePrism makes this easy:
class Home will return the capybara element found using the selector
@home.search_field.send_keys('the search string')
@home.search_field['value'] #=> standard method on a capybara element (field); returns the string valueAnother method added to the Page class by the element method is the
has_? method.
This method delegates to Capybara::Node::Matchers#has_selector?.
Using the same example as above:
class Home 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
endTo test that an element does not exist on the page, you should not call
#not_to have_search_field. SitePrism supplies the #has_no_? method
that should be used instead to test for non-existence.
This method delegates to Capybara::Node::Matchers#has_no_selector?
Using the above example:
@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 THE SAME AS => expect(@home).not_to have_search_field
endA method that gets added by calling element is the wait_until__visible method.
This method delegates to Capybara::Node::Matchers#has_selector?.
Calling this method will cause the test to wait for Capybara's default wait time for the element to become visible. You can customise
the wait time by supplying a number of seconds to wait in-line or configuring the default wait time.
@home.wait_until_search_field_visible # using the default wait time set
# or...
@home.wait_until_search_field_visible(wait: 10)Another method added by calling element is the wait_until__invisible method.
This method delegates to Capybara::Node::Matchers#has_no_selector?.
Calling this method will cause the test to wait for Capybara's default wait time for the element to become invisible.
You can (as with the visibility waiter), customise the wait time in the same way.
@home.wait_until_search_field_invisible # using the default wait time set
# or...
@home.wait_until_search_field_invisible(wait: 10)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 (Standard Capybara logic).
An example:
class Home [, , ]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)Just like the element method, the elements method adds a method to
the page that will allow you to check for the existence of the
collection, called has_?. As long as there is
at least 1 element in the array, the method will return true, otherwise
it wil return false. For example, with the following page:
class Friends returns true if at least one `name` element is foundThis 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`
endLike an individual element, calling the elements method will create
two methods: wait_until__visible and
wait_until__invisible. Calling these methods will cause
your test to wait for the elements to become visible or invisible. Using
the above example:
@friends_page.wait_until_names_visible
# and...
@friends_page.wait_until_names_invisibleIt 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)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? method that will return true if all mapped items
are present in the browser and false if they're not all there.
@friends_page.all_there? #=> true/false
# and...
Then('the friends page contains all the expected elements') do
expect(@friends_page).to be_all_there
endYou 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? you can declare
.expected_elements on your page class that narrows the elements
included in #all_there? check to those that definitely should be present.
class TestPage [: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? check. Note that the only valid values
for this at the moment are :none and :one
Passing :none (default), will not change the functionality. However passing in :one will cause
site_prism to recurse through all section / sections items defined in your present scope.
Work to develop this is contained in the site_prism-all_there repo. So head on over there if you're interested in this area more
If #all_there? returns false and you wish to get the list of missing elements for debugging purposes
you may want to use #elements_missing method. It will return all missing elements from the expected_elements list
If you do not provide a list of expected_elements this method will return all elements that are missing on the page;
from those which are defined.
class Home [:name]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.
In the same way that SitePrism provides element and elements, it
provides section and sections. The first returns an instance of a
page section, the second returns an array of section instances, one for
each capybara element found by the supplied css selector. What follows
is an explanation of section.
A section is similar to a page in that it inherits from a SitePrism class:
class Menu When the menu method is called against @home, an instance of Menu
(the second argument to the section method) is returned. The third
argument that is passed to the section method is the locator that
will be used to find the root element of the section; this root node
becomes the 'scope' of the 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 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.mNo open issues yet, or sync has not completed.