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 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 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.
``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.
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 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_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 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 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='INFO'):
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 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 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 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 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 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 location_should_contain(self, expected, message=None):
"""Verifies that current URL contains ``expected``.
The ``url`` 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 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 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 log(self, msg, level='INFO', html=False):
if not is_noney(level):
logger.write(msg, level.upper(), html)
def get_timeout(self, timeout=None):
if is_noney(timeout):
return self.ctx.timeout
return timestr_to_secs(timeout)
def resolve_keyword(name):
if is_noney(name) or is_string(name) and name.upper() == 'NOTHING':
return None
return name
