Testing website user functionality with Capybara page objects
Page Objects can be used as a powerful method of abstraction (isolation) of your tests from technical implementation. It is important to remember that they (Page Objects) can be used to increase the stability of tests and maintain the principle of DRY (do not repeat yourself) - by encapsulating the functionality (website) in simple methods.
Page Object is an instance of a class that abstracts (isolates) the user interface from the test environment, presents methods for interacting with the user interface, and extracts the necessary information.
The term Page Object is too general a concept. In my experience, Page Object includes the following 3 types:
Consider a simple RSpec Capybara test that creates blogs and does not use page objects:
Let's take a closer look at the code; it has several problems. There are the following actions: switching to the corresponding page, interacting with the page and checking the content. Part of the code is duplicated, but this can be fixed by sticking to the DRY principle.
It is important to understand that this code is difficult to maintain if there are changes in the application under test. For example, element classes, names and identifiers can change, which requires regular updates of the test code.
Also in this code there is no 'Semantic context', it is difficult to understand which lines of code are logically grouped.
As discussed in the terminology section, Page Objects can be used to represent presentation-level abstractions.
Taking the previous example and using Page Object to create new blogs and view blogs, we can clear the code of the previous example.
Having got rid of specific information about technical implementation, the final result (code) should be readable and should not contain specific information about the user interface (id, css classes, etc.).
Creating Page Objects
The first step in creating Page Objects is to create a basic page class structure:
Connecting (enabling) Capybara :: DSL to allow Page Objects instances to use the methods available in Capybara
In addition, I used
Do not violate the agreement, Page Objects should not include expect (expectations) . However, where appropriate, I prefer this approach to rely on Capybara's built-in mechanisms for handling conditions.
For example, the following Capybara code will expect the presence of 'foo' inside Page Objects (in this case, self ):
However, in the following code:
Unforeseen errors are possible (a floating test may occur), since page_object.content is immediately checked for compliance with the condition, and possibly has not yet been declared. For more examples, I would recommend reading thoughtbot's writing reliable asynchronous integration tests with Capybara .
We can abstract (describe) the place (region) from which we want to obtain data, in the framework of one method:
It's important to choose the semantically correct names for the methods for your Page Objects
In general, it is important to follow the principle of functionally integrated methods and, where possible, adhere to the principle of single responsibility (Single Responsibility Principle).
In our example, we use the NewBlog class, but there is no implementation to create.
Since we interact with the form, we could additionally introduce a class to represent this component:
Where methods implementation for BlogForm can be hidden:
Using the above classes, you can now query and create instances of the Page Objects of your page as part of the description of the object.
Note: I intentionally created the page object manually at the top of the object file. In some RSpec tests, it may be convenient to automatically download all support files and provide access to them in object files, however, this can lead to excessive workloads when using large pieces of code. In particular, this will lead to slow startup and potential unintended cyclic dependencies.
Now in each scenario we will have access to instances of new_blog_page and view_blog_page :
As with most things in Rails / Ruby, there are conventions that may seem insignificant (not binding) completely at a glance.
In our tests, we interacted with the page object using have_loaded and have_blog :
However, the method names of our page object actually has_loaded? and has_blog? :
This is a subtle distinction that needs attention. For more information on this convention, I would recommend reading the following predicate matchers link.
Git, the source code used in the examples
Original
In other words
Page Object is an instance of a class that abstracts (isolates) the user interface from the test environment, presents methods for interacting with the user interface, and extracts the necessary information.
Terminology
The term Page Object is too general a concept. In my experience, Page Object includes the following 3 types:
- Component Objects represents specific components or widgets in the user interface. For example: tables, menus, articles and other blocks containing a group of components.
- Page Object describes a specific area or user interface in a web application. It may consist of several Component Objects and may contain convenient methods for interacting with the abstraction that is contained within this object.
- Experience is used to group complex functionality, testing of which requires several steps, or interaction with several pages. From my own experience, I used this concept to abstract complex behavior on a page (testing educational pages, creating a new user, etc.)
Examples
Consider a simple RSpec Capybara test that creates blogs and does not use page objects:
require 'feature_helper' feature 'Blog management', type: :feature do scenario 'Successfully creating a new blog' do visit '/' click_on 'Form Examples' expect(page).to have_content('Create Blog') fill_in 'blog_title', with: 'My Blog Title' fill_in 'blog_text', with: 'My new blog text' click_on 'Save Blog' expect(page).to have_selector('.blog--show') expect(page).to have_content('My Blog Title') expect(page).to have_content('My new blog text') end scenario 'Entering no data' do visit '/' click_on 'Form Examples' expect(page).to have_content('Create Blog') click_on 'Save Blog' expect(page).to have_content('4 errors stopped this form being submitted') expect(page).to have_content("Title can't be blank") expect(page).to have_content("Text can't be blank") expect(page).to have_content('Title is too short') expect(page).to have_content('Text is too short') end end
Let's take a closer look at the code; it has several problems. There are the following actions: switching to the corresponding page, interacting with the page and checking the content. Part of the code is duplicated, but this can be fixed by sticking to the DRY principle.
It is important to understand that this code is difficult to maintain if there are changes in the application under test. For example, element classes, names and identifiers can change, which requires regular updates of the test code.
Also in this code there is no 'Semantic context', it is difficult to understand which lines of code are logically grouped.
Introduction to Page Objects
As discussed in the terminology section, Page Objects can be used to represent presentation-level abstractions.
Taking the previous example and using Page Object to create new blogs and view blogs, we can clear the code of the previous example.
Having got rid of specific information about technical implementation, the final result (code) should be readable and should not contain specific information about the user interface (id, css classes, etc.).
require 'feature_helper' require_relative '../pages/new_blog' require_relative '../pages/view_blog' feature 'Blog management', type: :feature do let(:new_blog_page) { ::Pages::NewBlog.new } let(:view_blog_page) { ::Pages::ViewBlog.new } before :each do new_blog_page.visit_location end scenario 'Successfully creating a new blog' do new_blog_page.create title: 'My Blog Title', text: 'My new blog text' expect(view_blog_page).to have_loaded expect(view_blog_page).to have_blog title: 'My Blog Title', text: 'My new blog text' end scenario 'Entering no data' do new_blog_page.create title: '', text: '' expect(view_blog_page).to_not have_loaded expect(new_blog_page).to have_errors "Title can't be blank", "Text can't be blank", "Title is too short", "Text is too short" end end
Creating Page Objects
The first step in creating Page Objects is to create a basic page class structure:
module Pages class NewBlog include RSpec::Matchers include Capybara::DSL # ... end end
Connecting (enabling) Capybara :: DSL to allow Page Objects instances to use the methods available in Capybara
has_css? '.foo' has_content? 'hello world' find('.foo').click
In addition, I used
include RSpec :: Matchersin the above examples to use the expectation RSpec library.
Do not violate the agreement, Page Objects should not include expect (expectations) . However, where appropriate, I prefer this approach to rely on Capybara's built-in mechanisms for handling conditions.
For example, the following Capybara code will expect the presence of 'foo' inside Page Objects (in this case, self ):
expect(self).to have_content 'foo'
However, in the following code:
expect(page_object.content).to match 'foo'
Unforeseen errors are possible (a floating test may occur), since page_object.content is immediately checked for compliance with the condition, and possibly has not yet been declared. For more examples, I would recommend reading thoughtbot's writing reliable asynchronous integration tests with Capybara .
Method Creation
We can abstract (describe) the place (region) from which we want to obtain data, in the framework of one method:
def visit_location visit '/blogs/new' # It can be beneficial to assert something positive about the page # before progressing with your tests at this point # # This can be useful to ensures that the page has loaded successfully, and any # asynchronous JavaScript has been loaded and retrieved etc. # # This is required to avoid potential race conditions. expect(self).to have_loaded end def has_loaded? self.has_selector? 'h1', text: 'Create Blog' end
It's important to choose the semantically correct names for the methods for your Page Objects
def create(title:, text:) # ... end def has_errors?(*errors) # ... end def has_error?(error) # ... end
In general, it is important to follow the principle of functionally integrated methods and, where possible, adhere to the principle of single responsibility (Single Responsibility Principle).
Component objects
In our example, we use the NewBlog class, but there is no implementation to create.
Since we interact with the form, we could additionally introduce a class to represent this component:
# ... def create(title:, text:) blog_form.new.create title: title, text: text end # ... private def blog_form ::Components::BlogForm end
Where methods implementation for BlogForm can be hidden:
module Components class BlogForm include RSpec::Matchers include Capybara::DSL def create(title:, text:) within blog_form do fill_in 'blog_title', with: title fill_in 'blog_text', with: text click_on 'Save Blog' end end private def blog_form find('.blog--new') end end end
Together
Using the above classes, you can now query and create instances of the Page Objects of your page as part of the description of the object.
require 'feature_helper' require_relative '../pages/new_blog' require_relative '../pages/view_blog' feature 'Blog management', type: :feature do let(:new_blog_page) { ::Pages::NewBlog.new } let(:view_blog_page) { ::Pages::ViewBlog.new } # ... end
Note: I intentionally created the page object manually at the top of the object file. In some RSpec tests, it may be convenient to automatically download all support files and provide access to them in object files, however, this can lead to excessive workloads when using large pieces of code. In particular, this will lead to slow startup and potential unintended cyclic dependencies.
Call Page Objects
Now in each scenario we will have access to instances of new_blog_page and view_blog_page :
scenario 'Successfully creating a new blog' do new_blog_page.create title: 'My Blog Title', text: 'My new blog text' expect(view_blog_page).to have_loaded expect(view_blog_page).to have_blog title: 'My Blog Title', text: 'My new blog text' end
Naming Conventions / Predicate Methods
As with most things in Rails / Ruby, there are conventions that may seem insignificant (not binding) completely at a glance.
In our tests, we interacted with the page object using have_loaded and have_blog :
expect(view_blog_page).to have_loaded expect(view_blog_page).to have_blog title: 'My Blog Title', text: 'My new blog text'
However, the method names of our page object actually has_loaded? and has_blog? :
def has_loaded? # ... end def has_blog?(title:, text:) # ... end
This is a subtle distinction that needs attention. For more information on this convention, I would recommend reading the following predicate matchers link.
Git, the source code used in the examples
Original
All Articles