Skip to main content

pages is a lightweight page object and component Python library for UI tests

Project description


BuildStatus CoverageStatus PyPI1 PyPI2 PyPI3

pages is a lightweight Python library which helps in the creation of readable and reliable page/component objects for UI tests.

It is been designed to ensure that timing issues will have zero impact on your test results.

It is a wrapper around the Python WebDriver bindings, but the same ideas (components, traits, …) could be adapted to any other driver technology - including mobile.


The most common problem when introducing automated UI-based testing in continuous integration is the brittle nature of the tests. A false negative in a CI pipeline is often cause of stress, fierce discussions (slip the build through vs. hold it on failure analysis) and in some cases radical changes of test strategies. However, the value of reliable UI tests is undeniable, as they are the closest thing to real usage of a product. Moreover, they exercise the stack from the front-end, thus representing a way to test integration of the whole system. This is why automated UI tests sit at the top of the well-known test pyramid: they are seen as difficult to implement and expensive to maintain.

However, reliability of tests is normally a design problem.

pages offers a simple but effective framework to build robust page objects for UI tests.


pip install p-ages


The design revolves around three key concepts:

As usual, the best way to learn how to use it is to start coding.


We want to create UI tests for this page:

This is a login page that, on successful authentication, takes to a secure area page. We want to write a test that loads the login page and executes authentication. We will create two page objects. All the examples are in the samples folder.

First step - test container

As a first step, we will create a container where we instantiate the driver.

class LoginTest(unittest.TestCase):

    def setUp(self):
        self.driver = WebDriver()

    def test_can_login(self):

Second step - test implementation top-down

Load the page, enter credentials and assert that the secure area page is loaded. In code this becomes:

