WebDriver

qa_pytest_webdriver

__all__ = ['By', 'Locator', 'SearchContext', 'SeleniumConfiguration', 'SeleniumSteps', 'SeleniumTests'] module-attribute

By

Factory for Selenium locators, matching Selenium's By API.

Provides static methods to create Locator objects for each Selenium locator strategy.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

class By:
    """
    Factory for Selenium locators, matching Selenium's By API.

    Provides static methods to create Locator objects for each Selenium locator strategy.
    """

    @staticmethod
    def id(value: str) -> Locator:
        """
        Creates a locator for elements with the given id attribute.

        Args:
            value (str): The id value.
        Returns:
            Locator: The locator object.
        """
        return Locator(_By.ID, value)

    @staticmethod
    def xpath(value: str) -> Locator:
        """
        Creates a locator for elements matching the given XPath expression.

        Args:
            value (str): The XPath expression.
        Returns:
            Locator: The locator object.
        """
        return Locator(_By.XPATH, value)

    @staticmethod
    def link_text(value: str) -> Locator:
        """
        Creates a locator for elements with the given link text.

        Args:
            value (str): The link text.
        Returns:
            Locator: The locator object.
        """
        return Locator(_By.LINK_TEXT, value)

    @staticmethod
    def partial_link_text(value: str) -> Locator:
        """
        Creates a locator for elements with the given partial link text.

        Args:
            value (str): The partial link text.
        Returns:
            Locator: The locator object.
        """
        return Locator(_By.PARTIAL_LINK_TEXT, value)

    @staticmethod
    def name(value: str) -> Locator:
        """
        Creates a locator for elements with the given name attribute.

        Args:
            value (str): The name value.
        Returns:
            Locator: The locator object.
        """
        return Locator(_By.NAME, value)

    @staticmethod
    def tag_name(value: str) -> Locator:
        """
        Creates a locator for elements with the given tag name.

        Args:
            value (str): The tag name.
        Returns:
            Locator: The locator object.
        """
        return Locator(_By.TAG_NAME, value)

    @staticmethod
    def class_name(value: str) -> Locator:
        """
        Creates a locator for elements with the given class name.

        Args:
            value (str): The class name.
        Returns:
            Locator: The locator object.
        """
        return Locator(_By.CLASS_NAME, value)

    @staticmethod
    def css_selector(value: str) -> Locator:
        """
        Creates a locator for elements matching the given CSS selector.

        Args:
            value (str): The CSS selector.
        Returns:
            Locator: The locator object.
        """
        return Locator(_By.CSS_SELECTOR, value)

class_name(value) staticmethod

Creates a locator for elements with the given class name.

Parameters:

Name	Type	Description	Default
value	str	The class name.	required

Returns: Locator: The locator object.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

@staticmethod
def class_name(value: str) -> Locator:
    """
    Creates a locator for elements with the given class name.

    Args:
        value (str): The class name.
    Returns:
        Locator: The locator object.
    """
    return Locator(_By.CLASS_NAME, value)

css_selector(value) staticmethod

Creates a locator for elements matching the given CSS selector.

Parameters:

Name	Type	Description	Default
value	str	The CSS selector.	required

Returns: Locator: The locator object.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

@staticmethod
def css_selector(value: str) -> Locator:
    """
    Creates a locator for elements matching the given CSS selector.

    Args:
        value (str): The CSS selector.
    Returns:
        Locator: The locator object.
    """
    return Locator(_By.CSS_SELECTOR, value)

id(value) staticmethod

Creates a locator for elements with the given id attribute.

Parameters:

Name	Type	Description	Default
value	str	The id value.	required

Returns: Locator: The locator object.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

@staticmethod
def id(value: str) -> Locator:
    """
    Creates a locator for elements with the given id attribute.

    Args:
        value (str): The id value.
    Returns:
        Locator: The locator object.
    """
    return Locator(_By.ID, value)

link_text(value) staticmethod

Creates a locator for elements with the given link text.

Parameters:

Name	Type	Description	Default
value	str	The link text.	required

Returns: Locator: The locator object.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

@staticmethod
def link_text(value: str) -> Locator:
    """
    Creates a locator for elements with the given link text.

    Args:
        value (str): The link text.
    Returns:
        Locator: The locator object.
    """
    return Locator(_By.LINK_TEXT, value)

name(value) staticmethod

Creates a locator for elements with the given name attribute.

Parameters:

