Element Interface¶

Warning

This is auto-generated interface documentation for the abstract Element class.

This is essential for providing a comprehensive overview of all available methods for the Element object.

For the actual signature, please refer to dyatel.base.element.Element.

Note

All of these methods will work in the same way for Group class instances, which represent a collection of elements.

The Element class is a fundamental building block for creating Page Object Models (POM) in web testing. It provides a comprehensive set of methods that allow you to interact with various web page elements which be found below.

class dyatel.base.element.Element(*args, **kwargs)¶

Element object crossroad. Should be defined as Page/Group class variable

locator: str = None¶

name: str = None¶

parent: Element | None = None¶

wait: bool = None¶

property driver_wrapper: DriverWrapper¶

Retrieves the driver wrapper instance.

Returns:: The current DriverWrapper instance that assigned for this object.
Return type:: DriverWrapper

set_text(text: str, silent: bool = False) → Element¶

Clear the current input field and type the provided text.

Parameters:

text (str) – The text to enter into the element.
silent (bool) – If True, suppresses logging.

Returns:

Element

send_keyboard_action(action: str | PlaywrightKeys) → Element¶

Send a keyboard action to the current element (e.g., press a key or shortcut).

Parameters:: action (str or KeyboardKeys) – The keyboard action to perform.
Returns:: Element

wait_visibility_without_error(*, timeout: int | float = 2.5, silent: bool = False) → Element¶

Wait for the element to become visible, without raising an error if it does not.

Note: The method requires the use of named arguments.

Selenium & Playwright:

Applied wait_condition() decorator integrates a 0.1 seconds delay for each iteration during the waiting process.

Appium:

Applied wait_condition() decorator integrates an exponential delay (starting at 0.1 seconds, up to a maximum of 1.6 seconds) which increases with each iteration during the waiting process.

Parameters:

timeout (int or float) – The maximum time to wait for the condition (in seconds). Default: QUARTER_WAIT_EL.
silent (bool) – If True, suppresses logging.

Returns:

Element

wait_hidden_without_error(*, timeout: int | float = 2.5, silent: bool = False) → Element¶

Wait for the element to become hidden, without raising an error if it does not.

Note: The method requires the use of named arguments.

Selenium & Playwright:

Applied wait_condition() decorator integrates a 0.1 seconds delay for each iteration during the waiting process.

Appium:

Applied wait_condition() decorator integrates an exponential delay (starting at 0.1 seconds, up to a maximum of 1.6 seconds) which increases with each iteration during the waiting process.

Parameters:

timeout (int or float) – The maximum time to wait for the condition (in seconds). Default: QUARTER_WAIT_EL.
silent (bool) – If True, suppresses logging.

Returns:

Element

wait_for_text(expected_text: str | None = None, *, timeout: int | float = 10, silent: bool = False) → Element¶

Wait for the presence of a specific text in the current element, or for any non-empty text.

Note: The method requires the use of named arguments except expected_text.

Selenium & Playwright:

Applied wait_condition() decorator integrates a 0.1 seconds delay for each iteration during the waiting process.

Appium:

Applied wait_condition() decorator integrates an exponential delay (starting at 0.1 seconds, up to a maximum of 1.6 seconds) which increases with each iteration during the waiting process.

Parameters:

expected_text (Optional[str]) – The text to wait for. None - any text; str - expected text.
timeout (int or float) – The maximum time to wait for the condition (in seconds). Default: WAIT_EL.
silent (bool) – If True, suppresses logging.

Returns:

Element

wait_for_value(expected_value: str | None = None, *, timeout: int | float = 10, silent: bool = False) → Element¶

Wait for a specific value in the current element, or for any non-empty value.

Note: The method requires the use of named arguments except expected_value.

Selenium & Playwright:

Applied wait_condition() decorator integrates a 0.1 seconds delay for each iteration during the waiting process.

Appium:

