Building PageObjects


A typical PageObject built with holmium.core has the following composition:

A Page is initalized with a selenium.webdriver.remote.webdriver.WebDriver instance and can take some optional arguments.

class MyPage(Page):

driver = selenium.webdriver.Firefox()
p = MyPage(driver)
p = MyPage(driver, url = "")
p = MyPage(driver, url = "", iframe = "#frame")

Providing the url argument will result in the driver navigating to the url when the Page is initialized. The iframe argument forces an invocation of selenium.webdriver.remote.webdriver.WebDriver.switch_to_frame() everytime an element in the Page is accessed.

The webdriver that is supplied to a Page is used when looking up any Element, Elements or ElementMap that is declared as a static member.

To understand the wiring between a Page and its elements try out the example below in a python repl.

from holmium.core import Page, Element, Elements, ElementMap, Locators
import selenium.webdriver
driver = selenium.webdriver.Firefox()
class GooglePage(Page):
    search_box = Element( Locators.NAME, "q", timeout = 1)
    google_footer = ElementMap ( Locators.CSS_SELECTOR, "#fsl>a" , timeout = 1 )

g = GooglePage(driver, url="")
# <selenium.webdriver.remote.webelement.WebElement object at 0x10b50e450>
# OrderedDict([(u'Advertising', <selenium.webdriver.remote.webelement.WebElement object at 0x10b35f250>), .....
# <selenium.webdriver.remote.webelement.WebElement object at 0x10b35f450>
# u''
g.google_footer["Kuhusu Google"].get_attribute("href")
# u''

Both the element search_box and the collection of footer links google_footer are looked up using the driver that was passed into the GooglePage instance.


Section objects can be used to further encapsulate blocks of page logic that may either be reusable between different pages or accessed from within different parts of the page in a similar manner. Examples of such usecases are menus, footers and collections that may not follow a standard list or map formation.

Take for example a page with the following structure.

from holmium.core import Page, Section, Element, Elements, ElementMap, Locators
import selenium.webdriver

headlines_snippet = """
        <div class='header'>
            <h2>Breaking news!!</h2>
        <div class='news_section'>
                    <div class='heading'>Big News!!!</div>
                    <div class='content'>Just kidding</div>
                    <div class='heading'>Other Big News!!!</div>
                    <div class='content'>Again, just kidding</div>
sports_snippet = """
        <div class='header'>
            <h1>Sports news</h1>
            <h2>Breaking news!!</h2>
        <table class="events">
                <td class='sport'>Soccer</td>
                <td class='status'>World cup</td>
                <td class='sport'>Cricket</td>
                <td class='status'>League matches</td>
        <div class='news_section'>
                    <div class='heading'>Soccer worldcup finals!!!</div>
                    <div class='content'>I'm running out of meaningful snippets</div>
                    <div class='heading'>Cricket league matches</div>
                    <div class='content'>I'm definitely out.</div>

class Heading(Section):
    main = Element( Locators.CSS_SELECTOR, "h1")
    sub = Element( Locators.CSS_SELECTOR, "h2")

