element.py

Go to the documentation of this file.

# Copyright 2008-2011 Nokia Networks
# Copyright 2011-2016 Ryan Tomac, Ed Manlove and contributors
# Copyright 2016-     Robot Framework Foundation
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
from collections import namedtuple
 
from robot.utils import plural_or_not
from selenium.webdriver.common.action_chains import ActionChains
from selenium.webdriver.common.keys import Keys
 
 
from SeleniumLibrary.base import LibraryComponent, keyword
from SeleniumLibrary.utils import (is_falsy, is_noney, is_truthy,
                                   plural_or_not as s)
from SeleniumLibrary.errors import ElementNotFound
 
 
class ElementKeywords(LibraryComponent):
 
    @keyword(name='Get WebElement')
    
    def get_webelement(self, locator):
        return self.find_elementfind_element(locator)
 
    @keyword(name='Get WebElements')
    
    def get_webelements(self, locator):
        return self.find_elementsfind_elements(locator)
 
    @keyword
    
    def element_should_contain(self, locator, expected, message=None, ignore_case=False):
        actual = actual_before = self.find_elementfind_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.infoinfo("Element '%s' contains text '%s'." % (locator, expected_before))
 
    @keyword
    
    def element_should_not_contain(self, locator, expected, message=None, ignore_case=False):
        actual = self.find_elementfind_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.infoinfo("Element '%s' does not contain text '%s'."
                  % (locator, expected_before))
 
    @keyword
    
    def page_should_contain(self, text, loglevel='TRACE'):
        if not self._page_contains_page_contains(text):
            self.ctxctx.log_source(loglevel)
            raise AssertionError("Page should have contained text '%s' "
                                 "but did not." % text)
        self.infoinfo("Current page contains text '%s'." % text)
 
    @keyword
    
    def page_should_contain_element(self, locator, message=None,
                                    loglevel='TRACE', limit=None):
        if is_noney(limit):
            return self.assert_page_containsassert_page_contains(locator, message=message,
                                             loglevel=loglevel)
        limit = int(limit)
        count = len(self.find_elementsfind_elements(locator))
        if count == limit:
            self.infoinfo('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.ctxctx.log_source(loglevel)
            raise AssertionError(message)
 
    @keyword
    
    def locator_should_match_x_times(self, locator, x, message=None, loglevel='TRACE'):
        count = len(self.find_elementsfind_elements(locator))
        x = int(x)
        if count != x:
            if is_falsy(message):
                message = ("Locator '%s' should have matched %s time%s but "
                           "matched %s time%s."
                           % (locator, x, s(x), count, s(count)))
            self.ctxctx.log_source(loglevel)
            raise AssertionError(message)
        self.infoinfo("Current page contains %s elements matching '%s'."
                  % (count, locator))
 
    @keyword
    
    def page_should_not_contain(self, text, loglevel='TRACE'):
        if self._page_contains_page_contains(text):
            self.ctxctx.log_source(loglevel)
            raise AssertionError("Page should not have contained text '%s'."
                                 % text)
        self.infoinfo("Current page does not contain text '%s'." % text)
 
    @keyword
    
    def page_should_not_contain_element(self, locator, message=None, loglevel='TRACE'):
        self.assert_page_not_containsassert_page_not_contains(locator, message=message,
                                      loglevel=loglevel)
 
    @keyword
    
    def assign_id_to_element(self, locator, id):
        self.infoinfo("Assigning temporary id '%s' to element '%s'." % (id, locator))
        element = self.find_elementfind_element(locator)
        self.driverdriverdriver.execute_script("arguments[0].id = '%s';" % id, element)
 
    @keyword
    
    def element_should_be_disabled(self, locator):
        if self.is_element_enabledis_element_enabled(locator):
            raise AssertionError("Element '%s' is enabled." % locator)
 
    @keyword
    
    def element_should_be_enabled(self, locator):
        if not self.is_element_enabledis_element_enabled(locator):
            raise AssertionError("Element '%s' is disabled." % locator)
 
    @keyword
    
    def element_should_be_focused(self, locator):
        element = self.find_elementfind_element(locator)
        focused = self.driverdriverdriver.switch_to.active_element
        # Selenium 3.6.0 with Firefox return dict wich contains the selenium WebElement
        if isinstance(focused, dict):
            focused = focused['value']
        if element != focused:
            raise AssertionError("Element '%s' does not have focus." % locator)
 
    @keyword
    
    def element_should_be_visible(self, locator, message=None):
        if not self.find_elementfind_element(locator).is_displayed():
            if is_noney(message):
                message = ("The element '%s' should be visible, but it "
                           "is not." % locator)
            raise AssertionError(message)
        self.infoinfo("Element '%s' is displayed." % locator)
 
    @keyword
    
    def element_should_not_be_visible(self, locator, message=None):
        element = self.find_elementfind_element(locator, required=False)
        if element is None:
            self.infoinfo("Element '%s' did not exist." % locator)
        elif not element.is_displayed():
            self.infoinfo("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)
 
    @keyword
    
    def element_text_should_be(self, locator, expected, message=None, ignore_case=False):
        self.infoinfo("Verifying element '%s' contains exact text '%s'."
                  % (locator, expected))
        text = before_text = self.find_elementfind_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)
 
    @keyword
    
    def element_text_should_not_be(self, locator, not_expected, message=None, ignore_case=False):
        self.infoinfo("Verifying element '%s' does not contains exact text '%s'."
                  % (locator, not_expected))
        text = self.find_elementfind_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)
 
    @keyword
    
    def get_element_attribute(self, locator, attribute):
        return self.find_elementfind_element(locator).get_attribute(attribute)
 
    @keyword
    
    def element_attribute_value_should_be(self, locator, attribute, expected, message=None):
        current_expected = self.find_elementfind_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.infoinfo("Element '%s' attribute '%s' contains value '%s'." % (locator, attribute, expected))
 
    @keyword
    
    def get_horizontal_position(self, locator):
        return self.find_elementfind_element(locator).location['x']
 
    @keyword
    
    def get_element_size(self, locator):
        element = self.find_elementfind_element(locator)
        return element.size['width'], element.size['height']
 
    @keyword
    
    def cover_element(self, locator):
        elements = self.find_elementsfind_elements(locator)
        if not elements:
            raise ElementNotFound("No element with locator '%s' found."
                                  % locator)
        for element in elements:
            script = """
old_element = arguments[0];
let newDiv = document.createElement('div');
newDiv.setAttribute("name", "covered");
newDiv.style.backgroundColor = 'blue';
newDiv.style.zIndex = '999';
newDiv.style.top = old_element.offsetTop + 'px';
newDiv.style.left = old_element.offsetLeft + 'px';
newDiv.style.height = old_element.offsetHeight + 'px';
newDiv.style.width = old_element.offsetWidth + 'px';
old_element.parentNode.insertBefore(newDiv, old_element);
old_element.remove();
newDiv.parentNode.style.overflow = 'hidden';
        """
            self.driverdriverdriver.execute_script(script, element)
 
    @keyword
    
    def get_value(self, locator):
        return self.get_element_attributeget_element_attribute(locator, 'value')
 
    @keyword
    
    def get_text(self, locator):
        return self.find_elementfind_element(locator).text
 
    @keyword
    
    def clear_element_text(self, locator):
        self.find_elementfind_element(locator).clear()
 
    @keyword
    
    def get_vertical_position(self, locator):
        return self.find_elementfind_element(locator).location['y']
 
    @keyword
    
    def click_button(self, locator, modifier=False):
        if is_falsy(modifier):
            self.infoinfo("Clicking button '%s'." % locator)
            element = self.find_elementfind_element(locator, tag='input', required=False)
            if not element:
                element = self.find_elementfind_element(locator, tag='button')
            element.click()
        else:
            self._click_with_modifier_click_with_modifier(locator, ['button', 'input'], modifier)
 
    @keyword
    
    def click_image(self, locator, modifier=False):
        if is_falsy(modifier):
            self.infoinfo("Clicking image '%s'." % locator)
            element = self.find_elementfind_element(locator, tag='image', required=False)
            if not element:
                # A form may have an image as it's submit trigger.
                element = self.find_elementfind_element(locator, tag='input')
            element.click()
        else:
            self._click_with_modifier_click_with_modifier(locator, ['image', 'input'], modifier)
 
    @keyword
    
    def click_link(self, locator, modifier=False):
        if is_falsy(modifier):
            self.infoinfo("Clicking link '%s'." % locator)
            self.find_elementfind_element(locator, tag='link').click()
        else:
            self._click_with_modifier_click_with_modifier(locator, ['link', 'link'], modifier)
 
    @keyword
    
    def click_element(self, locator, modifier=False):
        if is_falsy(modifier):
            self.infoinfo("Clicking element '%s'." % locator)
            self.find_elementfind_element(locator).click()
        else:
            self._click_with_modifier_click_with_modifier(locator, [None, None], modifier)
 
    def _click_with_modifier(self, locator, tag, modifier):
        self.infoinfo("Clicking %s '%s' with %s." % (tag if tag[0] else 'element', locator, modifier))
        modifier = self.parse_modifierparse_modifier(modifier)
        action = ActionChains(self.driverdriverdriver)
        for item in modifier:
            action.key_down(item)
        element = self.find_elementfind_element(locator, tag=tag[0], required=False)
        if not element:
            element = self.find_elementfind_element(locator, tag=tag[1])
        action.click(element)
        for item in modifier:
            action.key_up(item)
        action.perform()
 
    @keyword
    
    def click_element_at_coordinates(self, locator, xoffset, yoffset):
        self.infoinfo("Clicking element '%s' at coordinates x=%s, y=%s."
                  % (locator, xoffset, yoffset))
        element = self.find_elementfind_element(locator)
        action = ActionChains(self.driverdriverdriver)
        action.move_to_element(element)
        action.move_by_offset(xoffset, yoffset)
        action.click()
        action.perform()
 
    @keyword
    
    def double_click_element(self, locator):
        self.infoinfo("Double clicking element '%s'." % locator)
        element = self.find_elementfind_element(locator)
        action = ActionChains(self.driverdriverdriver)
        action.double_click(element).perform()
 
    @keyword
    
    def set_focus_to_element(self, locator):
        element = self.find_elementfind_element(locator)
        self.driverdriverdriver.execute_script("arguments[0].focus();", element)
 
    @keyword
    
    def scroll_element_into_view(self, locator):
        element = self.find_elementfind_element(locator)
        ActionChains(self.driverdriverdriver).move_to_element(element).perform()
 
    @keyword
    
    def drag_and_drop(self, locator, target):
        element = self.find_elementfind_element(locator)
        target = self.find_elementfind_element(target)
        action = ActionChains(self.driverdriverdriver)
        action.drag_and_drop(element, target).perform()
 
    @keyword
    
    def drag_and_drop_by_offset(self, locator, xoffset, yoffset):
        element = self.find_elementfind_element(locator)
        action = ActionChains(self.driverdriverdriver)
        action.drag_and_drop_by_offset(element, int(xoffset), int(yoffset))
        action.perform()
 
    @keyword
    
    def mouse_down(self, locator):
        self.infoinfo("Simulating Mouse Down on element '%s'." % locator)
        element = self.find_elementfind_element(locator)
        action = ActionChains(self.driverdriverdriver)
        action.click_and_hold(element).perform()
 
    @keyword
    
    def mouse_out(self, locator):
        self.infoinfo("Simulating Mouse Out on element '%s'." % locator)
        element = self.find_elementfind_element(locator)
        size = element.size
        offsetx = (size['width'] / 2) + 1
        offsety = (size['height'] / 2) + 1
        action = ActionChains(self.driverdriverdriver)
        action.move_to_element(element).move_by_offset(offsetx, offsety)
        action.perform()
 
    @keyword
    
    def mouse_over(self, locator):
        self.infoinfo("Simulating Mouse Over on element '%s'." % locator)
        element = self.find_elementfind_element(locator)
        action = ActionChains(self.driverdriverdriver)
        action.move_to_element(element).perform()
 
    @keyword
    
    def mouse_up(self, locator):
        self.infoinfo("Simulating Mouse Up on element '%s'." % locator)
        element = self.find_elementfind_element(locator)
        ActionChains(self.driverdriverdriver).release(element).perform()
 
    @keyword
    
    def open_context_menu(self, locator):
        element = self.find_elementfind_element(locator)
        action = ActionChains(self.driverdriverdriver)
        action.context_click(element).perform()
 
    @keyword
    
    def simulate_event(self, locator, event):
        element = self.find_elementfind_element(locator)
        script = """
element = arguments[0];
eventName = arguments[1];
if (document.createEventObject) { // IE
    return element.fireEvent('on' + eventName, document.createEventObject());
}
var evt = document.createEvent("HTMLEvents");
evt.initEvent(eventName, true, true);
return !element.dispatchEvent(evt);
        """
        self.driverdriverdriver.execute_script(script, element, event)
 
    @keyword
    
    def press_key(self, locator, key):
        if key.startswith('\\') and len(key) > 1:
            key = self._map_ascii_key_code_to_key_map_ascii_key_code_to_key(int(key[1:]))
        element = self.find_elementfind_element(locator)
        element.send_keys(key)
 
    @keyword
    
    def press_keys(self, locator=None, *keys):
        parsed_keys = self._parse_keys_parse_keys(*keys)
        if is_truthy(locator):
            self.infoinfo('Sending key(s) %s to %s element.' % (keys, locator))
        else:
            self.infoinfo('Sending key(s) %s to page.' % str(keys))
        self._press_keys_press_keys(locator, parsed_keys)
 
    def _press_keys(self, locator, parsed_keys):
        if is_truthy(locator):
            element = self.find_elementfind_element(locator)
        else:
            element = None
        for parsed_key in parsed_keys:
            actions = ActionChains(self.driverdriverdriver)
            special_keys = []
            for key in parsed_key:
                if self._selenium_keys_has_attr_selenium_keys_has_attr(key.original):
                    special_keys = self._press_keys_special_keys_press_keys_special_keys(actions, element, parsed_key,
                                                                 key, special_keys)
                else:
                    self._press_keys_normal_keys_press_keys_normal_keys(actions, element, key)
            for special_key in special_keys:
                self.infoinfo('Releasing special key %s.' % special_key.original)
                actions.key_up(special_key.converted)
            actions.perform()
 
    def _press_keys_normal_keys(self, actions, element, key):
        self.infoinfo('Sending key%s %s' % (plural_or_not(key.converted), key.converted))
        if element:
            actions.send_keys_to_element(element, key.converted)
        else:
            actions.send_keys(key.converted)
 
    def _press_keys_special_keys(self, actions, element, parsed_key, key, special_keys):
        if len(parsed_key) == 1 and element:
            self.infoinfo('Pressing special key %s to element.' % key.original)
            actions.send_keys_to_element(element, key.converted)
        elif len(parsed_key) == 1 and not element:
            self.infoinfo('Pressing special key %s to browser.' % key.original)
            actions.send_keys(key.converted)
        else:
            self.infoinfo('Pressing special key %s down.' % key.original)
            actions.key_down(key.converted)
            special_keys.append(key)
        return special_keys
 
    @keyword
    
    def get_all_links(self):
        links = self.find_elementsfind_elements("tag=a")
        return [link.get_attribute('id') for link in links]
 
    @keyword
    
    def mouse_down_on_link(self, locator):
        element = self.find_elementfind_element(locator, tag='link')
        action = ActionChains(self.driverdriverdriver)
        action.click_and_hold(element).perform()
 
    @keyword
    
    def page_should_contain_link(self, locator, message=None, loglevel='TRACE'):
        self.assert_page_containsassert_page_contains(locator, 'link', message, loglevel)
 
    @keyword
    
    def page_should_not_contain_link(self, locator, message=None, loglevel='TRACE'):
        self.assert_page_not_containsassert_page_not_contains(locator, 'link', message, loglevel)
 
    @keyword
    
    def mouse_down_on_image(self, locator):
        element = self.find_elementfind_element(locator, tag='image')
        action = ActionChains(self.driverdriverdriver)
        action.click_and_hold(element).perform()
 
    @keyword
    
    def page_should_contain_image(self, locator, message=None, loglevel='TRACE'):
        self.assert_page_containsassert_page_contains(locator, 'image', message, loglevel)
 
    @keyword
    
    def page_should_not_contain_image(self, locator, message=None, loglevel='TRACE'):
        self.assert_page_not_containsassert_page_not_contains(locator, 'image', message, loglevel)
 
    @keyword
    
    def get_element_count(self, locator):
        return len(self.find_elementsfind_elements(locator))
 
    @keyword
    
    def add_location_strategy(self, strategy_name, strategy_keyword, persist=False):
        self.element_finderelement_finderelement_finderelement_finder.register(strategy_name, strategy_keyword, persist)
 
    @keyword
    
    def remove_location_strategy(self, strategy_name):
        self.element_finderelement_finderelement_finderelement_finder.unregister(strategy_name)
 
    def _map_ascii_key_code_to_key(self, key_code):
        map = {
            0: Keys.NULL,
            8: Keys.BACK_SPACE,
            9: Keys.TAB,
            10: Keys.RETURN,
            13: Keys.ENTER,
            24: Keys.CANCEL,
            27: Keys.ESCAPE,
            32: Keys.SPACE,
            42: Keys.MULTIPLY,
            43: Keys.ADD,
            44: Keys.SEPARATOR,
            45: Keys.SUBTRACT,
            56: Keys.DECIMAL,
            57: Keys.DIVIDE,
            59: Keys.SEMICOLON,
            61: Keys.EQUALS,
            127: Keys.DELETE
        }
        key = map.get(key_code)
        if key is None:
            key = chr(key_code)
        return key
 
    def _map_named_key_code_to_special_key(self, key_name):
        try:
            return getattr(Keys, key_name)
        except AttributeError:
            message = "Unknown key named '%s'." % (key_name)
            self.debugdebug(message)
            raise ValueError(message)
 
    def _page_contains(self, text):
        self.driverdriverdriver.switch_to.default_content()
 
        if self.is_text_presentis_text_present(text):
            return True
 
        subframes = self.find_elementsfind_elements("xpath://frame|//iframe")
        self.debugdebug('Current frame has %d subframes.' % len(subframes))
        for frame in subframes:
            self.driverdriverdriver.switch_to.frame(frame)
            found_text = self.is_text_presentis_text_present(text)
            self.driverdriverdriver.switch_to.default_content()
            if found_text:
                return True
        return False
 
    def parse_modifier(self, modifier):
        modifier = modifier.upper()
        modifiers = modifier.split('+')
        keys = []
        for item in modifiers:
            item = item.strip()
            item = self._parse_aliases_parse_aliases(item)
            if hasattr(Keys, item):
                keys.append(getattr(Keys, item))
            else:
                raise ValueError("'%s' modifier does not match to Selenium Keys"
                                 % item)
        return keys
 
    def _parse_keys(self, *keys):
        if not keys:
            raise AssertionError('"keys" argument can not be empty.')
        list_keys = []
        for key in keys:
            separate_keys = self._separate_key_separate_key(key)
            separate_keys = self._convert_special_keys_convert_special_keys(separate_keys)
            list_keys.append(separate_keys)
        return list_keys
 
    def _parse_aliases(self, key):
        if key == 'CTRL':
            return 'CONTROL'
        if key == 'ESC':
            return 'ESCAPE'
        return key
 
    def _separate_key(self, key):
        one_key = ''
        list_keys = []
        for char in key:
            if char == '+' and one_key != '':
                list_keys.append(one_key)
                one_key = ''
            else:
                one_key += char
        if one_key:
            list_keys.append(one_key)
        return list_keys
 
    def _convert_special_keys(self, keys):
        KeysRecord = namedtuple('KeysRecord', 'converted, original')
        converted_keys = []
        for key in keys:
            key = self._parse_aliases_parse_aliases(key)
            if self._selenium_keys_has_attr_selenium_keys_has_attr(key):
                converted_keys.append(KeysRecord(getattr(Keys, key), key))
            else:
                converted_keys.append(KeysRecord(key, key))
        return converted_keys
 
    def _selenium_keys_has_attr(self, key):
        try:
            return hasattr(Keys, key)
        except UnicodeError:  # To support Python 2 and non ascii characters.
            return False