Pre-built Objects

This section documents all the pre-built actions and executors available in the selenium package. These ready-to-use classes provide common functionality for web automation tasks.

Actions

Actions are concrete implementations of the BaseAction interface that perform specific operations on web elements or the browser.

Click Actions

class selenium_package.actions.click_on_element.ClickOnElement(web_instance: WebDriver | WebElement, web_element: WebElement)

Bases: BaseAction

Action that clicks on the element passed to the constructor.

class selenium_package.actions.click_on_the_screen.ClickOnTheScreen(web_instance: WebDriver, x_coordinate: int, y_coordinate: int)

Bases: BaseAction

Action that clicks on the screen at the point passed to the constructor.

Text Input Actions

class selenium_package.actions.insert_text.InsertText(web_instance: WebDriver, web_element: WebElement, text: str, using_js: bool = False)

Bases: BaseAction

Action that inserts the text passed to the constructor into the element passed to the constructor.

Tab Management Actions

class selenium_package.actions.go_to_tab_that_has_title.GoToTabThatHasTitle(web_instance: WebDriver, desired_tab_title: str = '')

Bases: BaseAction

Action that goes to the tab that has the exact same title passed to the constructor.

class selenium_package.actions.go_to_tab_that_contains_title.GoToTabThatContainsTitle(web_instance: WebDriver, desired_tab_title: str)

Bases: BaseAction

Action that goes to the tab that contains the title passed to the constructor.

class selenium_package.actions.go_to_tab_that_contains_url.GoToTabThatContainsUrl(web_instance: WebDriver, desired_url: str)

Bases: BaseAction

Action that goes to the tab that contains the url passed to the constructor.

class selenium_package.actions.close_all_tabs_except_that_has_title.CloseAllTabsExceptThatHasTitle(web_instance: WebDriver, desired_tab_title: str)

Bases: BaseAction

Action that closes all tabs except the one that has the exact same title passed to the constructor.

class selenium_package.actions.close_all_tabs_except_that_contains_title.CloseAllTabsExceptThatContainsTitle(web_instance: WebDriver, desired_tab_title: str)

Bases: BaseAction

Action that closes all tabs except the one that contains the title passed to the constructor.

Executors

Executors are concrete implementations of the BaseExecutor interface that control how actions are executed, including retry logic and conditional execution.

Basic Executors

class selenium_package.executors.default_executor.DefaultExecutor(action: BaseAction, web_element: WebElement = None, wait_to_verify_condition: int = None, timeout: int = 30)

Bases: BaseExecutor

Default executor that runs an action once and stops.

This is the simplest executor implementation that executes the action once and immediately considers the condition to stop as met.

class selenium_package.executors.timeout_executor.TimeoutExecutor(action: BaseAction, web_element: WebElement | None = None, wait_to_verify_condition: int | None = None, timeout: int = 30)

Bases: BaseExecutor

Executor that runs an action with a specific timeout.

This executor will run the action once and stop, with the timeout being handled by the base executor class.

class selenium_package.executors.retry_executor.RetryExecutor(action: BaseAction, web_element: WebElement | None = None, wait_to_verify_condition: int | None = 1, timeout: int = 30)

Bases: BaseExecutor

Executor that retries an action until a condition is met.

This executor will continuously retry the action until the condition to stop is met or the timeout is reached.

Retry Executors

class selenium_package.executors.retry_action_by_max_attempts.RetryActionByMaxAttempts(action: BaseAction, max_attempts: int = 1)

Bases: BaseExecutor

Executor that retries an action a specified number of times.

This executor will attempt to run the action up to max_attempts times. If the action fails after all attempts, it raises MaximumAttemptsReachedException.

run() → Any

Execute the action with retry logic.

This method will attempt to run the action up to max_attempts times. If the action succeeds, it returns the result. If it fails after all attempts, it raises MaximumAttemptsReachedException.

Returns:

Any: The result of the action if successful

Raises:

MaximumAttemptsReachedException: If all attempts failed

Element-based Retry Executors

class selenium_package.executors.retry_action_until_element_is_located.RetryActionUntilElementIsLocated(action: BaseAction, element_locator: Tuple[str, str], wait_to_verify_condition: int = None)

Bases: BaseExecutor

Executor that retries an action until an element is located.

This executor will continuously retry the action until the specified element is found on the page using the provided locator.

class selenium_package.executors.retry_action_until_element_has_a_property_value.RetryActionUntilElementHasAPropertyValue(action: BaseAction, web_element: WebElement, property_name: str, property_value: str, wait_to_verify_condition: int = None)

