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)¶

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()

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()¶

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()¶: Wait for the page to load.

Region¶

class pypom.region.Region(page, root=None)¶

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)¶

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)¶

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 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()¶: Wait for the page region to load.

Hooks¶

pypom.hooks.pypom_after_wait_for_page_to_load(page)¶: Called after waiting for the page to load

pypom.hooks.pypom_after_wait_for_region_to_load(region)¶: Called after waiting for the region to load