Applied wait_condition() decorator integrates an exponential delay (starting at 0.1 seconds, up to a maximum of 1.6 seconds) which increases with each iteration during the waiting process.

Parameters:

expected_value (Optional[str]) – The value to waiting for. None - any value; str - expected value.
timeout (int or float) – The maximum time to wait for the condition (in seconds). Default: WAIT_EL.
silent (bool) – If True, suppresses logging.

Returns:

Element

wait_enabled(*, timeout: int | float = 10, silent: bool = False) → Element¶

Wait for the element to become enabled and/or clickable.

Note: The method requires the use of named arguments.

Selenium & Playwright:

Applied wait_condition() decorator integrates a 0.1 seconds delay for each iteration during the waiting process.

Appium:

Applied wait_condition() decorator integrates an exponential delay (starting at 0.1 seconds, up to a maximum of 1.6 seconds) which increases with each iteration during the waiting process.

Parameters:

timeout (int or float) – The maximum time to wait for the condition (in seconds). Default: WAIT_EL.
silent (bool) – If True, suppresses logging.

Returns:

Element

wait_disabled(*, timeout: int | float = 10, silent: bool = False) → Element¶

Wait for the element to become disabled.

Note: The method requires the use of named arguments.

Selenium & Playwright:

Applied wait_condition() decorator integrates a 0.1 seconds delay for each iteration during the waiting process.

Appium:

Applied wait_condition() decorator integrates an exponential delay (starting at 0.1 seconds, up to a maximum of 1.6 seconds) which increases with each iteration during the waiting process.

Parameters:

timeout ([int, float]) – The maximum time to wait for the condition (in seconds). Default: WAIT_EL.
silent (bool) – If True, suppresses logging.

Returns:

Element

wait_for_size(expected_size: Size, *, timeout: int | float = 10, silent: bool = False) → Element¶

Wait until element size will be equal to given Size object

Note: The method requires the use of named arguments except expected_size.

Selenium & Playwright:

Applied wait_condition() decorator integrates a 0.1 seconds delay for each iteration during the waiting process.

Appium:

Applied wait_condition() decorator integrates an exponential delay (starting at 0.1 seconds, up to a maximum of 1.6 seconds) which increases with each iteration during the waiting process.

Parameters:

expected_size (Size) – expected element size
timeout (int or float) – The maximum time to wait for the condition (in seconds). Default: WAIT_EL.
silent (bool) – If True, suppresses logging.

Returns:

Element

wait_elements_count(expected_count: int, *, timeout: int | float = 10, silent: bool = False) → Element¶

Wait until the number of matching elements equals the expected count.

Note: The method requires the use of named arguments except expected_count.

Selenium & Playwright:

Applied wait_condition() decorator integrates a 0.1 seconds delay for each iteration during the waiting process.

Appium:

Applied wait_condition() decorator integrates an exponential delay (starting at 0.1 seconds, up to a maximum of 1.6 seconds) which increases with each iteration during the waiting process.

Parameters:

expected_count (int) – The expected number of elements.
timeout (Union[int, float]) – The maximum time to wait for the condition (in seconds). Default: WAIT_EL.
silent (bool) – If True, suppresses logging.

Returns:

Element

property all_elements: List[Element]¶

Returns a list of all matching elements.

Returns:: A list of wrapped Element objects.

is_visible(check_displaying: bool = True, silent: bool = False) → bool¶

Checks is the current element’s top-left corner or bottom-right corner is visible on the screen.

Parameters:

check_displaying (bool) – If True, the is_displayed() method will be called to further verify visibility. The check will stop if this method returns False.
silent (bool) – If True, suppresses logging.

Returns:

bool

is_fully_visible(check_displaying: bool = True, silent: bool = False) → bool¶

Check is current element top left corner and bottom right corner visible on current screen

Parameters:

check_displaying (bool) – If True, the is_displayed() method will be called to further verify visibility. The check will stop if this method returns False.
silent (bool) – If True, suppresses logging.