Bases: BaseExecutor

Executor that retries an action until an element’s property equals a value.

This executor will continuously retry the action until the specified web element’s property exactly matches the expected value.

class selenium_package.executors.retry_action_until_element_contains_a_property_value.RetryActionUntilElementContainsAPropertyValue(action: BaseAction, web_element: WebElement, property_name: str, property_value: str, wait_to_verify_condition: int = None)

Bases: BaseExecutor

Executor that retries an action until an element’s property contains a value.

This executor will continuously retry the action until the specified web element’s property contains the expected value.

Page-based Retry Executors

class selenium_package.executors.retry_action_until_page_title_is.RetryActionUntilPageTitleIs(action: BaseAction, desired_page_title: str, wait_to_verify_condition: int = None)

Bases: BaseExecutor

Executor that retries an action until the page title exactly matches specific text.

This executor will continuously retry the action until the current page title exactly matches the desired text.

class selenium_package.executors.retry_action_until_page_title_contains.RetryActionUntilPageTitleContains(action: BaseAction, desired_page_title: str, wait_to_verify_condition: int = 3)

Bases: BaseExecutor

Executor that retries an action until the page title contains specific text.

This executor will continuously retry the action until the current page title contains the desired text.

class selenium_package.executors.retry_action_until_url_contains.RetryActionUntilUrlContains(action: BaseAction, desired_url: str, wait_to_verify_condition: int = 3)

Bases: BaseExecutor

Executor that retries an action until the URL contains specific text.

This executor will continuously retry the action until the current URL contains the desired text.

Tab-based Retry Executors

class selenium_package.executors.retry_action_until_another_tab_is_opened.RetryActionUntilAnotherTabIsOpened(action: BaseAction, current_tabs_count: int, wait_to_verify_condition: int = 3)

Bases: BaseExecutor

Executor that retries an action until another tab is opened.

This executor will continuously retry the action until the number of browser tabs increases beyond the initial count.

class selenium_package.executors.retry_action_until_number_of_tabs_is.RetryActionUntilNumberOfTabsIs(action: BaseAction, desired_number_of_tabs: int)

Bases: BaseExecutor

Executor that retries an action until the number of tabs equals a specific value.

This executor will continuously retry the action until the browser has exactly the desired number of tabs open.

File-based Retry Executors

class selenium_package.executors.retry_action_until_new_file_has_been_detected.RetryActionUntilNewFileHasBeenDetected(action: BaseAction, path: Path, file_extension: str = None)

Bases: BaseExecutor

Executor that retries an action until a new file is detected in a directory.

This executor will continuously retry the action until a new file appears in the specified directory.

Text Input Retry Executors

class selenium_package.executors.retry_insert_text_until_value_is_correct.RetryInsertTextUntilValueIsCorrect(action: BaseAction, web_element: WebElement, desired_text: str, wait_to_verify_condition: int = None)

Bases: BaseExecutor

Executor that retries an action until an input element contains the correct text.

This executor will continuously retry the action until the specified input element’s value exactly matches the desired text.

Usage Examples

Here are some practical examples of how to use the pre-built actions and executors:

Basic Action Usage:

from selenium_package.actions import ClickOnElement, InsertText, RedirectToPage
from selenium.webdriver.common.by import By
from selenium import webdriver

driver = webdriver.Chrome()

# Navigate to a page
redirect_action = RedirectToPage(driver, "https://example.com")
redirect_action.execute_action()

# Find an element and click it
element = driver.find_element(By.ID, "submit-button")
click_action = ClickOnElement(driver, element)
click_action.execute_action()

# Insert text into an input field
input_element = driver.find_element(By.NAME, "username")
insert_action = InsertText(driver, input_element, "myusername")
insert_action.execute_action()

Using Executors for Retry Logic:

from selenium_package.executors import RetryActionUntilElementIsLocated, RetryActionByMaxAttempts
from selenium.webdriver.common.by import By

# Retry clicking until an element appears
click_action = ClickOnElement(driver, some_element)
retry_executor = RetryActionUntilElementIsLocated(
    click_action,
    (By.ID, "success-message")
)
retry_executor.run()

# Retry an action up to 3 times
retry_max_executor = RetryActionByMaxAttempts(click_action, max_attempts=3)
retry_max_executor.run()

Combining Actions and Executors:

from selenium_package.executors import RetryActionUntilUrlContains

# Navigate and wait for URL change
redirect_action = RedirectToPage(driver, "https://example.com/login")
url_retry_executor = RetryActionUntilUrlContains(redirect_action, "login")
url_retry_executor.run()