Developer Interface

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

WebView

class pomcorn.web_view.WebView(webdriver: WebDriver, *, app_root: str, wait_timeout: int, poll_frequency=0.0)[source]

Class for storing basic shortcuts for interacting with the browser.

__init__(webdriver: WebDriver, *, app_root: str, wait_timeout: int, poll_frequency=0.0)[source]

Initialize webview.

Parameters:
  • webdriver – Instance of a class for managing the browser.

  • app_root – The URL of browser.

  • wait_timeout – Number of seconds before timing out.

  • poll_frequency – Time between checks of wait condition, lower interval - faster checks. This allows to improve overall tests speed.

init_element(locator: TInitLocator) PomcornElement[TInitLocator][source]

Shortcut for initializing Element instances.

Note: To be consistent with the method of the same name in Component, try to use keyword when specifying the locator argument whenever possible.

Parameters:

locator – Instance of a class to locate the element in the browser.

init_elements(locator: XPathLocator) list[PomcornElement[XPathLocator]][source]

Shortcut for initializing many Element instances via single locator.

Note: Only supports Xpath locators.

Note: To be consistent with the method of the same name in Component, try to use keyword when specifying the locator argument whenever possible.

Parameters:

locator – Instance of a class to locate the element in the browser.

iter_locators(locator: XPathLocator, only_visible: bool = False) list[XPathLocator][source]

Get the list of the locators where each of them match an element.

