src/third_party/webdriver/pylib/selenium/webdriver/support/expected_conditions.py

   1 #
   2 # Copyright 2012 WebDriver committers
   3 # Copyright 2012 Software Freedom Conservancy.
   4 #
   5 # Licensed under the Apache License, Version 2.0 (the "License");
   6 # you may not use this file except in compliance with the License.
   7 # You may obtain a copy of the License at
   8 #
   9 #      http://www.apache.org/licenses/LICENSE-2.0
  10 #
  11 # Unless required by applicable law or agreed to in writing, software
  12 # distributed under the License is distributed on an "AS IS" BASIS,
  13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 # See the License for the specific language governing permissions and
  15 # limitations under the License.
  16
  17 from selenium.common.exceptions import NoSuchElementException
  18 from selenium.common.exceptions import NoSuchFrameException
  19 from selenium.common.exceptions import StaleElementReferenceException
  20 from selenium.common.exceptions import WebDriverException
  21 from selenium.common.exceptions import NoAlertPresentException
  22
  23 """
  24  * Canned "Expected Conditions" which are generally useful within webdriver
  25  * tests.
  26 """
  27 class title_is(object):
  28     """An expectation for checking the title of a page.
  29     title is the expected title, which must be an exact match
  30     returns True if the title matches, false otherwise."""
  31     def __init__(self, title):
  32         self.title = title
  33
  34     def __call__(self, driver):
  35         return self.title == driver.title
  36
  37 class title_contains(object):
  38     """ An expectation for checking that the title contains a case-sensitive
  39     substring. title is the fragment of title expected
  40     returns True when the title matches, False otherwise
  41     """
  42     def __init__(self, title):
  43         self.title = title
  44
  45     def __call__(self, driver):
  46         return self.title in driver.title
  47
  48 class presence_of_element_located(object):
  49     """ An expectation for checking that an element is present on the DOM
  50     of a page. This does not necessarily mean that the element is visible.
  51     locator - used to find the element
  52     returns the WebElement once it is located
  53     """
  54     def __init__(self, locator):
  55         self.locator = locator
  56
  57     def __call__(self, driver):
  58         return _find_element(driver, self.locator)
  59
  60 class visibility_of_element_located(object):
  61     """ An expectation for checking that an element is present on the DOM of a
  62     page and visible. Visibility means that the element is not only displayed
  63     but also has a height and width that is greater than 0.
  64     locator - used to find the element
  65     returns the WebElement once it is located and visible
  66     """
  67     def __init__(self, locator):
  68         self.locator = locator
  69
  70     def __call__(self, driver):
  71         try:
  72             return _element_if_visible(_find_element(driver, self.locator))
  73         except StaleElementReferenceException:
  74             return False
  75
  76 class visibility_of(object):
  77     """ An expectation for checking that an element, known to be present on the
  78     DOM of a page, is visible. Visibility means that the element is not only
  79     displayed but also has a height and width that is greater than 0.
  80     element is the WebElement
  81     returns the (same) WebElement once it is visible
  82     """
  83     def __init__(self, element):
  84         self.element = element
  85
  86     def __call__(self, ignored):
  87         return _element_if_visible(self.element)
  88
  89 def _element_if_visible(element):
  90     return element if element.is_displayed() else False
  91
  92 class presence_of_all_elements_located(object):
  93     """ An expectation for checking that there is at least one element present
  94     on a web page.
  95     locator is used to find the element
  96     returns the list of WebElements once they are located
  97     """
  98     def __init__(self, locator):
  99         self.locator = locator
 100
 101     def __call__(self, driver):
 102         return _find_elements(driver, self.locator)
 103
 104 class text_to_be_present_in_element(object):
 105     """ An expectation for checking if the given text is present in the
 106     specified element.
 107     locator, text
 108     """
 109     def __init__(self, locator, text_):
 110         self.locator = locator
 111         self.text = text_
 112
 113     def __call__(self, driver):
 114         try :
 115             element_text = _find_element(driver, self.locator).text
 116             return self.text in element_text
 117         except StaleElementReferenceException:
 118             return False
 119
 120 class text_to_be_present_in_element_value(object):
 121     """
 122     An expectation for checking if the given text is present in the element's
 123     locator, text
 124     """
 125     def __init__(self, locator, text_):
 126         self.locator = locator
 127         self.text = text_
 128
 129     def __call__(self, driver):
 130         try:
 131             element_text = _find_element(driver,
 132                                          self.locator).get_attribute("value")
 133             if element_text:
 134                 return self.text in element_text
 135             else:
 136                 return False
 137         except StaleElementReferenceException:
 138                 return False
 139
 140 class frame_to_be_available_and_switch_to_it(object):
 141     """ An expectation for checking whether the given frame is available to
 142     switch to.  If the frame is available it switches the given driver to the
 143     specified frame.
 144     """
 145     def __init__(self, locator):
 146         self.frame_locator = locator
 147
 148     def __call__(self, driver):
 149         try:
 150             driver.switch_to_frame(self.frame_locator)
 151             return True
 152         except NoSuchFrameException:
 153             return False
 154
 155 class invisibility_of_element_located(object):
 156     """ An Expectation for checking that an element is either invisible or not
 157     present on the DOM.
 158
 159     locator used to find the element
 160     """
 161     def __init__(self, locator):
 162         self.locator = locator
 163
 164     def __call__(self, driver):
 165         try:
 166             return not _find_element(driver, self.locator).is_displayed()
 167         except (NoSuchElementException, StaleElementReferenceException):
 168             # In the case of NoSuchElement, returns true because the element is
 169             # not present in DOM. The try block checks if the element is present
 170             # but is invisible.
 171             # In the case of StaleElementReference, returns true because stale
 172             # element reference implies that element is no longer visible.
 173             return True
 174
 175 class element_to_be_clickable(object):
 176     """ An Expectation for checking an element is visible and enabled such that
 177     you can click it."""
 178     def __init__(self, locator):
 179         self.locator = locator
 180
 181     def __call__(self, driver):
 182         element = visibility_of_element_located(self.locator)(driver)
 183         if element and element.is_enabled():
 184             return element
 185         else:
 186             return False
 187
 188 class staleness_of(object):
 189     """ Wait until an element is no longer attached to the DOM.
 190     element is the element to wait for.
 191     returns False if the element is still attached to the DOM, true otherwise.
 192     """
 193     def __init__(self, element):
 194         self.element = element
 195
 196     def __call__(self, ignored):
 197         try:
 198             # Calling any method forces a staleness check
 199             self.element.is_enabled()
 200             return False
 201         except StaleElementReferenceException as expected:
 202             return True
 203
 204 class element_to_be_selected(object):
 205     """ An expectation for checking the selection is selected.
 206     element is WebElement object
 207     """
 208     def __init__(self, element):
 209         self.element = element
 210
 211     def __call__(self, ignored):
 212         return self.element.is_selected()
 213
 214 class element_located_to_be_selected(object):
 215     """An expectation for the element to be located is selected.
 216     locator is a tuple of (by, path)"""
 217     def __init__(self, locator):
 218         self.locator = locator
 219
 220     def __call__(self, driver):
 221         return _find_element(driver, self.locator).is_selected()
 222
 223 class element_selection_state_to_be(object):
 224     """ An expectation for checking if the given element is selected.
 225     element is WebElement object
 226     is_selected is a Boolean."
 227     """
 228     def __init__(self, element, is_selected):
 229         self.element = element
 230         self.is_selected = is_selected
 231
 232     def __call__(self, ignored):
 233         return self.element.is_selected() == self.is_selected
 234
 235 class element_located_selection_state_to_be(object):
 236     """ An expectation to locate an element and check if the selection state
 237     specified is in that state.
 238     locator is a tuple of (by, path)
 239     is_selected is a boolean
 240     """
 241     def __init__(self, locator, is_selected):
 242         self.locator = locator
 243         self.is_selected = is_selected
 244
 245     def __call__(self, driver):
 246         try:
 247             element = _find_element(driver, self.locator)
 248             return element.is_selected() == self.is_selected
 249         except StaleElementReferenceException:
 250             return False
 251
 252 class alert_is_present(object):
 253     """ Expect an alert to be present."""
 254     def __init__(self):
 255         pass
 256
 257     def __call__(self, driver):
 258         try:
 259             alert = driver.switch_to_alert()
 260             alert.text
 261             return alert
 262         except NoAlertPresentException:
 263             return False
 264
 265 def _find_element(driver, by):
 266     """ Looks up an element. Logs and re-raises WebDriverException if thrown.
 267     Method exists to gather data for
 268     http://code.google.com/p/selenium/issues/detail?id=1800
 269     """
 270     try :
 271       return driver.find_element(*by)
 272     except NoSuchElementException as e:
 273         raise e
 274     except WebDriverException as e:
 275         raise e
 276
 277
 278 def _find_elements(driver, by):
 279     try :
 280         return driver.find_elements(*by)
 281     except WebDriverException as e:
 282         raise e
 283