Utilities

This section shows general objects and helper functions that are used with this package.

Driver

class balderhub.webdriver.lib.utils.driver.BaseWebdriverDriverClass

Bases: BaseDriverClass, ABC

This is the base driver class for any balderhub-guicontrol packages that supports the webdriver interface.

abstract add_cookie(cookie_dict: dict) → None

This method adds a specific cookie to the current browser context.

Reference: https://www.w3.org/TR/webdriver2/#add-cookie

Parameters:: cookie_dict – the content of the cookie as dictionary

abstract property current_url: Url

Returns:: returns the current opened URL

abstract delete_all_cookies()

This method deletes all cookies in the current browser context.

Reference: https://www.w3.org/TR/webdriver2/#delete-all-cookies

abstract delete_cookie(name: str)

This method deletes a specific cookie from the current browser context.

Reference: https://www.w3.org/TR/webdriver2/#delete-cookie

Parameters:: name – the name of the cookie that should be deleted

abstract execute_async_script(script: str, *args: Any) → Any

This command executes the given script in the current browser context.

Reference: https://www.w3.org/TR/webdriver2/#execute-async-script

Parameters:

script – the script to be executed in the current browser context
args – arguments to be passed to the script

abstract execute_sync_script(script: str, *args: Any) → Any

This command executes the given script in the current browser context.

Reference: https://www.w3.org/TR/webdriver2/#execute-script

Parameters:

script – the script to be executed in the current browser context
args – arguments to be passed to the script

abstract find_bridge(selector: Selector) → FullyReidentifiableElementBridge | PartlyReidentifiableElementBridge

This method returns a specific bridge object identified by a selector. In case that the element can be reidentified completely by the selector (f.e. because the selector is By.ID) the method returns a

FullyReidentifiableElementBridge object. Otherwise, the method returns a PartlyReidentifiableElementBridge object.

Parameters:: selector – the selector to identify the element
Returns:: the bridge object (if it is reidentifiable a FullyReidentifiableElementBridge object, otherwise PartlyReidentifiableElementBridge)

abstract find_bridges(selector: Selector) → list[NotReidentifiableElementBridge]

This method returns a list of bridge objects identified by the provided selector.

Parameters:: selector – the selector to identify the elements
Returns:: a list of NotReidentifiableElementBridge objects (can not be reidentifiable because all have the same selector)

abstract get_all_cookies() → list[dict]

This method returns a list of all cookies in the current browser context.

Reference: https://www.w3.org/TR/webdriver2/#get-all-cookies

abstract get_bridge_for_raw_element(raw_element, parent: BaseWebdriverElementBridge | None = None) → NotReidentifiableElementBridge

This method returns the bridge object for a raw selenium element.

Parameters:

raw_element – the raw element of the browser-automation tool that is used here
parent – the parent bridge of the element that is a parent of this element (or None if there is no parent specified)

Returns:

the newly created bridge object

abstract get_cookie(name: str) → dict | None

This method returns a specific cookie by name.

Reference: https://www.w3.org/TR/webdriver2/#get-named-cookie

Parameters:: name – the name of the cookie
Returns:: the content of the dictionary or None if the cookie is not found

abstract get_page_source() → str

The Get Page Source command returns a string serialization of the DOM of session’s current browsing context active document.

Reference: https://www.w3.org/TR/webdriver2/#get-page-source

Returns:: a string serialization of the DOM of session’s current browsing context

abstract go_back()

This command causes the browser to traverse one step backward in the joint session history of session’s current top-level browsing context. This is equivalent to pressing the back button in the browser or invoking window.history.back.

Reference: https://www.w3.org/TR/webdriver2/#back

abstract go_forward()

This command causes the browser to traverse one step forwards in the joint session history of session’s current top-level browsing context. This is equivalent to pressing the forward button in the browser chrome or invoking window.history.forward.

Reference: https://www.w3.org/TR/webdriver2/#forward

abstract navigate_to(url: Url | str)

Opens the provided URL in the related browser window

Parameters:: url – the URL that should be opened

