API Reference

API compatibility / stability

lemoncheesecake-selenium follows the well know Semantic Versioning for its public API. Since lemoncheesecake-selenium is still on 0.y.z major version, API breaking changes might occur; it is then advised to pin the version.

What is considered as “public” is everything documented on https://lemoncheesecake-selenium.readthedocs.io. Everything else is internal and is subject to changes at anytime.

Selector

class lemoncheesecake_selenium.Selector(driver)

Factory of Selection instances.

Parameters:

driver (WebDriver) –

by_id(value)

Get a Selection using element’s id

Parameters:

value – a value related to by

Returns:

Selection

by_xpath(value)

Get a Selection using element’s xpath

Parameters:

value – a value related to by

Returns:

Selection

by_link_text(value)

Get a Selection using element’s link text

Parameters:

value – a value related to by

Returns:

Selection

by_partial_link_text(value)

Get a Selection using element’s partial link text

Parameters:

value – a value related to by

Returns:

Selection

by_name(value)

Get a Selection using element’s name

Parameters:

value – a value related to by

Returns:

Selection

by_tag_name(value)

Get a Selection using element’s tag name

Parameters:

value – a value related to by

Returns:

Selection

by_class_name(value)

Get a Selection using element’s class name

Parameters:

value – a value related to by

Returns:

Selection

by_css_selector(value)

Get a Selection using element’s css selector

Parameters:

value – a value related to by

Returns:

Selection

Selection

class lemoncheesecake_selenium.Selection(driver, by, value)
default_timeout = 10

The default timeout value to use if no timeout argument is passed to the must_be_waited_until() / must_be_waited_until_not() methods.

screenshot_on_exceptions = False

Whether or not a screenshot will be automatically saved upon upon WebDriverException exceptions on methods such as Selection.set_text(), Selection.click(), etc…

screenshot_on_failed_checks = False

Whether or not a screenshot will be automatically saved upon failed checks with Selection.check_element(), Selection.require_element() and Selection.assert_element() methods.

must_be_waited_until(expected_condition, *, timeout=None, extra_args=())

The method can be called to set an explicit wait (see https://selenium-python.readthedocs.io/waits.html#explicit-waits) on the underlying element so that it is considered available when the expected_condition is met.

Parameters:

  • expected_condition (Callable) – a callable that will take a locator (a tuple of (by, path)) as first argument

  • timeout (Optional[int]) – wait timeout (will be Selection.default_timeout if no argument is passed)

  • extra_args – extra arguments to be passed to the expected_condition callable

Returns:

self, meaning this method can be chain called

must_be_waited_until_not(expected_condition, *, timeout=None, extra_args=())

The method can be called to set an explicit wait (see https://selenium-python.readthedocs.io/waits.html#explicit-waits) on the underlying element so that it is considered available when the expected_condition is NOT met.

Parameters:

  • expected_condition (Callable) – a callable that will take a locator (a tuple of (by, path)) as first argument

  • timeout (Optional[int]) – wait timeout (will be Selection.default_timeout if no argument is passed)

  • extra_args – extra arguments to be passed to the expected_condition callable

Returns:

self, meaning this method can be chain called

property element: WebElement
Returns:

the underlying WebElement with the explicit wait taken into account (if any has been set)

property elements: Sequence[WebElement]
Returns:

the underlying WebElement list with the explicit wait taken into account (if any has been set)

click()

Click on the element.

clear()

Clear the element.

set_text(text)

Set to text in the element.

Parameters:

text (str) – text to be set

check_element(expected)

Check that the element matches expected using the lemoncheesecake.matching.check_that() function.

Parameters:

expected (Matcher) – a Matcher instance whose matches method will be called with the WebElement that has been found

check_no_element()

Check that the element is not present using the lemoncheesecake.matching.check_that() function.

require_element(expected)

Check that the element matches expected using the lemoncheesecake.matching.require_that() function.

Parameters:

expected (Matcher) – a Matcher instance whose matches method will be called with the WebElement that has been found

require_no_element()

Check that the element is not present using the lemoncheesecake.matching.require_that() function.

assert_element(expected)

Check that the element matches expected using the lemoncheesecake.matching.assert_that() function.

Parameters:

expected (Matcher) – a Matcher instance whose matches method will be called with the WebElement that has been found

assert_no_element()

Check that the element is not present using the lemoncheesecake.matching.assert_that() function.

save_screenshot(description=None)

Take and save (as lemoncheesecake attachment) a screenshot of the underlying element.

Parameters:

description (Optional[str]) – description of the image attachment for that screenshot

select_by_value(value)

Select option by its value considering the underlying element is a SELECT element.

Parameters:

value – the value to be selected

select_by_index(index)

Select option by its index considering the underlying element is a SELECT element.

Parameters:

index – the index to be selected

select_by_visible_text(text)

Select option by its text considering the underlying element is a SELECT element.

Parameters:

text – the text to be selected

deselect_all()

Deselect all options considering the underlying element is a SELECT element.

deselect_by_value(value)

Deselect option by its value considering the underlying element is a SELECT element.

Parameters:

value – the value to be deselected

deselect_by_index(index)

Deselect option by its index considering the underlying element is a SELECT element.

Parameters:

index – the index to be deselected

deselect_by_visible_text(text)

Deselect option by its text considering the underlying element is a SELECT element.

Parameters:

text – the text to be deselected

Matchers

lemoncheesecake_selenium.is_in_page()

Test if WebElement is present in page.

NB: as the matcher is already called with a WebElement instance, the matcher will always be successful.

Returns:

Matcher instance

lemoncheesecake_selenium.has_text(expected)

Test if WebElement instance has text.

Parameters:

expected (Union[Matcher, str]) – expected text

Returns:

Matcher instance

lemoncheesecake_selenium.has_attribute(name, matcher=None)

Test if WebElement element has entity.

Parameters:
Returns:

Matcher instance

lemoncheesecake_selenium.has_property(name, matcher=None)
Parameters:

matcher (Optional[Union[str, Matcher]]) –

lemoncheesecake_selenium.is_displayed()

Test if WebElement element is displayed.

Returns:

Matcher instance

lemoncheesecake_selenium.is_enabled()

Test if WebElement element is enabled.

Returns:

Matcher instance

lemoncheesecake_selenium.is_selected()

Test if WebElement element is selected.

Returns:

Matcher instance

Utils

lemoncheesecake_selenium.save_screenshot(driver, description=None)

Take and save screenshot as a lemoncheesecake report attachment.

Parameters:

  • driver (WebDriver) – WebDriver instance

  • description (Optional[str]) – an optional screenshot description

lemoncheesecake_selenium.save_screenshot_on_exception(driver)

Context manager. Upon a WebDriverException exception, it saves a screenshot and re-raise the exception.

Parameters:

driver (WebDriver) – WebDriver instance