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 thelocator
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 thelocator
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.
- execute_javascript(script: str, *args)[source]
Execute simple javascript.
- Parameters:
script – JavaScript code as a string object.
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.
Navigate absolute URL.
Replace the browser URL with the entered one.
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.
- __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].
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:
keys – The names of the keys in the form of a single string. More keys: https://www.selenium.dev/selenium/docs/api/py/webdriver/selenium.webdriver.common.keys.html # noqa
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_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.
- __annotations__ = {}