For example, there are multiple elements on the page that matches XPathLocator(“//a”).

This method return the set of locators like: * XPathLocator(“(//a)[1]”) * XPathLocator(“(//a)[2]”)

Parameters:
  • locator – Instance of a class to locate the element in the browser.

  • only_visible – Flag for viewing visible elements. If this is True (default), then this method will only get visible elements, otherwise all the elements (including not visible) will be counted.

property current_url: str

Return the current webdriver URL.

wait_until_url_contains(url: str)[source]

Wait until browser’s url contains input url.

Raises:

TimeoutException – If after self.wait_timeout seconds the wait has not ended.

wait_until_url_not_contains(url: str)[source]

Wait until browser’s url doesn’t not contains input url.

Raises:

TimeoutException – If after self.wait_timeout seconds the wait has not ended.

wait_until_url_changes(url: str | None = None)[source]

Wait until url changes.

Parameters:

url – Browser URL which should be changed. If the argument is not input, will be used self.current_url.

Raises:

TimeoutException – If after self.wait_timeout seconds the wait has not ended.

wait_until_locator_visible(locator: Locator)[source]

Wait until element matching locator becomes visible.

Parameters:

locator – Instance of a class to locate the element in the browser.

Raises:

TimeoutException – If after self.wait_timeout seconds the wait has not ended.

wait_until_locator_invisible(locator: Locator)[source]

Wait until element matching locator becomes invisible.

Parameters:

locator – Instance of a class to locate the element in the browser.

Raises:

TimeoutException – If after self.wait_timeout seconds the wait has not ended.

wait_until_clickable(locator: Locator)[source]

Wait until element matching locator becomes clickable.

Parameters:

locator – Instance of a class to locate the element in the browser.

Raises:

TimeoutException – If after self.wait_timeout seconds the wait has not ended.

wait_until_text_is_in_element(text: str, locator: Locator)[source]

Wait until text is present in the specified element by locator.

Parameters:
  • locator – Instance of a class to locate the element in the browser.

  • text – Text that should be presented in element.

Raises:

TimeoutException – If after self.wait_timeout seconds the wait has not ended.

wait_until_not_exists_in_dom(element: PomcornElement[TLocator] | TLocator)[source]

Wait until element ceases to exist in DOM.

Parameters:

locator – Instance of a class to locate the element in the browser or instance of element.

Raises:

TimeoutException – If after self.wait_timeout seconds the wait has not ended.

drag_and_drop(source: WebElement, target: WebElement)[source]

Perform drag and drop.

Parameters:
  • source – The web element instance to drag.

  • target – The web element instance to drag into.

scroll_to(target: WebElement)[source]

Scroll page to target.

Scroll to the center of target vertically and to the center of target horizontally.

Parameters:

target – The web element instance to scroll to.

scroll_to_top()[source]

Scroll browser to top.

scroll_to_bottom()[source]

Scroll browser to bottom.

get_input_value(label: str) str[source]

Find input element by label and get it’s value.

execute_javascript(script: str, *args)[source]

Execute simple javascript.

Parameters:

script – JavaScript code as a string object.

switch_to_default()[source]

Switch webdriver’s focus to default content.

switch_to_iframe(locator: Locator)[source]

Switch webdriver’s focus to iframe.

Parameters:

locator – Instance of a class to locate the element in the browser.

iframe_switcher_manager(locator: Locator)[source]

Context manager for interacting with iframes.

Parameters:

locator – Instance of a class to locate the element in the browser.

Page

class pomcorn.page.Page(webdriver: WebDriver, *, app_root: str | None = None, wait_timeout: int = 5, poll_frequency: float = 0.01)[source]

The class for representing a web page.

It contains the element and components of the page and utils methods for page manipulation.

APP_ROOT: str
__init__(webdriver: WebDriver, *, app_root: str | None = None, wait_timeout: int = 5, poll_frequency: float = 0.01)[source]

Initialize page.

Call wait_until_loaded method after initialization.

Parameters:
  • webdriver – Instance of a class for managing the browser.

  • app_root – The URL of base page, by default the value of APP_ROOT attribute is used.

  • wait_timeout – Number of seconds before timing out.

  • poll_frequency – Time between checks of wait condition, lower interval - faster checks. This allows to improve overall tests speed.

check_page_is_loaded() bool[source]

Return result of check that the page is loaded.

Some pages can be slow to load and cause problems checking for unloaded items. To be sure the page is loaded, this property should return the result of checking for the slowest parts of the page.

classmethod open(webdriver: WebDriver, *, app_root: str | None = None) Self[source]

Open page and initialize page object.

Parameters:
  • webdriver – Instance of a WebDriver class for managing the browser.

  • app_root – The URL of page, by default the value of APP_ROOT attribute is used.

classmethod open_from_url(webdriver: WebDriver, *, path: str, app_root: str | None = None, **kwargs) Self[source]

Open page from relative path and initialize page object.

Add path to app_root in browser URL.

Parameters:
  • webdriver – Instance of a WebDriver class for managing the browser.

  • app_root – The URL of page, by default the value of APP_ROOT attribute is used.

  • path – Relative URL.

refresh() None[source]

Refresh web page and wait until it is loaded.

wait_until_loaded() None[source]

Wait until page is loaded.

navigate(url: str) None[source]

Navigate absolute URL.

Replace the browser URL with the entered one.

navigate_relative(relative_url: str = '/') None[source]

Navigate to URL relative to application root.

Parameters:

relative_url (str) – Relative URL

click_on_page() None[source]

Click on (1, 1) coordinates of page (left upper corner).

Allows you to move focus away from an element, for example, if it is currently unavailable for interaction.

__annotations__ = {'APP_ROOT': <class 'str'>}

Components

class pomcorn.component.Component(page: TPage, base_locator: XPathLocator | None = None, wait_until_visible: bool = True)[source]

The class to represent a page component that depends on base locator.

It contains page elements, components and utils methods for page manipulation, but as a separate entity that can be reused for different pages with common elements.

Implement wait methods until the component becomes visible or invisible.

__init__(page: TPage, base_locator: XPathLocator | None = None, wait_until_visible: bool = True)[source]

Initialize component.

Parameters:
  • page – An instance of the page that uses this component.

  • base_locator – Instance of a class to locate the component in the browser. Used in relative element initialization methods and visibility waits. You also can specify it as attribute.

  • wait_until_visible – Whether to wait for the component to become visible before completing initialization or not.

base_locator: XPathLocator
init_element(*, locator: XPathLocator) PomcornElement[XPathLocator][source]
init_element(*, relative_locator: XPathLocator) PomcornElement[XPathLocator]

Initialize element including base locator.

Use relative_locator if you need to include base_locator, otherwise use locator.

Raises:

ValueError – If both arguments were passed or neither.

init_elements(*, locator: XPathLocator | None = None) list[PomcornElement[XPathLocator]][source]
init_elements(*, relative_locator: XPathLocator | None = None) list[PomcornElement[XPathLocator]]

Initialize list of elements including base locator.

Use relative_locator if you need to include base_locator, otherwise use locator.

Raises:

ValueError – If both arguments were passed or neither.

wait_until_visible(**kwargs)[source]

Wait until component becomes visible.

wait_until_invisible(**kwargs)[source]

Wait until component becomes invisible.

__annotations__ = {'base_locator': <class 'pomcorn.locators.base_locators.XPathLocator'>}
class pomcorn.component.ListComponent(page: TPage, base_locator: XPathLocator | None = None, wait_until_visible: bool = True)[source]

Class to represent a list-like component.

It contains standard properties and methods for working with list-like components:

  • count

  • all

  • get_item_by_text()

Waits for base_item_locator property to be overridden or one of the attributes (item_locator or relative_item_locator) to be specified.

item_locator: XPathLocator | None = None
relative_item_locator: XPathLocator | None = None
property base_item_locator: XPathLocator

Get the base locator of list item.

Raises:
  • ValueError – If both attributes are specified.

  • NotImplementedError – If no attribute has been specified,

property count: int

Get count of list items.

property all: list[ListItemType]

Get all items of list.

__annotations__ = {'_item_class': type[~ListItemType], 'base_locator': 'locators.XPathLocator', 'item_locator': pomcorn.locators.base_locators.XPathLocator | None, 'relative_item_locator': pomcorn.locators.base_locators.XPathLocator | None}
classmethod get_list_item_class() type[ListItemType] | None[source]

Return class passed in Generic[ListItemType].

classmethod is_valid_item_class(item_class: Any) bool[source]

Check that specified item_class is valid.

Valid item_class should be a class and subclass of Component.

get_item_by_text(text: str) ListItemType[source]

Get list item by text.

PomcornElement

Note

This class is returned when the Element descriptor or the init_element/init_elements methods of the page or components are used.

class pomcorn.element.PomcornElement(web_view: WebView, locator: locators.TLocator)[source]

The class to represent a simple element (tag) on the page.

Contains methods for the interaction with an element on the browser page.

__init__(web_view: WebView, locator: locators.TLocator)[source]

Init page element.

Parameters:
  • web_view – Instance of a webview.

  • locator – Instance of a class to locate the element in the browser.

wait_until_visible()[source]

Wait until element becomes visible.

Raises:

TimeoutException – If after self.wait_timeout seconds the wait has not ended.

wait_until_invisible()[source]

Wait until element becomes invisible.

Raises:

TimeoutException – If after self.wait_timeout seconds the wait has not ended.

wait_until_clickable()[source]

Wait until element becomes clickable.

Raises:

TimeoutException – If after self.wait_timeout seconds the wait has not ended.

wait_until_text_is_in_element(text: str)[source]

Wait until text is present in element.

Raises:

TimeoutException – If after self.wait_timeout seconds the wait has not ended.

wait_until_not_exists_in_dom()[source]

Wait until element ceases to exist in DOM.

Raises:

TimeoutException – If after self.wait_timeout seconds the wait has not ended.

get_element(only_visible: bool = True) WebElement[source]

Get selenium instance(WebElement) of element.

Parameters:

only_visible – Flag for viewing visible elements. If this is True (default), then this method will only get visible elements, otherwise all the elements (including not visible) will be counted.

property exists_in_dom: bool

Check if element is present in html, can be not visible.

property is_displayed: bool

Check if element is displayed.

If element is not present in the html, return False.

property is_enabled: bool

Check if element is enabled.

It is primarily used with buttons.

property is_selected: bool

Check if element is selected.

It is predominantly used with radio buttons, dropdowns and checkboxes.

fill(text: str, only_visible: bool = True, clear: bool = True)[source]

Fill element with text.

Parameters:
  • text – The text that will be sent to the element to be filled.

  • only_visible – Flag for viewing visible elements. If this is True (default), then this method will only get visible elements, otherwise all elements (including not visible) will be counted.

  • clear – Whether the element needs to be cleared before filling it or not (default True).

clear(only_visible: bool = True)[source]

Clear element (input) and it’s value.

Parameters:

only_visible – Flag for viewing visible elements. If this is True (default), then this method will only get visible elements, otherwise all the elements (including not visible) will be counted.

send_keys(keys: str, only_visible: bool = True)[source]

Send keys to element.

Simulate user keystrokes.

Parameters:
get_text(only_visible: bool = True) str[source]

Get text from element.

Parameters:

only_visible – Flag for viewing visible elements. If this is True (default), then this method will only get visible elements, otherwise all the elements (including not visible) will be counted.

get_attribute(attribute_name: str, only_visible: bool = True) str[source]

Get value of attribute from element.

If attribute is not found, return empty string.

Parameters:
  • attribute_name – Element attribute name..

  • only_visible – Flag for viewing visible elements. If this is True (default), then this method will only get visible elements, otherwise all the elements (including not visible) will be counted.

set_attribute(attribute_name: str, value: str, only_visible: bool = True)[source]

Set value to element attribute.

Parameters:
  • attribute_name – Element attribute name.

  • value – New value for attribute.

  • only_visible – Flag for viewing visible elements. If this is True (default), then this method will only get visible elements, otherwise all the elements (including not visible) will be counted.

get_value(only_visible: bool = True)[source]

Get value of value attribute from element.

Parameters:

only_visible – Flag for viewing visible elements. If this is True (default), then this method will only get visible elements, otherwise all the elements (including not visible) will be counted.

select(value: str, only_visible: bool = True)[source]

Perform select on element.

Parameters:
  • value – Value for selecting an element based on visible text.

  • only_visible – Flag for viewing visible elements. If this is True (default), then this method will only get visible elements.

click(only_visible: bool = True, wait_until_clickable: bool = True)[source]

Click on element.

Parameters:
  • only_visible – Flag for viewing visible elements. If this is True (default), then this method will only get visible elements.

  • wait_until_clickable – Wait until the element is clickable before clicking, or not (default True).

drag_and_drop(target: PomcornElement[TLocator], only_visible: bool = True)[source]

Drag and drop page object on target object.

Parameters:
  • target – The element instance to drag into.

  • only_visible – Flag for viewing visible elements. If this is True (default), then this method will only get visible elements.

scroll_to(only_visible: bool = True)[source]

Scroll page until element is visible.

Parameters:

only_visible – Flag for viewing visible elements. If this is True (default), then this method will only get visible elements.

hover_to(only_visible: bool = True)[source]

Hover cursor to element.

Parameters:

only_visible – Flag for viewing visible elements. If this is True (default), then this method will only get visible elements.

get_value_of_css_property(property_name: str, only_visible: bool = True) str[source]

Return value of a CSS property.

Parameters:
  • property_name – Name of CSS property.

  • only_visible – Flag for viewing visible elements. If this is True (default), then this method will only get visible elements.

add_debug_mark()[source]

Set element background to red.

Should be used only for debugging.

remove_debug_mark()[source]

Remove debug mark.

__annotations__ = {}