abstract property page_title: str

Returns:: the title of the page

abstract quit(): This method releases all resources belonging to this driver.

abstract refresh()

This command causes the browser to reload the page.

Reference: https://www.w3.org/TR/webdriver2/#refresh

WebElement Bridges

The bindings between the original web browser automation tool (like selenium) and the balderhub-guicontrol are provided within the bridge classes. This BalderHub project provides abstract bridge classes that supports the WebDriver protocol.

class balderhub.webdriver.lib.utils.web_element_bridges.BaseWebdriverElementBridge(driver: BaseWebdriverDriverClassT, parent: BaseWebdriverElementBridge | None)

Bases: BaseElementBridge, ABC

The abstract base class implementation for every element bridge. It holds common properties and methods that are used in all kinds of web element bridge classes.

abstract clear()

Clears the element

Reference: https://www.w3.org/TR/webdriver2/#element-clear

abstract click() → None

This method clicks the element.

Reference:

The Element Click command scrolls into view the element if it is not already pointer-interactable, and clicks its in-view center point.

If the element’s center point is obscured by another element, an element click intercepted error is returned. If the element is outside the viewport, an element not interactable error is returned.

property driver: BaseWebdriverDriverClassT

Returns:: returns the driver class, this bridge was created from

abstract exists() → bool

This method returns True if the element exists. An element exists if it is still part of the DOM.

Note

