Merge pull request #28 from levi-rs/add-find-one-method

Add find_one method to waiter

Author: levi-rs

explicit/__init__.py

@@ -4,6 +4,11 @@
 __version__ = get_versions()['version']
 del get_versions
 
-ID = By.ID
+CLASS_NAME = By.CLASS_NAME
 CSS = By.CSS_SELECTOR
+ID = By.ID
+LINK = By.LINK_TEXT
+NAME = By.NAME
+PARTIAL_LINK = By.PARTIAL_LINK_TEXT
+TAG = By.TAG_NAME
 XPATH = By.XPATH

explicit/waiter.py

@@ -10,7 +10,8 @@
 from selenium.webdriver.support.ui import WebDriverWait
 from selenium.webdriver.support import expected_conditions as EC
 
-from explicit import CSS
+from explicit import (
+    CLASS_NAME, CSS, ID, LINK, NAME, PARTIAL_LINK, TAG, XPATH)
 
 TIMEOUT = 30
 """ int: Default timeout value, in seconds"""
@@ -64,6 +65,48 @@ def find_elements(driver, elem_path, by=CSS, timeout=TIMEOUT, poll_frequency=0.5
     return wait.until(EC.presence_of_all_elements_located((by, elem_path)))
 
 
+def find_one(driver, locator_list, elem_type=CSS, timeout=TIMEOUT):
+    """
+    Args:
+        driver (selenium webdriver): Selenium webdriver object
+        locator_list (:obj: `list` of :obj: `str`): List of CSS selector strings
+        elem_type (Selenium By types): Selenium By type (i.e. By.CSS_SELECTOR)
+        timeout (int): Number of seconds to wait before timing out
+
+    Returns:
+        Selenium Element
+
+    Raises:
+        TimeoutException: Raised if no elements are found within the TIMEOUT
+    """
+    def _find_one(driver):
+        """ Expected Condition to find and return first located element """
+        finders = {
+            CLASS_NAME: driver.find_elements_by_class_name,
+            CSS: driver.find_elements_by_css_selector,
+            ID: driver.find_elements_by_id,
+            LINK: driver.find_elements_by_link_text,
+            NAME: driver.find_elements_by_name,
+            PARTIAL_LINK: driver.find_elements_by_partial_link_text,
+            TAG: driver.find_elements_by_tag_name,
+            XPATH: driver.find_elements_by_xpath
+        }
+
+        elems = [finders[elem_type](loc) for loc in locator_list]
+
+        if any([len(elem_list) > 0 for elem_list in elems]):
+            return elems
+        else:
+            return False
+
+    raw_results = WebDriverWait(driver, timeout).until(_find_one)
+
+    # Pull out any found elements from lists
+    results = [elem for elem_list in raw_results for elem in elem_list]
+
+    return results.pop() if len(results) == 1 else results
+
+
 def find_write(driver, elem_path, write_str, clear_first=True, send_enter=False,
                by=CSS, timeout=TIMEOUT, poll_frequency=0.5):
     """ Find a writable element and write to it

setup.py

@@ -32,7 +32,7 @@
         'pytest',
     ],
     classifiers=[
-        'Development Status :: 3 - Alpha',
+        'Development Status :: 4 - Beta',
         'Intended Audience :: Developers',
         'Natural Language :: English',
         'License :: OSI Approved :: MIT License',

tests/test_waiter.py

@@ -3,12 +3,9 @@
 except ImportError:
     from unittest import mock
 
-from selenium.webdriver.common.by import By
 from selenium.webdriver.common.keys import Keys
 
-from explicit import waiter
-
-CSS = By.CSS_SELECTOR
+from explicit import waiter, CSS, ID, XPATH
 
 
 def test_find_element_with_defaults(driver, element):
@@ -35,13 +32,13 @@ def test_find_element_with_non_defaults(driver, element):
 
     driver.find_element.side_effect = [None, element]
 
-    elem = waiter.find_element(driver, mock_xpath_path, by=By.XPATH)
+    elem = waiter.find_element(driver, mock_xpath_path, by=XPATH)
 
     assert driver.find_element.called
     assert elem is element
     assert len(driver.mock_calls) == 2
-    assert driver.find_element.call_args_list == [mock.call(By.XPATH, mock_xpath_path),
-                                                  mock.call(By.XPATH, mock_xpath_path)]
+    assert driver.find_element.call_args_list == [mock.call(XPATH, mock_xpath_path),
+                                                  mock.call(XPATH, mock_xpath_path)]
 
 
 def test_find_elements_with_defaults(driver, element):
@@ -69,14 +66,14 @@ def test_find_elements_with_non_defaults(driver, element):
 
     driver.find_elements.side_effect = [None, [element, element]]
 
-    elem_list = waiter.find_elements(driver, mock_xpath_path, by=By.XPATH)
+    elem_list = waiter.find_elements(driver, mock_xpath_path, by=XPATH)
 
     assert driver.find_elements.called
     assert isinstance(elem_list, list)
     assert all(map(lambda x: x is element, elem_list))
     assert len(driver.mock_calls) == 2
-    assert driver.find_elements.call_args_list == [mock.call(By.XPATH, mock_xpath_path),
-                                                   mock.call(By.XPATH, mock_xpath_path)]
+    assert driver.find_elements.call_args_list == [mock.call(XPATH, mock_xpath_path),
+                                                   mock.call(XPATH, mock_xpath_path)]
 
 
 def test_find_write_with_defaults(driver, element):
@@ -113,17 +110,55 @@ def test_find_write_with_non_defaults(driver, element):
     driver.find_element.side_effect = [None, element]
 
     elem = waiter.find_write(driver, mock_id_path, mock_write_string,
-                             by=By.ID, clear_first=False, send_enter=True)
+                             by=ID, clear_first=False, send_enter=True)
 
     # Element locating asserts
     assert driver.find_element.called
     assert elem is element
     assert len(driver.mock_calls) == 2
-    assert driver.find_element.call_args_list == [mock.call(By.ID, mock_id_path),
-                                                  mock.call(By.ID, mock_id_path)]
+    assert driver.find_element.call_args_list == [mock.call(ID, mock_id_path),
+                                                  mock.call(ID, mock_id_path)]
 
     # Element writing asserts
     assert not elem.clear.called
     assert len(elem.send_keys.call_args_list) == 2
     assert elem.send_keys.call_args_list == [mock.call(mock_write_string),
                                              mock.call(Keys.ENTER)]
+
+
+def test_find_one_with_defaults(driver, element):
+    """ Verify the waiter can locate one of several possible elements """
+    side_effects = [[], [], [element, ], []]
+    driver.find_elements_by_css_selector.side_effect = side_effects
+
+    div1 = 'div.mock_1'
+    div2 = 'div.mock_2'
+
+    locators = [div1, div2]
+    elem = waiter.find_one(driver, locators)
+
+    assert elem is element
+    assert driver.method_calls == [mock.call.find_elements_by_css_selector(div1),
+                                   mock.call.find_elements_by_css_selector(div2),
+                                   mock.call.find_elements_by_css_selector(div1),
+                                   mock.call.find_elements_by_css_selector(div2)]
+
+
+def test_find_one_with_non_defaults(driver, element):
+    """ Verify the waiter can locate one of several possible elements,
+        using non-default function parameters
+    """
+    side_effects = [[], [], [element, ], []]
+    driver.find_elements_by_id.side_effect = side_effects
+
+    id_1 = 'mock_1'
+    id_2 = 'mock_2'
+
+    locators = [id_1, id_2]
+    elem = waiter.find_one(driver, locators, elem_type=ID, timeout=20)
+
+    assert elem is element
+    assert driver.method_calls == [mock.call.find_elements_by_id(id_1),
+                                   mock.call.find_elements_by_id(id_2),
+                                   mock.call.find_elements_by_id(id_1),
+                                   mock.call.find_elements_by_id(id_2)]