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 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(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_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_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_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 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 an 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 _get_log_path(self, log_file):
if is_noney(log_file):
return None
index = 1
while True:
formatted = _format_path(log_file, 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 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 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 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 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 = "Title should have been '%s' but was '%s'." % (
title, actual)
raise AssertionError(message)
self.info("Page title is '%s'." % title)
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 _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 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("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_contain(self, expected, message=None):
"""Verifies that the 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 is 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 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 = ("Location should have been '%s' but "
"was '%s'." % (url, actual))
raise AssertionError(message)
self.info("Current location is '%s'." % url)
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 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 resolve_keyword(name):
if is_noney(name) or is_string(name) and name.upper() == 'NOTHING':
return None
return name
def get_timeout(self, timeout=None):
if is_noney(timeout):
return self.ctx.timeout
return timestr_to_secs(timeout)
def log(self, msg, level='INFO', html=False):
if not is_noney(level):
logger.write(msg, level.upper(), html)