This does not mean, that it needs to be visible! Use the BaseWebElementBridge.is_displayed() method instead.`

Returns:: returns True if the element does exist otherwise false.

abstract find_bridge(selector: Selector) → FullyReidentifiableElementBridge | PartlyReidentifiableElementBridge

Method to directly returning the bridge of a specific raw web element by its selector that is a child of the current one. In case that the element can be reidentified completely by the selector (f.e. because the selector is By.ID) the method returns a FullyReidentifiableElementBridge object. Otherwise, the method returns a PartlyReidentifiableElementBridge object.

Parameters:: selector – the selector specifying the element (relative to this one)
Returns:: the bridge object of the element specified by the selector

abstract find_bridges(selector: Selector) → List[NotReidentifiableElementBridge]

Method to directly returning a list of bridge objects for raw web elements matching the provided relative selector as a child of the current one

Parameters:: selector – the selector specifying the elements (relative to this one)
Returns:: a list with all matching bridge objects (depending on the underlying framework)

abstract find_raw_element(selector: Selector) → RawElementT

Method to find a specific raw web element by its selector that is a child of the current one

Parameters:: selector – the selector specifying the element (relative to this one)
Returns:: the raw web element (depending on the underlying framework)

abstract find_raw_elements(selector: Selector) → List[RawElementT]

Method to find raw web elements matching the provided relative selector as a child of the current one

Parameters:: selector – the selector specifying the elements (relative to this one)
Returns:: the raw web element (depending on the underlying framework)

abstract get_attribute(name: Any) → str | None

Reference: https://www.w3.org/TR/webdriver2/#get-element-attribute

Parameters:: name – the attribute name
Returns:: a attribute value or None if there is no attribute for the provided name

abstract get_css_value(name: Any) → str

Reference: https://www.w3.org/TR/webdriver2/#get-element-css-value

Parameters:: name – the css property name
Returns:: the element css value

abstract get_property(name: Any) → Any

Reference: https://www.w3.org/TR/webdriver2/#get-element-property

Parameters:: name – the property name
Returns:: the element property value

abstract get_rect() → tuple[int, int, int, int]

Reference: https://www.w3.org/TR/webdriver2/#get-element-rect

Returns:: the rect of the element (x, y, width, height)

abstract get_tag_name() → str

Reference: https://www.w3.org/TR/webdriver2/#get-element-tag-name

Returns:: the element tag name as string

abstract get_text_content() → str

This method returns the text of the element as a string.

Returns:: returns the text of the element as a string

abstract is_clickable() → bool

This method returns True if the element is (theoretically) clickable.

Returns:: returns True if the element is (theoretically) clickable, otherwise False.

abstract is_displayed() → bool

This method returns True if the element is visible.

Returns:: returns True if the element does exist otherwise false.

abstract is_enabled() → bool

Reference: https://www.w3.org/TR/webdriver2/#is-element-enabled

Returns:: returns True if the element is enabled.

abstract is_selected() → bool

The Is Element Selected command determines if the referenced element is selected or not. This operation only makes sense on input elements of the Checkbox- and Radio Button states, or on option elements.

Reference: https://www.w3.org/TR/webdriver2/#is-element-selected

Returns:: returns True if the element is selected.

property parent: BaseWebdriverElementBridge | None

Returns:: returns the defined parent web element bridge if a parent does exist

abstract scroll_for(scroll_steps: int, *args, **kwargs)

This method scrolls for one step.

todo what unit should we use for scroll_steps?

Parameters:: scroll_steps – the number of steps to scroll (positive: scrolls forward, negative: scrolls backward)

abstract scroll_to_beginning(*args, **kwargs): This method scrolls to the beginning of the scrollable element. It needs to make sure, that after calling it, the scrollable element is always at the beginning of its content. It raises an error, in case the element can not be scrolled.

abstract scroll_to_end(*args, **kwargs): This method scrolls to the end of the scrollable element. It needs to make sure, that after calling it, the scrollable element is always at the end of its content. It raises an error, in case the element can not be scrolled.

abstract send_keys(text: str) → None

This method inserts a text into the field.

Reference: https://www.w3.org/TR/webdriver2/#element-send-keys

The Element Send Keys command scrolls into view the form control element and then sends the provided keys to the element. In case the element is not keyboard-interactable, an element not interactable error is returned.

Parameters:: text – the text that should be inserted into the field

class balderhub.webdriver.lib.utils.web_element_bridges.FullyReidentifiableElementBridge(driver: BaseWebdriverDriverClassT, selector: Selector, parent: FullyReidentifiableElementBridge | None = None)

Bases: BaseWebdriverElementBridge, ABC

A fully reidentifiable element bridge specifies the element in an absolute manner. It doesn’t matter if the element has a full absolute selector or has parents with re-identifiable selectors (so all parents need to be FullyReidentifiableElementBridge objects)

property parent: FullyReidentifiableElementBridge | None

Returns:: returns the defined parent web element bridge if a parent does exist

property raw_element: RawElementT

Returns:: returns the raw web element (depending on the underlying framework)

abstract re_identify_raw_element() → RawElementT

This method re-identifies the element by requesting it again from the main driver. This method automatically updates the internal reference for this object.

Returns:: the re-identified raw element

property selector: Selector

Returns:: the absolute selector this element bridge has.

class balderhub.webdriver.lib.utils.web_element_bridges.NotReidentifiableElementBridge(driver: BaseWebdriverDriverClassT, raw_element: RawElementT, parent: BaseWebdriverElementBridge | None = None)

Bases: BaseWebdriverElementBridge, ABC

A non reidentifiable element bridge can not re-identify an element by itself, because it does not specify absolute selectors.

class balderhub.webdriver.lib.utils.web_element_bridges.PartlyReidentifiableElementBridge(driver: BaseWebdriverDriverClassT, relative_selector: Selector, parent: PartlyReidentifiableElementBridge | NotReidentifiableElementBridge)

Bases: BaseWebdriverElementBridge, ABC

A partly reidentifiable element bridge specifies a bridge that does only have a relative selector to another bridge object that is not re-identifiable. This type of bridges are only reidentifiable if their parent element is in a reliable state.

property parent: PartlyReidentifiableElementBridge | NotReidentifiableElementBridge

Returns:: returns the defined parent web element bridge if a parent does exist

property raw_element: RawElementT

Returns:: returns the raw web element (depending on the underlying framework)

abstract re_identify_raw_element() → RawElementT

This method re-identifies the element by requesting it again from the main driver. This method automatically updates the internal reference for this object.

Returns:: the re-identified raw element

property relative_selector: Selector

Returns:: returns the relative selector.