Utilities

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

Drivers

class balderhub.selenium.lib.utils.drivers.BaseSeleniumDriver(*args, **kwargs)

Bases: BaseWebdriverDriverClass

Base Selenium Driver class (used by all selenium browser-automation drivers)

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

property current_url: str
Returns:

returns the current opened URL

delete_all_cookies()

This method deletes all cookies in the current browser context.

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

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

execute_async_script(script: str, *args) → 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

execute_sync_script(script: str, *args) → 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

find_bridge(selector: BaseSelector) → SeleniumFullyReidentifiableElementBridge

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)

find_bridges(selector: BaseSelector) → list[balderhub.selenium.lib.utils.web_element_bridges.selenium_not_reidentifiable_element_bridge.SeleniumNotReidentifiableElementBridge]

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)

find_raw_element(selector: BaseSelector) → WebElement

Returns the raw selenium element by the provided selector

Parameters:

selector – the selector that identifies the element

Returns:

the specific selenium element

find_raw_elements(selector: BaseSelector) → list[selenium.webdriver.remote.webelement.WebElement]

Returns the raw selenium elements by the provided selector

Parameters:

selector – the selector that identifies the elements

Returns:

a list of raw selenium elements

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

get_bridge_for_raw_element(raw_element: WebElement, parent: BaseWebdriverElementBridge | None = None) → SeleniumNotReidentifiableElementBridge

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

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

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

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

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

navigate_to(url: Url | str)

Opens the provided URL in the related browser window

Parameters:

url – the URL that should be opened

property page_title: str
Returns:

the title of the page

quit()

This method releases all resources belonging to this driver.

refresh()

This command causes the browser to reload the page.

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

property selenium_webdriver: WebDriver
Returns:

returns the raw selenium webdriver

class balderhub.selenium.lib.utils.drivers.SeleniumChromeDriver(selenium_service=None, selenium_options=None, keep_alive=True)

Bases: BaseSeleniumDriver

This driver is used when you directly want to use the chrome webdriver

class balderhub.selenium.lib.utils.drivers.SeleniumEdgeDriver(selenium_service=None, selenium_options=None, keep_alive=True)

Bases: BaseSeleniumDriver

This driver is used when you directly want to use the edge webdriver

class balderhub.selenium.lib.utils.drivers.SeleniumFirefoxDriver(selenium_service=None, selenium_options=None, keep_alive=True)

Bases: BaseSeleniumDriver

This driver is used when you directly want to use the Firefox webdriver

class balderhub.selenium.lib.utils.drivers.SeleniumIEDriver(selenium_service=None, selenium_options=None, keep_alive=True)

Bases: BaseSeleniumDriver

This driver is used when you directly want to use the IE webdriver

class balderhub.selenium.lib.utils.drivers.SeleniumRemoteDriver(command_executor, selenium_options, file_detector=None, keep_alive=True)

Bases: BaseSeleniumDriver

This driver is used when you directly want to use a remote webdriver

class balderhub.selenium.lib.utils.drivers.SeleniumSafariDriver(selenium_service=None, selenium_options=None, keep_alive=True, reuse_service=False)

Bases: BaseSeleniumDriver

This driver is used when you directly want to use the Safari webdriver

WebElementBridges

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

Bases: FullyReidentifiableElementBridge, SeleniumWebElementBridge

Selenium element bridge for elements that can be fully reidentified (f.e. because they are defined by an absolute ref).

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.

find_bridge(selector: BaseSelector) → SeleniumFullyReidentifiableElementBridge

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

re_identify_raw_element() → WebElement

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

class balderhub.selenium.lib.utils.web_element_bridges.SeleniumNotReidentifiableElementBridge(driver: BaseWebdriverDriverClassT, raw_element: RawElementT, parent: BaseWebdriverElementBridge | None = None)

Bases: NotReidentifiableElementBridge, SeleniumWebElementBridge

Selenium element bridge for elements that can not be reidentified (f.e. because they were the result of get_elements()).

exists()

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.

find_bridge(selector: BaseSelector) → SeleniumPartlyReidentifiableElementBridge

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

property parent: NotReidentifiableElementBridge | None
Returns:

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

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

Bases: PartlyReidentifiableElementBridge, SeleniumWebElementBridge

Selenium element bridge for elements that partly be reidentified (f.e. because they have a non-reidentifiable parent, but a relative ref).

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.

find_bridge(selector: BaseSelector) → SeleniumPartlyReidentifiableElementBridge

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

re_identify_raw_element() → WebElement

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

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

Bases: BaseWebdriverElementBridge, ABC

basic web-element-bridge implementation for Selenium

clear()

Clears the element

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

click()

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: BaseSeleniumDriver
Returns:

returns the driver class, this bridge was created from

abstract find_bridge(selector: BaseSelector) → SeleniumFullyReidentifiableElementBridge | SeleniumPartlyReidentifiableElementBridge

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

find_bridges(selector: BaseSelector) → List[SeleniumNotReidentifiableElementBridge]

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)

find_raw_element(selector: BaseSelector) → WebElement

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)

find_raw_elements(selector: BaseSelector) → List[WebElement]

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)

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

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

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

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)

get_tag_name() → str

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

Returns:

the element tag name as string

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

is_clickable() → bool

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

Returns:

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

is_displayed() → bool

This method returns True if the element is visible.

Returns:

returns True if the element does exist otherwise false.

is_enabled() → bool

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

Returns:

returns True if the element is enabled.

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 raw_element: WebElement
Returns:

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

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)

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.

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.

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

Further Utilities

class balderhub.selenium.lib.utils.Selector(by_type: By, identifier: str)

Bases: Selector

Specific BalderHUb selenium selector

class By(value)

Bases: By

Enum to specify the type of selector

get_selenium_selector() → tuple[selenium.webdriver.common.by.By, str]
Returns:

returns the raw selenium selector reference for this balderhub selector