Name	Type	Description	Default
value	str	The name value.	required

Returns: Locator: The locator object.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

@staticmethod
def name(value: str) -> Locator:
    """
    Creates a locator for elements with the given name attribute.

    Args:
        value (str): The name value.
    Returns:
        Locator: The locator object.
    """
    return Locator(_By.NAME, value)

partial_link_text(value) staticmethod

Creates a locator for elements with the given partial link text.

Parameters:

Name	Type	Description	Default
value	str	The partial link text.	required

Returns: Locator: The locator object.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

@staticmethod
def partial_link_text(value: str) -> Locator:
    """
    Creates a locator for elements with the given partial link text.

    Args:
        value (str): The partial link text.
    Returns:
        Locator: The locator object.
    """
    return Locator(_By.PARTIAL_LINK_TEXT, value)

tag_name(value) staticmethod

Creates a locator for elements with the given tag name.

Parameters:

Name	Type	Description	Default
value	str	The tag name.	required

Returns: Locator: The locator object.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

@staticmethod
def tag_name(value: str) -> Locator:
    """
    Creates a locator for elements with the given tag name.

    Args:
        value (str): The tag name.
    Returns:
        Locator: The locator object.
    """
    return Locator(_By.TAG_NAME, value)

xpath(value) staticmethod

Creates a locator for elements matching the given XPath expression.

Parameters:

Name	Type	Description	Default
value	str	The XPath expression.	required

Returns: Locator: The locator object.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

@staticmethod
def xpath(value: str) -> Locator:
    """
    Creates a locator for elements matching the given XPath expression.

    Args:
        value (str): The XPath expression.
    Returns:
        Locator: The locator object.
    """
    return Locator(_By.XPATH, value)

Locator dataclass

Represents a Selenium locator as a (by, value) pair.

Attributes:

Name	Type	Description
by	str	The Selenium locator strategy (e.g., By.ID, By.XPATH).
value	str	The locator value.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

@dataclass(frozen=True)
class Locator:
    """
    Represents a Selenium locator as a (by, value) pair.

    Attributes:
        by (str): The Selenium locator strategy (e.g., By.ID, By.XPATH).
        value (str): The locator value.
    """
    by: str
    value: str

    def as_tuple(self) -> Tuple[str, str]:
        """
        Returns the locator as a tuple (by, value), suitable for Selenium APIs.

        Returns:
            Tuple[str, str]: The locator as a tuple.
        """
        return (self.by, self.value)

by instance-attribute

value instance-attribute

__init__(by, value)

as_tuple()

Returns the locator as a tuple (by, value), suitable for Selenium APIs.

Returns:

Type	Description
Tuple[str, str]	Tuple[str, str]: The locator as a tuple.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

def as_tuple(self) -> Tuple[str, str]:
    """
    Returns the locator as a tuple (by, value), suitable for Selenium APIs.

    Returns:
        Tuple[str, str]: The locator as a tuple.
    """
    return (self.by, self.value)

SearchContext

Bases: Protocol

Protocol for Selenium search contexts (e.g., WebDriver, WebElement).

Provides methods to find single or multiple elements using Selenium's locator strategy.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

class SearchContext(Protocol):
    """
    Protocol for Selenium search contexts (e.g., WebDriver, WebElement).

    Provides methods to find single or multiple elements using Selenium's locator strategy.
    """

    def find_element(self, by: str, value: Optional[str]) -> WebElement: ...

    def find_elements(
        self, by: str, value: Optional[str]) -> List[WebElement]: ...

find_element(by, value)

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

def find_element(self, by: str, value: Optional[str]) -> WebElement: ...

find_elements(by, value)

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

def find_elements(
    self, by: str, value: Optional[str]) -> List[WebElement]: ...

SeleniumConfiguration

Bases: BaseConfiguration

SeleniumConfiguration extends BaseConfiguration to provide Selenium-specific configuration options.

This class exposes properties for retrieving the UI URL and initializing the Selenium WebDriver Service, leveraging configuration values and dynamic driver management.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_configuration.py

