def add_cookie(self, name, value, path=None, domain=None, secure=None,
expiry=None):
"""Adds a cookie to your current session.
``name`` and ``value`` are required, ``path``, ``domain``, ``secure``
and ``expiry`` are optional. Expiry supports the same formats as
the [http://robotframework.org/robotframework/latest/libraries/DateTime.html|DateTime]
library or an epoch time stamp.
Example:
| `Add Cookie` | foo | bar | |
| `Add Cookie` | foo | bar | domain=example.com |
| `Add Cookie` | foo | bar | expiry=2027-09-28 16:21:35 | # Expiry as timestamp. |
| `Add Cookie` | foo | bar | expiry=1822137695 | # Expiry as epoch seconds. |
Prior to SeleniumLibrary 3.0 setting expiry did not work.
"""
new_cookie = {'name': name, 'value': value}
if not is_noney(path):
new_cookie['path'] = path
if not is_noney(domain):
new_cookie['domain'] = domain
# Secure must be True or False
if not is_noney(secure):
new_cookie['secure'] = is_truthy(secure)
if not is_noney(expiry):
new_cookie['expiry'] = self._expiry(expiry)
self.driver.add_cookie(new_cookie)
def add_cookie(self, name, value, path=None, domain=None, secure=None, expiry=None):
"""Adds a cookie to your current session.
``name`` and ``value`` are required, ``path``, ``domain``, ``secure``
and ``expiry`` are optional. Expiry supports the same formats as
the [http://robotframework.org/robotframework/latest/libraries/DateTime.html|DateTime]
library or an epoch timestamp.
Example:
| `Add Cookie` | foo | bar | |
| `Add Cookie` | foo | bar | domain=example.com |
| `Add Cookie` | foo | bar | expiry=2027-09-28 16:21:35 | # Expiry as timestamp. |
| `Add Cookie` | foo | bar | expiry=1822137695 | # Expiry as epoch seconds. |
Prior to SeleniumLibrary 3.0 setting expiry did not work.
"""
new_cookie = {"name": name, "value": value}
if not is_noney(path):
new_cookie["path"] = path
if not is_noney(domain):
new_cookie["domain"] = domain
# Secure must be True or False
if not is_noney(secure):
new_cookie["secure"] = is_truthy(secure)
if not is_noney(expiry):
new_cookie["expiry"] = self._expiry(expiry)
self.driver.add_cookie(new_cookie)
def add_cookie(self, name, value, path=None, domain=None, secure=None,
expiry=None):
"""Adds a cookie to your current session.
``name`` and ``value`` are required, ``path``, ``domain``, ``secure``
and ``expiry`` are optional. Expiry supports the same formats as
the [http://robotframework.org/robotframework/latest/libraries/DateTime.html|DateTime]
library or an epoch time stamp.
Prior SeleniumLibry 3.0 setting the expiry did not work.
Example:
| Add Cookie | foo | bar | | # Adds cookie with name foo and value bar |
| Add Cookie | foo | bar | domain=example.com | # Adds cookie with example.com domain defined |
| Add Cookie | foo | bar | expiry=2027-09-28 16:21:35 | # Adds cookie with expiry time defined |
| Add Cookie | foo | bar | expiry=1822137695 | # Adds cookie with expiry time defined as epoch |
"""
new_cookie = {'name': name, 'value': value}
if not is_noney(path):
new_cookie['path'] = path
if not is_noney(domain):
new_cookie['domain'] = domain
# Secure must be True or False
if not is_noney(secure):
new_cookie['secure'] = is_truthy(secure)
if not is_noney(expiry):
new_cookie['expiry'] = self._expiry(expiry)
self.browser.add_cookie(new_cookie)
def user_waits_until_parent_does_not_contain_element(parent_locator: str, child_locator: str,
timeout: int = None, error: str = None,
limit: int = None):
try:
sl.wait_until_page_contains_element(parent_locator, timeout=timeout, error=error,
limit=limit)
def parent_does_not_contain_matching_element() -> bool:
parent_el = sl.find_element(parent_locator)
return element_finder.find(child_locator, required=False, parent=parent_el) is None
if is_noney(limit):
return waiting._wait_until(
parent_does_not_contain_matching_element,
"Parent '%s' should not have contained '%s' in <TIMEOUT>." % (
parent_locator, child_locator),
timeout, error
)
limit = int(limit)
def parent_does_not_contain_matching_elements() -> bool:
parent_el = sl.find_element(parent_locator)
return len(sl.find_elements(child_locator, parent=parent_el)) != limit
waiting._wait_until(
parent_does_not_contain_matching_elements,
"Parent '%s' should not have contained %s '%s' element(s) within <TIMEOUT>." % (
parent_locator, limit, child_locator),
timeout, error
)
except Exception as err:
raise_assertion_error(err)
def _wait_until(self, condition, error, timeout=None, custom_error=None):
timeout = self.get_timeout(timeout)
if is_noney(custom_error):
error = error.replace('<TIMEOUT>', secs_to_timestr(timeout))
else:
error = custom_error
self._wait_until_worker(condition, timeout, error)
def element_should_contain(self, locator, expected, message=None, ignore_case=False):
"""Verifies that element ``locator`` contains text ``expected``.
See the `Locating elements` section for details about the locator
syntax.
The ``message`` argument can be used to override the default error
message.
The ``ignore_case`` argument can be set to True to compare case
insensitive, default is False. New in SeleniumLibrary 3.1.
``ignore_case`` argument new in SeleniumLibrary 3.1.
Use `Element Text Should Be` if you want to match the exact text,
not a substring.
"""
actual = actual_before = self.find_element(locator).text
expected_before = expected
if is_truthy(ignore_case):
actual = actual.lower()
expected = expected.lower()
if expected not in actual:
if is_noney(message):
message = "Element '%s' should have contained text '%s' but "\
"its text was '%s'." % (locator, expected_before, actual_before)
raise AssertionError(message)
self.info("Element '%s' contains text '%s'." % (locator, expected_before))
def element_text_should_be(
self, locator, expected, message=None, ignore_case=False
):
"""Verifies that element ``locator`` contains exact the text ``expected``.
See the `Locating elements` section for details about the locator
syntax.
The ``message`` argument can be used to override the default error
message.
The ``ignore_case`` argument can be set to True to compare case
insensitive, default is False.
``ignore_case`` argument is new in SeleniumLibrary 3.1.
Use `Element Should Contain` if a substring match is desired.
"""
self.info(
"Verifying element '%s' contains exact text '%s'." % (locator, expected)
)
text = before_text = self.find_element(locator).text
if is_truthy(ignore_case):
text = text.lower()
expected = expected.lower()
if text != expected:
if is_noney(message):
message = (
"The text of element '%s' should have been '%s' "
"but it was '%s'." % (locator, expected, before_text)
)
raise AssertionError(message)
def element_text_should_not_be(self, locator, not_expected, message=None, ignore_case=False):
"""Verifies that element ``locator`` does not contain exact text ``not_expected``.
See the `Locating elements` section for details about the locator
syntax.
The ``message`` argument can be used to override the default error
message.
The ``ignore_case`` argument can be set to True to compare case
insensitive, default is False.
New in SeleniumLibrary 3.1.1
"""
self.info("Verifying element '%s' does not contains exact text '%s'."
% (locator, not_expected))
text = self.find_element(locator).text
before_not_expected = not_expected
if is_truthy(ignore_case):
text = text.lower()
not_expected = not_expected.lower()
if text == not_expected:
if is_noney(message):
message = ("The text of element '%s' was not supposed to be '%s'."
% (locator, before_not_expected))
raise AssertionError(message)
def set_screenshot_directory(self, path, persist='DEPRECATED'):
"""Sets the directory for captured screenshots.
``path`` argument specifies the absolute path to a directory where
the screenshots should be written to. If the directory does not
exist, it will be created. The directory can also be set when
`importing` the library. If it is not configured anywhere,
screenshots are saved to the same directory where Robot Framework's
log file is written.
``persist`` argument is deprecated and has no effect.
The previous value is returned and can be used to restore
the original value later if needed.
Deprecating ``persist`` and returning the previous value are new
in SeleniumLibrary 3.0.
"""
if is_noney(path):
path = None
else:
path = os.path.abspath(path)
self._create_directory(path)
if persist != 'DEPRECATED':
self.warn("'persist' argument to 'Set Screenshot Directory' "
"keyword is deprecated and has no effect.")
previous = self.ctx.screenshot_root_directory
self.ctx.screenshot_root_directory = path
return previous
def element_attribute_value_should_be(
self, locator, attribute, expected, message=None
):
"""Verifies element identified by ``locator`` contains expected attribute value.
See the `Locating elements` section for details about the locator
syntax.
Example:
`Element Attribute Value Should Be` | css:img | href | value
New in SeleniumLibrary 3.2.
"""
current_expected = self.find_element(locator).get_attribute(attribute)
if current_expected != expected:
if is_noney(message):
message = (
"Element '%s' attribute should have value '%s' but "
"its value was '%s'." % (locator, expected, current_expected)
)
raise AssertionError(message)
self.info(
"Element '%s' attribute '%s' contains value '%s'."
% (locator, attribute, expected)
)
def user_waits_until_parent_contains_element(parent_locator: object, child_locator: str,
timeout: int = None, error: str = None,
limit: int = None):
try:
child_locator = _normalise_child_locator(child_locator)
def parent_contains_matching_element() -> bool:
parent_el = _get_parent_webelement_from_locator(parent_locator, timeout, error)
return element_finder.find(child_locator, required=False, parent=parent_el) is not None
if is_noney(limit):
return waiting._wait_until(
parent_contains_matching_element,
"Parent '%s' did not contain '%s' in <TIMEOUT>." % (parent_locator, child_locator),
timeout, error
)
limit = int(limit)
def parent_contains_matching_elements() -> bool:
parent_el = _get_parent_webelement_from_locator(parent_locator, timeout, error)
return len(sl.find_elements(child_locator, parent=parent_el)) == limit
waiting._wait_until(
parent_contains_matching_elements,
"Parent '%s' did not contain %s '%s' element(s) within <TIMEOUT>." % (
parent_locator, limit, child_locator),
timeout, error
)
except Exception as err:
warning(f"Error whilst executing utilities.py user_waits_until_parent_contains_element() "
f"with parent {parent_locator} and child locator {child_locator} - {err}")
raise_assertion_error(err)
def element_should_contain(
self, locator, expected, message=None, ignore_case=False
):
"""Verifies that element ``locator`` contains text ``expected``.
See the `Locating elements` section for details about the locator
syntax.
The ``message`` argument can be used to override the default error
message.
The ``ignore_case`` argument can be set to True to compare case
insensitive, default is False. New in SeleniumLibrary 3.1.
``ignore_case`` argument is new in SeleniumLibrary 3.1.
Use `Element Text Should Be` if you want to match the exact text,
not a substring.
"""
actual = actual_before = self.find_element(locator).text
expected_before = expected
if is_truthy(ignore_case):
actual = actual.lower()
expected = expected.lower()
if expected not in actual:
if is_noney(message):
message = (
"Element '%s' should have contained text '%s' but "
"its text was '%s'." % (locator, expected_before, actual_before)
)
raise AssertionError(message)
self.info("Element '%s' contains text '%s'." % (locator, expected_before))
def element_should_not_contain(
self, locator, expected, message=None, ignore_case=False
):
"""Verifies that element ``locator`` does not contain text ``expected``.
See the `Locating elements` section for details about the locator
syntax.
The ``message`` argument can be used to override the default error
message.
The ``ignore_case`` argument can be set to True to compare case
insensitive, default is False.
``ignore_case`` argument new in SeleniumLibrary 3.1.
"""
actual = self.find_element(locator).text
expected_before = expected
if is_truthy(ignore_case):
actual = actual.lower()
expected = expected.lower()
if expected in actual:
if is_noney(message):
message = "Element '%s' should not contain text '%s' but " "it did." % (
locator,
expected_before,
)
raise AssertionError(message)
self.info(
"Element '%s' does not contain text '%s'." % (locator, expected_before)
)
def wait_until_page_does_not_contain_element(self,
locator,
timeout=None,
error=None,
limit=None):
"""Waits until the element ``locator`` disappears from the current page.
Fails if ``timeout`` expires before the element disappears. See
the `Timeouts` section for more information about using timeouts and
their default value and the `Locating elements` section for details
about the locator syntax.
``error`` can be used to override the default error message.
The ``limit`` argument can used to define how many elements the
page should not contain. When ``limit`` is `None` (default) page can`t
contain any elements. When limit is a number, page must not
contain same number of elements.
``limit`` is new in SeleniumLibrary 4.4
"""
if is_noney(limit):
return self._wait_until(
lambda: self.find_element(locator, required=False) is None,
"Element '%s' did not disappear in <TIMEOUT>." % locator,
timeout, error)
limit = int(limit)
self._wait_until(
lambda: len(self.find_elements(locator)) != limit,
'Page should have not contained "%s" %s element(s) within <TIMEOUT>.'
% (limit, locator), timeout, error)
def element_text_should_not_be(
self, locator, not_expected, message=None, ignore_case=False
):
"""Verifies that element ``locator`` does not contain exact the text ``not_expected``.
See the `Locating elements` section for details about the locator
syntax.
The ``message`` argument can be used to override the default error
message.
The ``ignore_case`` argument can be set to True to compare case
insensitive, default is False.
New in SeleniumLibrary 3.1.1
"""
self.info(
"Verifying element '%s' does not contain exact text '%s'."
% (locator, not_expected)
)
text = self.find_element(locator).text
before_not_expected = not_expected
if is_truthy(ignore_case):
text = text.lower()
not_expected = not_expected.lower()
if text == not_expected:
if is_noney(message):
message = "The text of element '%s' was not supposed to be '%s'." % (
locator,
before_not_expected,
)
raise AssertionError(message)
def set_screenshot_directory(self, path):
"""Sets the directory for captured screenshots.
``path`` argument specifies the absolute path to a directory where
the screenshots should be written to. If the directory does not
exist, it will be created. The directory can also be set when
`importing` the library. If it is not configured anywhere,
screenshots are saved to the same directory where Robot Framework's
log file is written.
If ``path`` equals to EMBED (case insensitive) and
`Capture Page Screenshot` or `capture Element Screenshot` keywords
filename argument is not changed from the default value, then
the page or element screenshot is embedded as Base64 image to
the log.html.
The previous value is returned and can be used to restore
the original value later if needed.
Returning the previous value is new in SeleniumLibrary 3.0.
The persist argument was removed in SeleniumLibrary 3.2 and
EMBED is new in SeleniumLibrary 4.2.
"""
if is_noney(path):
path = None
elif path.upper() == EMBED:
path = EMBED
else:
path = os.path.abspath(path)
self._create_directory(path)
previous = self._screenshot_root_directory
self._screenshot_root_directory = path
return previous
def element_text_should_be(self, locator, expected, message=None, ignore_case=False):
"""Verifies that element ``locator`` contains exact text ``expected``.
See the `Locating elements` section for details about the locator
syntax.
The ``message`` argument can be used to override the default error
message.
The ``ignore_case`` argument can be set to True to compare case
insensitive, default is False.
``ignore_case`` argument new in SeleniumLibrary 3.1.
Use `Element Should Contain` if a substring match is desired.
"""
self.info("Verifying element '%s' contains exact text '%s'."
% (locator, expected))
text = before_text = self.find_element(locator).text
if is_truthy(ignore_case):
text = text.lower()
expected = expected.lower()
if text != expected:
if is_noney(message):
message = ("The text of element '%s' should have been '%s' "
"but it was '%s'."
% (locator, expected, before_text))
raise AssertionError(message)
def _wait_until(self, condition, error, timeout=None, custom_error=None):
timeout = self.get_timeout(timeout)
if is_noney(custom_error):
error = error.replace('<TIMEOUT>', secs_to_timestr(timeout))
else:
error = custom_error
self._wait_until_worker(condition, timeout, error)
def element_should_not_contain(self, locator, expected, message=None, ignore_case=False):
"""Verifies that element ``locator`` does not contains text ``expected``.
See the `Locating elements` section for details about the locator
syntax.
The ``message`` argument can be used to override the default error
message.
The ``ignore_case`` argument can be set to True to compare case
insensitive, default is False.
``ignore_case`` argument new in SeleniumLibrary 3.1.
"""
actual = self.find_element(locator).text
expected_before = expected
if is_truthy(ignore_case):
actual = actual.lower()
expected = expected.lower()
if expected in actual:
if is_noney(message):
message = "Element '%s' should not contain text '%s' but " \
"it did." % (locator, expected_before)
raise AssertionError(message)
self.info("Element '%s' does not contain text '%s'."
% (locator, expected_before))
def page_should_contain_element(self,
locator,
message=None,
loglevel='INFO',
limit=None):
"""Verifies that element ``locator`` is found on the current page.
See the `Locating elements` section for details about the locator
syntax.
The ``message`` argument can be used to override the default error
message.
The ``limit`` argument can used to define how many elements the
page should contain. When ``limit`` is ``None`` (default) page can
contain one or more elements. When limit is a number, page must
contain same number of elements.
See `Page Should Contain` for explanation about the ``loglevel``
argument.
Examples assumes that locator matches to two elements.
| `Page Should Contain Element` | div_name | limit=1 | # Keyword fails. |
| `Page Should Contain Element` | div_name | limit=2 | # Keyword passes. |
| `Page Should Contain Element` | div_name | limit=none | # None is considered one or more. |
| `Page Should Contain Element` | div_name | | # Same as above. |
The ``limit`` argument is new in SeleniumLibrary 3.0.
"""
if is_noney(limit):
return self.assert_page_contains(locator,
message=message,
loglevel=loglevel)
limit = int(limit)
count = len(self.find_elements(locator))
if count == limit:
self.info('Current page contains {} element(s).'.format(count))
else:
if is_noney(message):
message = ('Page should have contained "{}" element(s), '
'but it did contain "{}" element(s).'.format(
limit, count))
self.ctx.log_source(loglevel)
raise AssertionError(message)
def assert_page_not_contains(self, locator, tag=None, message=None,
loglevel='TRACE'):
if self.find_element(locator, tag, required=False):
self.log_source(loglevel)
if is_noney(message):
message = ("Page should not have contained %s '%s'."
% (tag or 'element', locator))
raise AssertionError(message)
logger.info("Current page does not contain %s '%s'."
% (tag or 'element', locator))
def assert_page_not_contains(self, locator, tag=None, message=None,
loglevel='TRACE'):
if self.find_element(locator, tag, required=False):
self.log_source(loglevel)
if is_noney(message):
message = ("Page should not have contained %s '%s'."
% (tag or 'element', locator))
raise AssertionError(message)
logger.info("Current page does not contain %s '%s'."
% (tag or 'element', locator))
def _get_log_path(self, log_file):
if is_noney(log_file):
return None
index = 1
while True:
formatted = log_file.format(index=index)
path = os.path.join(self.log_dir, formatted)
# filename didn't contain {index} or unique path was found
if formatted == log_file or not os.path.exists(path):
return path
index += 1
def submit_form(self, locator=None):
"""Submits a form identified by `locator`.
If `locator` is empty, first form in the page will be submitted.
Key attributes for forms are `id` and `name`. See `introduction` for
details about locating elements.
"""
self.info("Submitting form '%s'." % locator)
if is_noney(locator):
locator = 'tag:form'
element = self.find_element(locator, tag='form')
element.submit()
def page_should_contain_element(self, locator, message=None,
loglevel='TRACE', limit=None):
"""Verifies that element ``locator`` is found on the current page.
See the `Locating elements` section for details about the locator
syntax.
The ``message`` argument can be used to override the default error
message.
The ``limit`` argument can used to define how many elements the
page should contain. When ``limit`` is ``None`` (default) page can
contain one or more elements. When limit is a number, page must
contain same number of elements.
See `Page Should Contain` for explanation about the ``loglevel``
argument.
Examples assumes that locator matches to two elements.
| `Page Should Contain Element` | div_name | limit=1 | # Keyword fails. |
| `Page Should Contain Element` | div_name | limit=2 | # Keyword passes. |
| `Page Should Contain Element` | div_name | limit=none | # None is considered one or more. |
| `Page Should Contain Element` | div_name | | # Same as above. |
The ``limit`` argument is new in SeleniumLibrary 3.0.
"""
if is_noney(limit):
return self.assert_page_contains(locator, message=message,
loglevel=loglevel)
limit = int(limit)
count = len(self.find_elements(locator))
if count == limit:
self.info('Current page contains {} element(s).'.format(count))
else:
if is_noney(message):
message = ('Page should have contained "{}" element(s), '
'but it did contain "{}" element(s).'
.format(limit, count))
self.ctx.log_source(loglevel)
raise AssertionError(message)
def assert_page_not_contains(self,
locator,
tag=None,
message=None,
loglevel="TRACE"):
tag_message = tag or "element"
if self.find_element(locator, tag, required=False):
self.log_source(loglevel)
if is_noney(message):
message = f"Page should not have contained {tag_message} '{locator}'."
raise AssertionError(message)
logger.info(
f"Current page does not contain {tag_message} '{locator}'.")
def submit_form(self, locator=None):
"""Submits a form identified by ``locator``.
If ``locator`` is not given, first form on the page is submitted.
See the `Locating elements` section for details about the locator
syntax.
"""
self.info("Submitting form '%s'." % locator)
if is_noney(locator):
locator = 'tag:form'
element = self.find_element(locator, tag='form')
element.submit()
def submit_form(self, locator: Optional[str] = None):
"""Submits a form identified by ``locator``.
If ``locator`` is not given, first form on the page is submitted.
See the `Locating elements` section for details about the locator
syntax.
"""
self.info(f"Submitting form '{locator}'.")
if is_noney(locator):
locator = "tag:form"
element = self.find_element(locator, tag="form")
element.submit()
def submit_form(self, locator=None):
"""Submits a form identified by ``locator``.
If ``locator`` is not given, first form on the page is submitted.
See the `Locating elements` section for details about the locator
syntax.
"""
self.info("Submitting form '%s'." % locator)
if is_noney(locator):
locator = 'tag:form'
element = self.find_element(locator, tag='form')
element.submit()
def title_should_be(self, title, message=None):
"""Verifies that the current page title equals ``title``.
The ``message`` argument can be used to override the default error
message.
``message`` argument is new in SeleniumLibrary 3.1.
"""
actual = self.get_title()
if actual != title:
if is_noney(message):
message = f"Title should have been '{title}' but was '{actual}'."
raise AssertionError(message)
self.info(f"Page title is '{title}'.")
def title_should_be(self, title, message=None):
"""Verifies that current page title equals ``title``.
The ``message`` argument can be used to override the default error
message.
``message`` argument is new in SeleniumLibrary 3.1.
"""
actual = self.get_title()
if actual != title:
if is_noney(message):
message = "Title should have been '%s' but was '%s'." % (title, actual)
raise AssertionError(message)
self.info("Page title is '%s'." % title)
def _get_index(self, alias_or_index):
alias_or_index = None if is_noney(alias_or_index) else alias_or_index
try:
return self.resolve_alias_or_index(alias_or_index)
except AttributeError:
pass
except ValueError:
return None
# TODO: This try/except block can be removed when minimum
# required Robot Framework version is 3.3 or greater.
try:
return self._resolve_alias_or_index(alias_or_index)
except ValueError:
return None
def _get_index(self, alias_or_index):
alias_or_index = None if is_noney(alias_or_index) else alias_or_index
try:
return self.resolve_alias_or_index(alias_or_index)
except AttributeError:
pass
except ValueError:
return None
# TODO: This try/except block can be removed when minimum
# required Robot Framework version is 3.3 or greater.
try:
return self._resolve_alias_or_index(alias_or_index)
except ValueError:
return None
def textarea_value_should_be(self, locator, expected, message=None):
"""Verifies the value in text area identified by `locator` is exactly `expected`.
`message` can be used to override default error message.
Key attributes for text areas are `id` and `name`. See `introduction`
for details about locating elements.
"""
actual = self._get_value(locator, 'text area')
if expected != actual:
if is_noney(message):
message = "Text area '%s' should have had text '%s' " \
"but it had '%s'." % (locator, expected, actual)
raise AssertionError(message)
self.info("Content of text area '%s' is '%s'." % (locator, expected))
def textfield_should_contain(self, locator, expected, message=None):
"""Verifies text field identified by `locator` contains text `expected`.
`message` can be used to override default error message.
Key attributes for text fields are `id` and `name`. See `introduction`
for details about locating elements.
"""
actual = self._get_value(locator, 'text field')
if expected not in actual:
if is_noney(message):
message = "Text field '%s' should have contained text '%s' "\
"but it contained '%s'." % (locator, expected, actual)
raise AssertionError(message)
self.info("Text field '%s' contains text '%s'." % (locator, expected))
def element_should_not_be_visible(self, locator, message=None):
"""Verifies that the element identified by ``locator`` is NOT visible.
Passes if the element does not exists. See `Element Should Be Visible`
for more information about visibility and supported arguments.
"""
element = self.find_element(locator, required=False)
if element is None:
self.info(f"Element '{locator}' did not exist.")
elif not element.is_displayed():
self.info(f"Element '{locator}' exists but is not displayed.")
else:
if is_noney(message):
message = f"The element '{locator}' should not be visible, but it is."
raise AssertionError(message)
def textarea_value_should_be(self, locator, expected, message=None):
"""Verifies text area ``locator`` has exactly text ``expected``.
``message`` can be used to override default error message.
See the `Locating elements` section for details about the locator
syntax.
"""
actual = self._get_value(locator, 'text area')
if expected != actual:
if is_noney(message):
message = "Text area '%s' should have had text '%s' " \
"but it had '%s'." % (locator, expected, actual)
raise AssertionError(message)
self.info("Content of text area '%s' is '%s'." % (locator, expected))
def textfield_should_contain(self, locator, expected, message=None):
"""Verifies text field ``locator`` contains text ``expected``.
``message`` can be used to override the default error message.
See the `Locating elements` section for details about the locator
syntax.
"""
actual = self._get_value(locator, 'text field')
if expected not in actual:
if is_noney(message):
message = "Text field '%s' should have contained text '%s' "\
"but it contained '%s'." % (locator, expected, actual)
raise AssertionError(message)
self.info("Text field '%s' contains text '%s'." % (locator, expected))
def assert_page_contains(self,
locator,
tag=None,
message=None,
loglevel="TRACE"):
if not self.find_element(locator, tag, required=False):
self.log_source(loglevel)
if is_noney(message):
message = "Page should have contained %s '%s' but did not." % (
tag or "element",
locator,
)
raise AssertionError(message)
logger.info("Current page contains %s '%s'." %
(tag or "element", locator))
def textarea_value_should_be(self, locator, expected, message=None):
"""Verifies text area ``locator`` has exactly text ``expected``.
``message`` can be used to override default error message.
See the `Locating elements` section for details about the locator
syntax.
"""
actual = self._get_value(locator, 'text area')
if expected != actual:
if is_noney(message):
message = "Text area '%s' should have had text '%s' " \
"but it had '%s'." % (locator, expected, actual)
raise AssertionError(message)
self.info("Content of text area '%s' is '%s'." % (locator, expected))
def textfield_should_contain(self, locator, expected, message=None):
"""Verifies text field ``locator`` contains text ``expected``.
``message`` can be used to override the default error message.
See the `Locating elements` section for details about the locator
syntax.
"""
actual = self._get_value(locator, 'text field')
if expected not in actual:
if is_noney(message):
message = "Text field '%s' should have contained text '%s' "\
"but it contained '%s'." % (locator, expected, actual)
raise AssertionError(message)
self.info("Text field '%s' contains text '%s'." % (locator, expected))
def element_should_not_be_visible(self, locator, message=None):
"""Verifies that the element identified by ``locator`` is NOT visible.
Passes if element does not exists. See `Element Should Be Visible`
for more information about visibility and supported arguments.
"""
element = self.find_element(locator, required=False)
if element is None:
self.info("Element '%s' did not exist." % locator)
elif not element.is_displayed():
self.info("Element '%s' exists but is not displayed." % locator)
else:
if is_noney(message):
message = ("The element '%s' should not be visible, "
"but it is." % locator)
raise AssertionError(message)
def assert_page_contains(
self,
locator: str,
tag: Optional[str] = None,
message: Optional[str] = None,
loglevel: str = "TRACE",
):
tag_message = tag or "element"
if not self.find_element(locator, tag, required=False):
self.log_source(loglevel)
if is_noney(message):
message = (
f"Page should have contained {tag_message} '{locator}' but did not."
)
raise AssertionError(message)
logger.info(f"Current page contains {tag_message} '{locator}'.")
def location_should_be(self, url, message=None):
"""Verifies that the current URL is exactly ``url``.
The ``url`` argument contains the exact url that should exist in browser.
The ``message`` argument can be used to override the default error
message.
``message`` argument is new in SeleniumLibrary 3.2.0.
"""
actual = self.get_location()
if actual != url:
if is_noney(message):
message = f"Location should have been '{url}' but " f"was '{actual}'."
raise AssertionError(message)
self.info(f"Current location is '{url}'.")
def location_should_contain(self, expected, message=None):
"""Verifies that current URL contains ``expected``.
The ``expected`` argument contains the expected value in url.
The ``message`` argument can be used to override the default error
message.
``message`` argument new in SeleniumLibrary 3.2.0.
"""
actual = self.get_location()
if expected not in actual:
if is_noney(message):
message = ("Location should have contained '%s' but "
"it was '%s'." % (expected, actual))
raise AssertionError(message)
self.info("Current location contains '%s'." % expected)
def location_should_be(self, url, message=None):
"""Verifies that current URL is exactly ``url``.
The ``url`` argument contains the exact url that should exist in browser.
The ``message`` argument can be used to override the default error
message.
``message`` argument new in SeleniumLibrary 3.2.0.
"""
actual = self.get_location()
if actual != url:
if is_noney(message):
message = ("Location should have been '%s' but "
"was '%s'." % (url, actual))
raise AssertionError(message)
self.info("Current location is '%s'." % url)
def element_attribute_value_should_be(self, locator, attribute, expected, message=None):
"""Verifies element identified by ``locator`` contains expected attribute value.
See the `Locating elements` section for details about the locator
syntax.
Example:
`Element Attribute Value Should Be` | css:img | href | value
New in SeleniumLibrary 3.2.
"""
current_expected = self.find_element(locator).get_attribute(attribute)
if current_expected != expected:
if is_noney(message):
message = ("Element '%s' attribute should have value '%s' but "
"its value was '%s'." % (locator, expected, current_expected))
raise AssertionError(message)
self.info("Element '%s' attribute '%s' contains value '%s'." % (locator, attribute, expected))
def element_should_be_visible(self, locator, message=None):
"""Verifies that the element identified by ``locator`` is visible.
Herein, visible means that the element is logically visible, not
optically visible in the current browser viewport. For example,
an element that carries ``display:none`` is not logically visible,
so using this keyword on that element would fail.
See the `Locating elements` section for details about the locator
syntax.
The ``message`` argument can be used to override the default error
message.
"""
if not self.find_element(locator).is_displayed():
if is_noney(message):
message = ("The element '%s' should be visible, but it "
"is not." % locator)
raise AssertionError(message)
self.info("Element '%s' is displayed." % locator)
def set_screenshot_directory(self, path):
"""Sets the directory for captured screenshots.
``path`` argument specifies the absolute path to a directory where
the screenshots should be written to. If the directory does not
exist, it will be created. The directory can also be set when
`importing` the library. If it is not configured anywhere,
screenshots are saved to the same directory where Robot Framework's
log file is written.
The previous value is returned and can be used to restore
the original value later if needed.
Returning the previous value is new in SeleniumLibrary 3.0.
The persist argument was removed in SeleniumLibrary 3.2.
"""
if is_noney(path):
path = None
else:
path = os.path.abspath(path)
self._create_directory(path)
previous = self.ctx.screenshot_root_directory
self.ctx.screenshot_root_directory = path
return previous
def resolve_keyword(name):
if is_noney(name) or is_string(name) and name.upper() == 'NOTHING':
return None
return name
def log(self, msg, level='INFO', html=False):
if not is_noney(level):
logger.write(msg, level.upper(), html)
def test_is_noney(self):
for item in [None, 'None', 'NONE', 'none']:
self.assertTrue(is_noney(item) is True)
for item in self.truthy + [False, 0, 'False', '', [], {}, ()]:
self.assertTrue(is_noney(item) is False)
def get_timeout(self, timeout=None):
if is_noney(timeout):
return self.ctx.timeout
return timestr_to_secs(timeout)