Returns:

bool

save_screenshot(file_name: str, screenshot_base: bytes | Image | None = None, convert_type: str | None = None) → Image¶

Saves a screenshot of the element.

Parameters:

file_name (str) – Path or filename for the screenshot.
screenshot_base (bytes, PIL.Image.Image) – Screenshot binary or image to use (optional).
convert_type (str) – Image conversion type before saving (optional).

Returns:

PIL.Image.Image

hide() → Element¶

Hides the element.

Returns:: Element

execute_script(script: str, *args) → Any¶

Executes a JavaScript script on the element.

Parameters:

script (str) – JavaScript code to be executed, referring to the element as arguments[0].
args – Additional arguments for the script, that appear in script as arguments[1] arguments[2] etc.

Returns:

typing.Any result from the script.

Asserts that the given screenshot matches the currently taken screenshot.

Parameters:

filename (str) – The full name of the screenshot file. If empty - filename will be generated based on test name & Element name argument & platform.
test_name (str) – The custom test name for generated filename. If empty - it will be determined automatically.
name_suffix (str) – A suffix to add to the filename. Useful for distinguishing between positive and negative cases for the same Element during one test.
threshold (Optional[int or float]) – The acceptable threshold for comparing screenshots. If None - takes default threshold or calculate its automatically based on screenshot size.
delay (Optional[int or float]) – The delay in seconds before taking the screenshot. If None - takes default delay.
scroll (bool) – Whether to scroll to the element before taking the screenshot.
remove (Optional[Element or List[Element]]) – Element to remove from the screenshot. Can be a single element or a list of elements.
fill_background (Optional[str or bool]) – The color to fill the background. If True, uses a default color (black). If a str, uses the specified color.
cut_box (Optional[CutBox]) – A CutBox specifying a region to cut from the screenshot. If None, no region is cut.
hide (Optional[Element or List[Element]]) – Element to hide in the screenshot. Can be a single element or a list of elements.

Returns:

None

Compares the currently taken screenshot to the expected screenshot and returns a result.

Parameters:

filename (str) – The full name of the screenshot file. If empty - filename will be generated based on test name & Element name argument & platform.
test_name (str) – The custom test name for generated filename. If empty - it will be determined automatically.
name_suffix (str) – A suffix to add to the filename. Useful for distinguishing between positive and negative cases for the same Element during one test.
threshold (Optional[int or float]) – The acceptable threshold for comparing screenshots. If None - takes default threshold or calculate its automatically based on screenshot size.
delay (Optional[int or float]) – The delay in seconds before taking the screenshot. If None - takes default delay.
scroll (bool) – Whether to scroll to the element before taking the screenshot.
remove (Optional[Element or List[Element]]) – Element to remove from the screenshot.
fill_background (Optional[str or bool]) – The color to fill the background. If True, uses a default color (black). If a str, uses the specified color.
cut_box (Optional[CutBox]) – A CutBox specifying a region to cut from the screenshot. If None, no region is cut.
hide – Element to hide in the screenshot. Can be a single element or a list of elements.

Returns:

typing.Tuple (bool, str) - result state and result message

get_element_info(element: Element | None = None) → str¶

Retrieves detailed logging information for the specified element.

Parameters:: element (Element or None) – The Element for which to collect logging data. If None, logging data for the parent element is used.
Returns:: str - A string containing the log data.

check() → Element¶

Checks the checkbox element.

Returns:: Element

clear_text(silent: bool = False) → Element¶

Clears the text of the element.

Parameters:: silent (bool) – If True, suppresses logging.
Returns:: Element

click(*, force_wait: bool = True, **kwargs) → Element¶

Clicks on the element.

Parameters:: force_wait (bool) – If True, waits for element visibility before clicking.

Selenium/Appium:

Selenium Safari using js click instead.

Parameters:: kwargs – compatibility arg for playwright