class SeleniumConfiguration(BaseConfiguration):
    """
    SeleniumConfiguration extends BaseConfiguration to provide Selenium-specific configuration options.

    This class exposes properties for retrieving the UI URL and initializing the Selenium WebDriver Service,
    leveraging configuration values and dynamic driver management.
    """

    @cached_property
    @final
    def landing_page(self) -> str:
        """
        Returns the UI URL from the configuration parser.

        Returns:
            str: The URL string specified under the "selenium/base" in the configuration.

        Raises:
            KeyError: If the "selenium" section or "base" key is not present in the configuration parser.
        """
        return self.parser["selenium"]["landing_page"]

    # FIXME Service here is imported from selenium.webdriver.chrome.service
    # which makes this method specific to ChromeDriver.
    @cached_property
    @final
    def service(self) -> Service:
        """
        Creates and returns a Selenium WebDriver Service instance using the ChromeDriverManager.

        Returns:
            Service: An instance of Selenium's Service class, initialized with the path to the ChromeDriver executable
            installed by ChromeDriverManager.

        Note:
            This method currently supports only ChromeDriver, but may be extended to support different services
            based on configuration in the future.
        """
        # NOTE may add support for providing different services per configuration
        return Service(ChromeDriverManager().install())

landing_page cached property

Returns the UI URL from the configuration parser.

Returns:

Name	Type	Description
str	str	The URL string specified under the "selenium/base" in the configuration.

Raises:

Type	Description
KeyError	If the "selenium" section or "base" key is not present in the configuration parser.

service cached property

Creates and returns a Selenium WebDriver Service instance using the ChromeDriverManager.

Returns:

Name	Type	Description
Service	Service	An instance of Selenium's Service class, initialized with the path to the ChromeDriver executable
	Service	installed by ChromeDriverManager.

Note

This method currently supports only ChromeDriver, but may be extended to support different services based on configuration in the future.

SeleniumSteps

Bases: GenericSteps[TConfiguration]

BDD-style step definitions for Selenium-based UI operations.

Type Parameters

TConfiguration: The configuration type, must be a SeleniumConfiguration.

Attributes:

Name	Type	Description
_web_driver	WebDriver	The Selenium WebDriver instance used for browser automation.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

class SeleniumSteps[TConfiguration: SeleniumConfiguration](
    GenericSteps[TConfiguration]
):
    """
    BDD-style step definitions for Selenium-based UI operations.

    Type Parameters:
        TConfiguration: The configuration type, must be a SeleniumConfiguration.

    Attributes:
        _web_driver (WebDriver): The Selenium WebDriver instance used for browser automation.
    """
    _web_driver: WebDriver

    @final
    @Context.traced
    def clicking_once(self, element_supplier: ElementSupplier) -> Self:
        """
        Clicks the element supplied by the given callable.

        Args:
            element_supplier (ElementSupplier): Callable returning a WebElement.
        Returns:
            Self: The current step instance for chaining.
        """
        element_supplier().click()
        return self

    @overload
    def clicking(self, element: Locator) -> Self: ...

    @overload
    def clicking(self, element: ElementSupplier) -> Self: ...

    @final
    def clicking(self, element: LocatorOrSupplier) -> Self:
        """
        Clicks the element specified by a locator or supplier, with retry logic.

        Args:
            element (LocatorOrSupplier): Locator or callable returning a WebElement.
        Returns:
            Self: The current step instance for chaining.
        """
        return self.retrying(lambda: self.clicking_once(self._resolve(element)))

    @final
    @Context.traced
    def typing_once(self, element_supplier: ElementSupplier, text: str) -> Self:
        """
        Types the given text into the element supplied by the callable.

        Args:
            element_supplier (ElementSupplier): Callable returning a WebElement.
            text (str): The text to type.
        Returns:
            Self: The current step instance for chaining.
        """
        element = element_supplier()
        element.clear()
        element.send_keys(text)
        return self

    @overload
    def typing(self, element: Locator, text: str) -> Self: ...

    @overload
    def typing(self, element: ElementSupplier, text: str) -> Self: ...

    @final
    def typing(self, element: LocatorOrSupplier, text: str) -> Self:
        """
        Types the given text into the element specified by a locator or supplier, with retry logic.

        Args:
            element (LocatorOrSupplier): Locator or callable returning a WebElement.
            text (str): The text to type.
        Returns:
            Self: The current step instance for chaining.
        """
        return self.retrying(lambda: self.typing_once(self._resolve(element), text))

    @final
    def the_element(self, locator: Locator, by_rule: Matcher[WebElement], context: Optional[SearchContext] = None) -> Self:
        """
        Asserts that the element found by the locator matches the given matcher.

        Args:
            locator (Locator): The locator to find the element.
            by_rule (Matcher[WebElement]): Matcher for the element.
            context (Optional[SearchContext]): Optional search context.
        Returns:
            Self: The current step instance for chaining.
        """
        return self.eventually_assert_that(lambda: self._element(locator, context), by_rule)

    @final
    def the_elements(self, locator: Locator, by_rule: Matcher[Iterator[WebElement]], context: Optional[SearchContext] = None) -> Self:
        """
        Asserts that the elements found by the locator match the given matcher.

        Args:
            locator (Locator): The locator to find the elements.
            by_rule (Matcher[Iterator[WebElement]]): Matcher for the elements iterator.
            context (Optional[SearchContext]): Optional search context.
        Returns:
            Self: The current step instance for chaining.
        """
        return self.eventually_assert_that(lambda: self._elements(locator, context), by_rule)

    @final
    @Context.traced
    def _elements(
        self, locator: Locator, context: Optional[SearchContext] = None
    ) -> Iterator[WebElement]:
        return iter((context or self._web_driver).find_elements(*locator.as_tuple()))

    @final
    @Context.traced
    def _element(
        self, locator: Locator, context: Optional[SearchContext] = None
    ) -> WebElement:
        return self._scroll_into_view(
            (context or self._web_driver).find_element(*locator.as_tuple())
        )

    def _scroll_into_view(self, element: WebElement) -> WebElement:
        self._web_driver.execute_script(  # type: ignore
            "arguments[0].scrollIntoView({behavior: 'smooth', block: 'center'});", element)
        return element

    @final
    def _resolve(self, element: LocatorOrSupplier) -> ElementSupplier:
        if isinstance(element, Locator):
            return lambda: self._element(element)
        return element