class NewsSection(Section):
    articles = ElementMap( Locators.CSS_SELECTOR, "ul>li"
                            , key=lambda el: el.find_element_by_class_name('heading').text
                            , value=lambda el: el.find_element_by_class_name('content').text

class SportsEventsSection(Section):
    events = ElementMap( Locators.CSS_SELECTOR, "tr"
                            , key=lambda el: el.find_element_by_class_name('sport').text
                            , value=lambda el: el.find_element_by_class_name('status').text

class NewsPage(Page):
    heading = Heading(Locators.CLASS_NAME, "header")
    news_section = NewsSection(Locators.CLASS_NAME, "news_section")

class HeadlinePage(NewsPage):

class SportsPage(NewsPage):
    sports_events = SportsEventsSection(Locators.CLASS_NAME, "events")

driver = selenium.webdriver.Firefox()

headlines = HeadlinePage(driver, "file:///var/tmp/headlines.html")
print headlines.news_section.articles["Big News!!!"]
print headlines.heading.main.text

sports = SportsPage(driver, "file:///var/tmp/sports.html")
print sports.heading.main.text
print sports.news_section.articles["Soccer worldcup finals!!!"]

Though there are two different pages being accessed, they follow a similar structure and the news_section and header parts can be encapsulated into a common Section. Though the events section in the sports page isn’t used anywhere else - it still makes it clearer to define it as a Section to separate its logic from the main SportsPage.

There may be other usecases where Section objects may be used to represent complex objects within a page that appear repeatedly in a list like manner. To reduce the duplication of specifying Section objects repeatedly in a Page a Sections object may be used to obtain an iterable view of all matched Section objects.


Though one could be inclined to treat Sections as any other collection please only use them as an iterable or do indexed access directly on the Sections object. Trying to cast a Sections property into a list is not supported.

from holmium.core import Page, Sections, Element, Elements, ElementMap, Locators
import selenium.webdriver

page_snippet = """
        <div class='thought'>
            <div class='author'>
                <span class='user'>John</span>
                <span class='reputation'>1000</span>
            <div class='details'>
                <div class='brief'>John's world view</div>
                <div class='full_text'>Sleeping is important</div>
        <div class='thought'>
            <div class='author'>
                <span class='user'>Jane</span>
                <span class='reputation'>100000000</span>
            <div class='details'>
                <div class='brief'>Jane's world view</div>
                <div class='full_text'>John's world view is not important...</div>

class ThoughtSections(Sections):
    author = Element(Locators.CLASS_NAME , "user")
    brief = Element(Locators.CSS_SELECTOR , "div.details div.brief")
    full_text = Element(Locators.CSS_SELECTOR , "div.details div.full_text")

class MainPage(Page):
    thoughts = ThoughtSections(Locators.CLASS_NAME, "thought")

driver = selenium.webdriver.Firefox()

main_page = MainPage(driver, "file:///var/tmp/page.html")
for thought in main_page.thoughts:
    print thought.brief.text
    print thought.full_text.text


To keep the interaction with collections of elements in a Page readable and logically grouped - it is useful to represent and access such elements in a page the same way as one would a python list or dictionary. The Elements and ElementMap (which is used in the previous example) can be used to organize elements with either relationship.

Using the table defined in snippet below, a Page can be constructed that allows you to access the value or title of each row either as a list or a dictionary keyed by the title.

Take note of the differences in construction of element_values and element_titles. Since element_values does not provide a lookup function via the value argument, the element returned is a pure selenium selenium.webdriver.remote.webelement.WebElement. In the case of element_titles the lookup function extracts the text attribute of the element. The same type of lookup functions are used in element_map to create the key/value pairs.

snippet = """
        <td class='title'>title 1</td>
        <td class='value'>value one</td>
        <td class='title'>title 2</td>
        <td class='value'>value two</td>

from holmium.core import Page,Elements,ElementMap,Locators
import selenium.webdriver

class Trivial(Page):
    element_values = Elements(Locators.CSS_SELECTOR
                            , "tr>td[class='value']" )
    element_titles = Elements(Locators.CSS_SELECTOR
                            , "tr"
                            , value=lambda el: el.find_element_by_css_selector("td[class='value']").text)
    element_map = ElementMap(Locators.CSS_SELECTOR
                            , "tr"
                            , key=lambda el: el.find_element_by_css_selector("td[class='title']").text
                            , value=lambda el: el.find_element_by_css_selector("td[class='value']").text)

driver = selenium.webdriver.Firefox()
t = Trivial(driver)
# u'one'
# u'1'
# [u'1', u'2']
# u'one'


For any non-trivial web page, asynchronous changes to the dom are expected. This requires test authors to often place explicit waits for conditions such as visibility and content changes. To reduce the effort of describing these conditionals, page elements Element, Elements and ElementMap accept a keyword argument only_if: a callable that expects a selenium.webdriver.remote.webelement.WebElement and is expected to return True/False. When coupled with the keyword argument timeout, access to a page object’s element is internally subjected to an explicit wait.

Some common conditions are provided and can be used to further simplify the declaration of pageobject:

class holmium.core.conditions.VISIBLE[source]

checks if the element is visible

class holmium.core.conditions.INVISIBLE[source]

checks if the element is invisible

class holmium.core.conditions.MATCHES_TEXT(expr)[source]

checks if the element’s text matches the provided regular expression.

You can build your own condition objects by subclassing conditions.BaseCondition and implementing the conditions.BaseCondition.evaluate() method.


from holmium.core import conditions, Page, Element, Locators

class MyPage(Page):
    required_element = Element(Locators.CLASS_NAME, "main_element",
                                timeout = 5)
    delayed_element = Element(Locators.CLASS_NAME, "text_element",
                                timeout = 5)

In the above example, required_element will return None unless it is displayed. The 5 second timeout will take effect everytime the element is accessed. Similarly, delayed_element will return None until the text of the element matches a string that starts with ready.

Page Facets

Beyond elements maintained by a page, there are other characteristics that can define the behavior of a Page or Section. Holmium allows you to decorate a page with a facets.Facet which ensures evaluation of the facet before the first access on the Page or Section.

Builtin facets

class holmium.core.facets.Title(required=True, debug=False, **kwargs)[source]

enforces the title of the current page.

  • title (str) – a regular expression to match the title.
  • debug (bool) – if True a failure to evaluate will not result in an exception, only a log warning
  • required (bool) – if False a failure to evaluate will be treated as a noop.
class holmium.core.facets.Cookie(required=True, debug=False, **kwargs)[source]

enforces the existence (and optionally the value) of a cookie.

  • name (str) – name of the cookie
  • value (dict) – (optional) dict (or callable) to validate the value of the cookie.
  • debug (bool) – if True a failure to evaluate will not result in an exception, only a log warning
  • required (bool) – if False a failure to evaluate will be treated as a noop.
class holmium.core.facets.Strict(required=True, debug=False, **kwargs)[source]

enforces that every element declared in the Page or Section be present.

  • debug (bool) – if True a failure to evaluate will not result in an exception, only a log warning
  • required (bool) – if False a failure to evaluate will be treated as a noop.
class holmium.core.facets.Defer(required=True, debug=False, **kwargs)[source]
  • page (holmium.core.Page) – the page object that is expected to be deferred to
  • action (function) – a callable that takes the page object instance as the first argument
  • action_arguments (dict) – (optional) dictionary of arguments to pass to action
  • debug (bool) – if True a failure to evaluate will not result in an exception, only a log warning
  • required (bool) – if False a failure to evaluate will be treated as a noop.

For good measure, lowercased aliases are available for builtin facets:


alias of Title


alias of Strict


alias of Cookie


alias of Defer

Rolling your own

You can create your own facet decorator by subclassing facets.Facet and implementing the facets.Facet.evaluate() method. Any additional arguments that you want to access during evaluation should be declared as the following class members:

  • required arguments as an __ARGS__ list
  • optional arguments as an __OPTIONS__ dictionary.

You can also declare an __ALLOW_MUTLIPLE__ property on your facet which will control the expectation from multiple decorations of the same facet type. If set to False the last facet decorator applied will be respected (for example as with the facets.title facet - for which it only makes sense to respect the last decorator applied).

The example facet below would require that color as an argument, and would optionally accept image. When the facet is evaluated it would assert on the background-color of the body element and optionally, the background-image.

class background(Facet):
    __ARGS__ = ["color"]
    __OPTIONS__ = {"image": None}
    def validate(self, driver):
        body = driver.find_element_by_tag_name("body")
        assert_equals( self.arguments["color"], body.value_of_css_property("background-color")
        if self.options["image"]:
            assert_equals( self.options["image"], body.value_of_css_property("background-image")

The decorater could then be applied as follows

@background(color="rgb(255, 255, 255)", image="none")
class Google(Page):
    google_button = Element(Locators.NAME, "btnK")

Additionally individual Element, ElementMap or Elements members of a Page or Section can be promoted to a facet by adding the facet=True keyword argument. This will ensure that the specified element is required at the time of the containers first access.


from holmium.core import facets, Page, Element, Section, Locators

class MySection(Section):
    required_element = Element(Locators.CLASS_NAME, "main_element", facet=True)
    optional_element = Element(Locators.CLASS_NAME, "secondary_element")

@facets.title(title='login page')
class LoginPage(Page):
    def do_login(self, username, password):

@facets.defer(page=LoginPage, action=LoginPage.do_login, action_arguments= {"username":"ali", "password":"sekret"})
class ContentPage(Page):
    section = MySection(Locators.ID, "main-section")

To understand how the facets are evaluated, consider the following code path

from selenium import webdriver

driver = webdriver.Firefox()

p = ContentPage(driver, "http://localhost/content")
assert p.section.optional_element != None

The chain of execution when calling p.section.required_element is as follows

  • check defer to LoginPage
  • check title of LoginPage
  • perform do_login
  • check cookie of ContentPage
  • check required element exists in MySection
  • return optional_element

Customizing page elements

To further customize domain / page specific behaviors of certain web elements, the ElementEnhancer base class can be extended to hijack selenium.webdriver.remote.webelement.WebElement. The located web element is made available to the subclass as self.element.

In the sample below, the SelectEnhancer enhancer will be used to hijack any web element that has the tag name select. All properties and methods exposed by the selenium.webdriver.remote.webelement.WebElement object will still be accessible, and extra methods/properties (such as ‘options’) will be added on. You can register your own ElementEnhancer via a call to register_enhancer() and subsequently reset them via a call to reset_enhancers().

By default, holmium only installs a SelectEnhancer that shadows

class SelectEnhancer(ElementEnhancer):
    __TAG__ = "select"
    def options(self):
        return self.element.find_elements_by_tag_name("option")

    def has_option(self, option_name):
        return any([k.text == option_name for k in self.options])


More Examples

Wikipedia text search example

import unittest
import selenium.webdriver
from holmium.core import Page, Element, Elements, Locators, ElementMap

class WikiPedia(Page):
    languages = ElementMap( Locators.CLASS_NAME, "central-featured-lang"
                                    , key = lambda el:el.get_attribute("lang")
                                    , value = lambda el: el.find_element_by_tag_name("a"))
    search_box = Element( Locators.CSS_SELECTOR, "input#searchInput" )
    article_title = Element( Locators.CSS_SELECTOR, "h1#firstHeading span[dir=auto]" )
    search_results = ElementMap( Locators.CSS_SELECTOR, ">a")
    def search(self,  query ):
        self.search_box.send_keys( query )

class TextSearchArticle(unittest.TestCase):
    def setUp(self):
        self.driver = selenium.webdriver.Firefox() = WikiPedia(self.driver, "")

    def test_text_search_alllangs(self):
        for language in
            self.assertEquals("google").article_title.text, "Google", language)

    def tearDown(self):