Playwright:

Parameters:: kwargs – any kwargs params from source API
Returns:: Element

click_in_alert() → Element¶

Perform a click on an element inside an alert box (Mobile only). Note: Automatically switches to native context of the browser.

Returns:: Element

click_into_center(silent: bool = False) → Element¶

Clicks at the center of the element.

Parameters:: silent (bool) – If True, suppresses logging.
Returns:: Element

click_outside(x: int = -5, y: int = -5) → Element¶

Perform a click outside the current element, by default 5px left and above it.

Parameters:

x (int) – Horizontal offset from the element to click.
y (int) – Vertical offset from the element to click.

Returns:

Element

property driver: WebDriver | WebDriver | Page¶

Retrieves the source driver instance, which could be a Selenium, Appium, or Playwright driver.

Returns:

Current source driver that assigned for this object, which is either

selenium.webdriver.remote.webdriver.WebDriver or

appium.webdriver.webdriver.WebDriver or

playwright.sync_api.Page instance.

property element: WebElement | WebElement | Locator¶

Returns a source element object, depending on the current driver in use.

Returns:

selenium.webdriver.remote.webelement.WebElement or

appium.webdriver.webelement.WebElement or

playwright.sync_api.Locator

get_all_texts(silent: bool = False) → List[str]¶

Retrieve text content from all matching elements.

Parameters:: silent (bool) – If True, suppresses logging.
Returns:: list of str - A list containing the text content of all matching elements.

get_attribute(attribute: str, silent: bool = False) → str¶

Retrieve a specific attribute from the current element.

Parameters:

attribute (str) – The name of the attribute to retrieve, such as ‘value’, ‘innerText’, ‘textContent’, etc.
silent (bool) – If True, suppresses logging.

Returns:

str - The value of the specified attribute.

get_elements_count(silent: bool = False) → int¶

Get the count of matching elements.

Parameters:: silent (bool) – If True, suppresses logging.
Returns:: int - The number of matching elements.

get_rect() → dict¶

Retrieve the size and position of the element as a dictionary.

Returns:: dict - A dictionary {‘x’, ‘y’, ‘width’, ‘height’} of the element.

hover(silent: bool = False) → Element¶

Hover the mouse over the current element.

Parameters:: silent (bool) – If True, suppresses logging.
Returns:: Element

hover_outside(x: int = 0, y: int = -5) → Element¶

Hover the mouse outside the current element, by default 5px above it.

Parameters:

x (int) – Horizontal offset from the element to hover.
y (int) – Vertical offset from the element to hover.

Returns:

Element

property inner_text: str¶

Returns the inner text of the element.

Returns:: str - element inner text

is_available() → bool¶

Checks if the element is available in DOM tree.

Returns:: bool - True if present in DOM

is_checked() → bool¶

Check if a checkbox or radio button is selected.

Returns:: bool - True if the checkbox or radio button is checked, False otherwise.

is_displayed(silent: bool = False) → bool¶

Checks if the element is displayed.

Parameters:: silent (bool) – If True, suppresses logging.
Returns:: bool

is_enabled(silent: bool = False) → bool¶

Check if the current element is enabled.

Parameters:: silent (bool) – If True, suppresses logging.
Returns:: bool - True if the element is enabled, False otherwise.

is_hidden(silent: bool = False) → bool¶

Checks if the element is hidden.

Parameters:: silent (bool) – If True, suppresses logging.
Returns:: bool

property location: Location¶

Get the location of the current element, including the x and y coordinates.

Returns:: Location - An object representing the element’s position.

locator_type: str = None¶

log(message: str, level: str = 'info') → None¶

Logs a message with detailed context in the following format:

# Format
[time][level][driver_index][module][function:line] <message>
# Example
[Aug 14][16:04:22.767][I][2_driver][play_element.py][is_displayed:328] Check visibility of "Mouse page"

Parameters:

message (str) – The log message to record.
level (str) – The logging level, which should be one of the values from LogLevel

Returns:

None

property screenshot_base: bytes¶

Returns the binary screenshot data of the element.

Returns:: bytes - screenshot binary

screenshot_image(screenshot_base: bytes | None = None) → Image¶

Returns a PIL.Image.Image object representing the screenshot of the web element. Appium iOS: Take driver screenshot and crop manually element from it

Parameters:: screenshot_base (bytes) – Screenshot binary data (optional). If None is provided then takes a new screenshot
Returns:: PIL.Image.Image

scroll_into_view(block: ScrollTo = 'center', behavior: ScrollTypes = 'instant', sleep: int | float = 0, silent: bool = False) → Element¶

Scrolls the element into view using a JavaScript script.

Parameters:

block (ScrollTo) – The scrolling block alignment. One of the ScrollTo options.
behavior (ScrollTypes) – The scrolling behavior. One of the ScrollTypes options.
sleep (int or float) – Delay in seconds after scrolling. Can be an integer or a float.
silent (bool) – If True, suppresses logging.

Returns:

Element

property size: Size¶

Get the size of the current element, including width and height.

Returns:: Size - An object representing the element’s dimensions.

property text: str¶

Returns the text of the element.

Returns:: str - element text

type_slowly(text: str, sleep_gap: float = 0.05, silent: bool = False) → Element¶

Types text into the element slowly with a delay between keystrokes.

Parameters:

text (str) – The text to be typed.
sleep_gap (float) – Delay between keystrokes in seconds.
silent (bool) – If True, suppresses logging.

Returns:

Element

type_text(text: str | KeyboardKeys, silent: bool = False) → Element¶

Types text into the element.

Parameters:

text (str, KeyboardKeys) – The text to be typed or a keyboard key.
silent (bool) – If True, suppresses logging.

Returns:

Element

uncheck() → Element¶

Unchecks the checkbox element.

Returns:: Element

property value: str¶

Returns the value of the element.

Returns:: str - element value

wait_availability(*, timeout: int = 10, silent: bool = False) → Element¶

Waits until the element becomes available in DOM tree.

Note: The method requires the use of named arguments.

Selenium:

Applied wait_condition() decorator integrates a 0.1 seconds delay for each iteration during the waiting process.

Appium:

Applied wait_condition() decorator integrates an exponential delay (starting at 0.1 seconds, up to a maximum of 1.6 seconds) which increases with each iteration during the waiting process.

Parameters:

timeout (int) – The maximum time to wait for the condition (in seconds). Default: WAIT_EL.
silent (bool) – If True, suppresses logging.

Returns:

Element

wait_hidden(*, timeout: int = 10, silent: bool = False) → Element¶

Waits until the element becomes hidden. Note: The method requires the use of named arguments.

Selenium:

Applied wait_condition() decorator integrates a 0.1 seconds delay for each iteration during the waiting process.

Appium:

Applied wait_condition() decorator integrates an exponential delay (starting at 0.1 seconds, up to a maximum of 1.6 seconds) which increases with each iteration during the waiting process.

Parameters:

timeout (int) – The maximum time to wait for the condition (in seconds). Default: WAIT_EL.
silent (bool) – If True, suppresses logging.

Returns:

Element

wait_visibility(*, timeout: int = 10, silent: bool = False) → Element¶

Waits until the element becomes visible. Note: The method requires the use of named arguments.

Selenium:

Applied wait_condition() decorator integrates a 0.1 seconds delay for each iteration during the waiting process.

Appium:

Applied wait_condition() decorator integrates an exponential delay (starting at 0.1 seconds, up to a maximum of 1.6 seconds) which increases with each iteration during the waiting process.

Parameters:

timeout (int) – The maximum time to wait for the condition (in seconds). Default: WAIT_EL.
silent (bool) – If True, suppresses logging.

Returns:

Element