clicking(element)

clicking(element: Locator) -> Self

clicking(element: ElementSupplier) -> Self

Clicks the element specified by a locator or supplier, with retry logic.

Parameters:

Name	Type	Description	Default
element	LocatorOrSupplier	Locator or callable returning a WebElement.	required

Returns: Self: The current step instance for chaining.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

@final
def clicking(self, element: LocatorOrSupplier) -> Self:
    """
    Clicks the element specified by a locator or supplier, with retry logic.

    Args:
        element (LocatorOrSupplier): Locator or callable returning a WebElement.
    Returns:
        Self: The current step instance for chaining.
    """
    return self.retrying(lambda: self.clicking_once(self._resolve(element)))

clicking_once(element_supplier)

Clicks the element supplied by the given callable.

Parameters:

Name	Type	Description	Default
element_supplier	ElementSupplier	Callable returning a WebElement.	required

Returns: Self: The current step instance for chaining.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

@final
@Context.traced
def clicking_once(self, element_supplier: ElementSupplier) -> Self:
    """
    Clicks the element supplied by the given callable.

    Args:
        element_supplier (ElementSupplier): Callable returning a WebElement.
    Returns:
        Self: The current step instance for chaining.
    """
    element_supplier().click()
    return self

the_element(locator, by_rule, context=None)

Asserts that the element found by the locator matches the given matcher.

Parameters:

Name	Type	Description	Default
locator	Locator	The locator to find the element.	required
by_rule	Matcher[WebElement]	Matcher for the element.	required
context	Optional[SearchContext]	Optional search context.	None

Returns: Self: The current step instance for chaining.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

@final
def the_element(self, locator: Locator, by_rule: Matcher[WebElement], context: Optional[SearchContext] = None) -> Self:
    """
    Asserts that the element found by the locator matches the given matcher.

    Args:
        locator (Locator): The locator to find the element.
        by_rule (Matcher[WebElement]): Matcher for the element.
        context (Optional[SearchContext]): Optional search context.
    Returns:
        Self: The current step instance for chaining.
    """
    return self.eventually_assert_that(lambda: self._element(locator, context), by_rule)

the_elements(locator, by_rule, context=None)

Asserts that the elements found by the locator match the given matcher.

Parameters:

Name	Type	Description	Default
locator	Locator	The locator to find the elements.	required
by_rule	Matcher[Iterator[WebElement]]	Matcher for the elements iterator.	required
context	Optional[SearchContext]	Optional search context.	None

Returns: Self: The current step instance for chaining.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

@final
def the_elements(self, locator: Locator, by_rule: Matcher[Iterator[WebElement]], context: Optional[SearchContext] = None) -> Self:
    """
    Asserts that the elements found by the locator match the given matcher.

    Args:
        locator (Locator): The locator to find the elements.
        by_rule (Matcher[Iterator[WebElement]]): Matcher for the elements iterator.
        context (Optional[SearchContext]): Optional search context.
    Returns:
        Self: The current step instance for chaining.
    """
    return self.eventually_assert_that(lambda: self._elements(locator, context), by_rule)