class LoginTest(unittest.TestCase):

    def setUp(self):
        self.driver = WebDriver()

    def test_can_login(self):
        login_page = LoginPage(self.driver).load().wait_until_loaded()

        secure_area_page = login_page.login('tomsmith', 'SuperSecretPassword!')

        assert_that(secure_area_page, is_loaded().with_timeout(PAGE_LOADING_TIMEOUT)

Notice how the LoginPage needs only a reference to the driver that we have created in the setUp. We know the API already, so we are adding method calls to load() and wait_until_loaded(). However, this will be explained in the next steps.

Third step - loading the Login page

The Login page will extend the Page base class from our framework. One requirement is that load(), which is abstract, has to be defined. Moreover, since we are chaining other methods, load() has to return an instance of the class.

class LoginPage(Page):

    def __init__(self, driver):
        Page.__init__(driver, 'Login page')

    def load(self):
        return self

Fourth step - adding traits

Traits are the conditions that have to be verified for the page to be in the loaded state. In our case, the page has user text input, password text input and submit button, since those are the elements we are going to interact with. We’ll start by defining three private methods to check the presence of those elements.

def _has_username_input(self):
    return TextInput(self.driver, 'username', [By.ID, 'username']).is_present()

def _has_password_input(self):
    return TextInput(self.driver, 'password', [By.ID, 'password']).is_present()

def _has_submit_button(self):
    return Button(self.driver, 'submit', [By.XPATH, "//button[@type = 'submit']"]).is_present()

We can now add traits to the page under test. Let’s add them to the __init__().

def __init__(self, driver):
    Page.__init__(self, driver, 'Login page')
    self.add_trait(self._has_username_input, 'has username')
    self.add_trait(self._has_password_input, 'has password')
    self.add_trait(self._has_submit_button, 'has submit button')

Notice how add_trait() takes as first parameter the method name. In other words, it accepts only a callable. For instance, you may pass a lambda to it. The second parameter is the short description of the trait, used for logging.

Finally, notice how the three traits we chose are the elements that need to be ready for the interactions we are going to have with the page. While these three traits are verified, other parts of the page may still be loading. While this should not be a problem for the safety of this test, in general great care should be taken to select traits so that tests do not interact with parts of the DOM which have not finished loading.

Fifth step - logging in and returning secure area page

On successful login, the secure area page should be returned. This is done in the login_user() method. Notice that we have refactored some of the previous code for better reuse.

def login_user(self, username, password):
    return SecureAreaPage(self.driver)

Sixth step - Secure Area Page

Finally, we need to implement the return page. Similarly to the login page:

class SecureAreaPage(Page):

    def __init__(self, driver):
        Page.__init__(self, driver, 'Secure area page')
        self.add_trait(self._has_logout_button, 'has logout button')

    def load(self):
        raise NotLoadablePageException('{0} cannot be loaded'.format(

    def _has_logout_button(self):
        return Button(self.driver, [By.XPATH, "//button[@href='/logout']"]).is_present()

Notice how we did not implement load(), since the secure area page is not loadable from a URL.

Page objects

In the previous example, we have seen how simple it is to implement page objects and create tests with them. In essence, all we need to do is:

  • extend the Page class
  • implement the load() method
  • add traits to the page

As a final (golden) rule, every method which models a user interaction and results in a page load has to return a page object of the target page. The simplest case is load() itself.

The benefit of building a page from the Page class is that, after proper definition of traits, we can rely on wait_until_loaded() to pause the test execution just enough to allow the page to load.

login_page = LoginPage(self.driver).load().wait_until_loaded()

Page traits

Disclaimer: Traits we define here are not “class traits”.

A Trait is an abstraction of the condition that must be verified for an element to be ready. As shown in the example above, adding traits is extremely simple. The most important reason we introduced traits is that they make it easy to nail down which conditions have failed on page load.


The UIComponent class is the basic element we use to build our page models. Anything that is part of a web page can be modelled as a UIComponent. The responsibility of this class is to ensure lazy creation of a WebElement.

In the example above, the InputText and Button classes extend UIComponent.

In general, a UIComponent may represent any portion of the DOM. It is important to notice that a UIComponent can contain another UIComponent. An example of this is the Table class.


We want to build a model of the table at this address: We will build a component class that allows interaction with the table. In particular, we want to test that elements in the first row of the table match the expected values. The complete example code can be found under the sample folder.

Again, we will build the test top-down.

EXPECTED_LABEL_LIST = ['Iuvaret0', 'Apeirian0', 'Adipisci0', 'Definiebas0', 'Consequuntur0', 'Phaedrum0', 'edit delete']

class SampleTableTest(unittest.TestCase):

    def setUp(self):
        self.driver = WebDriver()

    def tearDown(self):

    def test_can_get_table_elements(self):
        sample_page = SamplePage(self.driver).load().wait_until_loaded()
        first_table_row_values = sample_page.read_first_table_row()

        assert_that(first_table_row_values, equal_to(EXPECTED_LABEL_LIST))

SamplePage is a page object class which contains a table as a component. We can start by writing the table. The Table class (available in pages.standard_components) makes this simple.

class SampleTable(Table):

    def __init__(self, driver):
        super(SampleTable, self).__init__(driver, 'sample table', [By.XPATH, './tbody/tr'], TableRow, 'row',
                                          [By.XPATH, '//table'])

SampleTable extends Table which in turn extends UIComponent. Moreover, when calling the super() method, we define TableRow as a component representing a single row.

class TableRow(UIComponent):

    def __init__(self, driver, name):
        super(TableRow, self).__init__(driver, name)

    def values(self):
        return [i.text for i in self.locate().find_elements_by_xpath('./td')]

TableRow extends UIComponent and defines methods to access elements in the row. The main problem has been split into smaller ones, and we have written a very small amount of code.

Finally, we can define SamplePage.

class SamplePage(Page):

    def __init__(self, driver):
        Page.__init__(self, driver, 'sample page')
        self.add_trait(lambda: SampleTable(self.driver).is_present(), 'has table')

    def load(self):
        return self

    def read_first_table_row(self):
        table_rows = SampleTable(self.driver).get_items()
        return [i for i in table_rows[0].values()]

One thing to notice here is that the table object is created afresh every time read_first_table_row() is called. While this makes sense in most cases, as the content of the page may change dynamically after loading (this is often the case for tables), in this case inspection of the Table class tells us that calling __init__() does not result in any WebDriver operation. The only moment when we locate elements on the DOM is when we call get_items().

This is the other key-concept of pages: by using UIComponent, we can build components that instantiate a WebElement only when we need to use it. This eliminates the possibility of StaleElementReferenceException(s) to be raised during the execution.


pages adds only a NullHandler to the loggers. In order to turn on logging generated inside the library you can rely on root logger or set on explicitly. To turn on logging from your application code, for instance:


This will set log level to DEBUG.

Distributing pages

pages is distributed on PyPI.


  • Ensure .pypirc is present.
  • Update __version__ under pages/
  • Run under the script folder.


pages is licensed under the Apache Software License 2.0 provision.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

p-ages-1.0.1.tar.gz (23.3 kB view hashes)

Uploaded source

Built Distribution

p_ages-1.0.1-py2-none-any.whl (29.8 kB view hashes)

Uploaded 2 7

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page