Developer Interface

This part of the documentation describes the interfaces for using PyPOM.

Page

class pypom.page.Page(driver, base_url=None, timeout=10, **url_kwargs)[source]

A page object.

Used as a base class for your project’s page objects.

Parameters:
  • driver (WebDriver or Browser) – A driver.
  • base_url (str) – (optional) Base URL.
  • timeout (int) – (optional) Timeout used for explicit waits. Defaults to 10.
  • url_kwargs – (optional) Keyword arguments used when generating the seed_url.

Usage (Selenium):

from pypom import Page
from selenium.webdriver import Firefox

class Mozilla(Page):
    URL_TEMPLATE = 'https://www.mozilla.org/{locale}'

driver = Firefox()
page = Mozilla(driver, locale='en-US')
page.open()

Usage (Splinter):

from pypom import Page
from splinter import Browser

class Mozilla(Page):
    URL_TEMPLATE = 'https://www.mozilla.org/{locale}'

driver = Browser()
page = Mozilla(driver, locale='en-US')
page.open()
URL_TEMPLATE = None

Template string representing a URL that can be used to open the page.

This string is formatted and can contain names of keyword arguments passed during construction of the page object. The template should either assume that its result will be appended to the value of base_url, or should yield an absolute URL.

Examples:

URL_TEMPLATE = 'https://www.mozilla.org/'  # absolute URL
URL_TEMPLATE = '/search'  # relative to base URL
URL_TEMPLATE = '/search?q={term}'  # keyword argument expansion
find_elements(strategy, locator)

Finds elements on the page.

Parameters:
  • strategy (str) – Location strategy to use. See By or ALLOWED_STRATEGIES.
  • locator (str) – Location of target elements.
Returns:

List of WebElement or ElementList

Return type:

list

is_element_displayed(strategy, locator)

Checks whether an element is displayed.

Parameters:
  • strategy (str) – Location strategy to use. See By or ALLOWED_STRATEGIES.
  • locator (str) – Location of target element.
Returns:

True if element is displayed, else False.

Return type:

bool

is_element_present(strategy, locator)

Checks whether an element is present.

Parameters:
  • strategy (str) – Location strategy to use. See By or ALLOWED_STRATEGIES.
  • locator (str) – Location of target element.
Returns:

True if element is present, else False.

Return type:

bool

loaded

Loaded state of the page.

By default the driver will try to wait for any page loads to be complete, however it’s not uncommon for it to return early. To address this you can override loaded to return True when the page has finished loading.

Returns:True if page is loaded, else False.
Return type:bool

Usage (Selenium):

from pypom import Page
from selenium.webdriver.common.by import By

class Mozilla(Page):

    @property
    def loaded(self):
        body = self.find_element(By.TAG_NAME, 'body')
        return 'loaded' in body.get_attribute('class')

Usage (Splinter):

from pypom import Page

class Mozilla(Page):

    def loaded(self):
        body = self.find_element('tag', 'body')
        return 'loaded' in body['class']

Examples:

# wait for the seed_url value to be in the current URL
self.seed_url in self.selenium.current_url
open()[source]

Open the page.

Navigates to seed_url and calls wait_for_page_to_load().

Returns:The current page object.
Return type:Page
Raises:UsageError
seed_url

A URL that can be used to open the page.

The URL is formatted from URL_TEMPLATE, which is then appended to base_url unless the template results in an absolute URL.

Returns:URL that can be used to open the page.
Return type:str
selenium

Backwards compatibility attribute

wait_for_page_to_load()[source]

Wait for the page to load.

Region

class pypom.region.Region(page, root=None)[source]

A page region object.

Used as a base class for your project’s page region objects.

Parameters:
  • page (Page) – Page object this region appears in.
  • root (WebElement or WebDriverElement) – (optional) element that serves as the root for the region.

Usage (Selenium):

from pypom import Page, Region
from selenium.webdriver import Firefox
from selenium.webdriver.common.by import By

class Mozilla(Page):
    URL_TEMPLATE = 'https://www.mozilla.org/'

    @property
    def newsletter(self):
        return Newsletter(self)

    class Newsletter(Region):
        _root_locator = (By.ID, 'newsletter-form')
        _submit_locator = (By.ID, 'footer_email_submit')

        def sign_up(self):
            self.find_element(*self._submit_locator).click()

driver = Firefox()
page = Mozilla(driver).open()
page.newsletter.sign_up()

Usage (Splinter):

from pypom import Page, Region
from splinter import Browser

class Mozilla(Page):
    URL_TEMPLATE = 'https://www.mozilla.org/'

    @property
    def newsletter(self):
        return Newsletter(self)

    class Newsletter(Region):
        _root_locator = ('id', 'newsletter-form')
        _submit_locator = ('id', 'footer_email_submit')

        def sign_up(self):
            self.find_element(*self._submit_locator).click()

driver = Browser()
page = Mozilla(driver).open()
page.newsletter.sign_up()
find_element(strategy, locator)[source]

Finds an element on the page.

Parameters:
  • strategy (str) – Location strategy to use. See By or ALLOWED_STRATEGIES.
  • locator (str) – Location of target element.
Returns:

An element.

Rytpe:

WebElement or WebDriverElement

find_elements(strategy, locator)[source]

Finds elements on the page.

Parameters:
  • strategy (str) – Location strategy to use. See By or ALLOWED_STRATEGIES.
  • locator (str) – Location of target elements.
Returns:

List of WebElement or ElementList

Return type:

list

is_element_displayed(strategy, locator)[source]

Checks whether an element is displayed.

Parameters:
  • strategy (str) – Location strategy to use. See By or ALLOWED_STRATEGIES.
  • locator (str) – Location of target element.
Returns:

True if element is displayed, else False.

Return type:

bool

is_element_present(strategy, locator)[source]

Checks whether an element is present.

Parameters:
  • strategy (str) – Location strategy to use. See By or ALLOWED_STRATEGIES.
  • locator (str) – Location of target element.
Returns:

True if element is present, else False.

Return type:

bool

loaded

Loaded state of the page region.

You may need to initialise your page region before it’s ready for you to interact with it. If this is the case, you can override loaded to return True when the region has finished loading.

Returns:True if page is loaded, else False.
Return type:bool

Usage (Selenium):

from pypom import Page, Region
from selenium.webdriver.common.by import By

class Mozilla(Page):
    URL_TEMPLATE = 'https://www.mozilla.org/'

    @property
    def newsletter(self):
        return Newsletter(self)

    class Newsletter(Region):
        _root_locator = (By.ID, 'newsletter-form')

        @property
        def loaded(self):
            return 'loaded' in self.root.get_attribute('class')

Usage (Splinter):

from pypom import Page, Region

class Mozilla(Page):
    URL_TEMPLATE = 'https://www.mozilla.org/'

    @property
    def newsletter(self):
        return Newsletter(self)

    class Newsletter(Region):
        _root_locator = ('id', 'newsletter-form')

        @property
        def loaded(self):
            return 'loaded' in self.root['class']
root

Root element for the page region.

Page regions should define a root element either by passing this on instantiation or by defining a _root_locator attribute. To reduce the chances of hitting StaleElementReferenceException or similar you should use _root_locator, as this is looked up every time the root property is accessed.

selenium

Backwards compatibility attribute

wait_for_region_to_load()[source]

Wait for the page region to load.

Hooks

pypom.hooks.pypom_after_wait_for_page_to_load(page)[source]

Called after waiting for the page to load

pypom.hooks.pypom_after_wait_for_region_to_load(region)[source]

Called after waiting for the region to load