typing(element, text)

typing(element: Locator, text: str) -> Self

typing(element: ElementSupplier, text: str) -> Self

Types the given text into the element specified by a locator or supplier, with retry logic.

Parameters:

Name	Type	Description	Default
element	LocatorOrSupplier	Locator or callable returning a WebElement.	required
text	str	The text to type.	required

Returns: Self: The current step instance for chaining.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

@final
def typing(self, element: LocatorOrSupplier, text: str) -> Self:
    """
    Types the given text into the element specified by a locator or supplier, with retry logic.

    Args:
        element (LocatorOrSupplier): Locator or callable returning a WebElement.
        text (str): The text to type.
    Returns:
        Self: The current step instance for chaining.
    """
    return self.retrying(lambda: self.typing_once(self._resolve(element), text))

typing_once(element_supplier, text)

Types the given text into the element supplied by the callable.

Parameters:

Name	Type	Description	Default
element_supplier	ElementSupplier	Callable returning a WebElement.	required
text	str	The text to type.	required

Returns: Self: The current step instance for chaining.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_steps.py

@final
@Context.traced
def typing_once(self, element_supplier: ElementSupplier, text: str) -> Self:
    """
    Types the given text into the element supplied by the callable.

    Args:
        element_supplier (ElementSupplier): Callable returning a WebElement.
        text (str): The text to type.
    Returns:
        Self: The current step instance for chaining.
    """
    element = element_supplier()
    element.clear()
    element.send_keys(text)
    return self

SeleniumTests

Bases: AbstractTestsBase[TSteps, TConfiguration]

Base class for Selenium-based UI test cases.

This class manages the lifecycle of a Selenium WebDriver for each test method. It is generic over the types of steps and configuration used.

Attributes:

Name	Type	Description
_web_driver	WebDriver	The Selenium WebDriver instance (not thread safe).

Type Parameters

TSteps: The type of the steps class, typically derived from SeleniumSteps. TConfiguration: The type of the configuration class, typically derived from SeleniumConfiguration.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_tests.py

class SeleniumTests[
    TSteps: SeleniumSteps[Any],
    TConfiguration: SeleniumConfiguration
](AbstractTestsBase[TSteps, TConfiguration]):
    """
    Base class for Selenium-based UI test cases.

    This class manages the lifecycle of a Selenium WebDriver for each test method.
    It is generic over the types of steps and configuration used.

    Attributes:
        _web_driver (WebDriver): The Selenium WebDriver instance (not thread safe).

    Type Parameters:
        TSteps: The type of the steps class, typically derived from SeleniumSteps.
        TConfiguration: The type of the configuration class, typically derived from SeleniumConfiguration.
    """
    _web_driver: WebDriver  # not thread safe

    @property
    def web_driver(self) -> WebDriver:
        '''
        Returns the web driver instance.

        Returns:
            WebDriver: The web driver instance.
        '''
        return self._web_driver

    @override
    def setup_method(self):
        '''
        Initializes the Selenium WebDriver before each test method.
        '''
        super().setup_method()

        options = Options()
        options.add_argument("--start-maximized")  # type: ignore
        self._web_driver = Chrome(
            options,
            self._configuration.service)

    @override
    def teardown_method(self):
        '''
        Quits the Selenium WebDriver after each test method.
        '''
        try:
            self._web_driver.quit()
        finally:
            super().teardown_method()

web_driver property

Returns the web driver instance.

Returns:

Name	Type	Description
WebDriver	WebDriver	The web driver instance.

setup_method()

Initializes the Selenium WebDriver before each test method.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_tests.py

@override
def setup_method(self):
    '''
    Initializes the Selenium WebDriver before each test method.
    '''
    super().setup_method()

    options = Options()
    options.add_argument("--start-maximized")  # type: ignore
    self._web_driver = Chrome(
        options,
        self._configuration.service)

teardown_method()

Quits the Selenium WebDriver after each test method.

Source code in qa-pytest-webdriver/src/qa_pytest_webdriver/selenium_tests.py

@override
def teardown_method(self):
    '''
    Quits the Selenium WebDriver after each test method.
    '''
    try:
        self._web_driver.quit()
    finally:
        super().teardown_method()