Merge pull request #22 from levi-rs/add-find-write

Add find_write to waiter

Author: levi-rs

README.rst

@@ -110,3 +110,23 @@ Explicit easily solves this by waiting for the element to load in:
         login_button.click()
     finally:
         driver.quit()
+
+Additionally, you can use explicit to handle the writing:
+
+.. code-block:: python
+
+    from explicit import waiter
+    from selenium import webdriver
+    from selenium.webdriver.common.by import By
+
+    driver = webdriver.Chrome()
+
+    try:
+        driver.get("https://github.com/this/doesntexist")
+
+        waiter.find_write(driver, "login_field", "my_username", by=By.ID)
+
+        waiter.find_write(driver, "password", "my_password", by=By.ID, send_enter=True)
+
+    finally:
+        driver.quit()

explicit/waiter.py

@@ -7,6 +7,7 @@
 """
 
 from selenium.webdriver.common.by import By
+from selenium.webdriver.common.keys import Keys
 from selenium.webdriver.support.ui import WebDriverWait
 from selenium.webdriver.support import expected_conditions as EC
 
@@ -18,7 +19,7 @@
 
 
 def find_element(driver, elem_path, by=CSS, timeout=TIMEOUT, poll_frequency=0.5):
-    """ find and return an element once located
+    """ Find and return an element once located
 
     find_element locates an element on the page, waiting
     for up to timeout seconds. The element, when located,
@@ -39,3 +40,41 @@ def find_element(driver, elem_path, by=CSS, timeout=TIMEOUT, poll_frequency=0.5)
     """
     wait = WebDriverWait(driver, timeout, poll_frequency)
     return wait.until(EC.presence_of_element_located((by, elem_path)))
+
+
+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
+
+    find_write locates a writable element on the page, waiting
+    for up to timeout seconds. Once found, it writes the string
+    to it.
+
+    Args:
+        driver (selenium webdriver or element): A driver or element
+        elem_path (str): String used to located the element
+        write_str (str): String to write
+        clear_first (bool): Clear the contents before writing (default True)
+        send_enter (bool): Send a keyboard ENTER after writing string
+        by (selenium By): Selenium By reference
+        timeout (int): Selenium Wait timeout, in seconds
+        poll_frequency (float): Selenium Wait polling frequency, in seconds
+
+    Returns:
+        element: Selenium element
+
+    Raises:
+        TimeoutException: Raised when target element isn't located
+    """
+    elem = find_element(driver, elem_path=elem_path, by=by, timeout=timeout,
+                        poll_frequency=poll_frequency)
+
+    if clear_first:
+        elem.clear()
+
+    elem.send_keys(write_str)
+
+    if send_enter:
+        elem.send_keys(Keys.ENTER)
+
+    return elem

tests/test_waiter.py

@@ -1,13 +1,94 @@
+try:
+    import mock
+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
+
+
+def test_find_element_with_defaults(driver, element):
+    """ Verify the waiter can find and return an element
+    """
+    mock_css_path = "div.mock-css-path"
+
+    driver.find_element.side_effect = [None, element]
+
+    elem = waiter.find_element(driver, mock_css_path)
+
+    assert driver.find_element.called
+    assert elem is element
+    assert len(driver.mock_calls) == 2
+    assert driver.find_element.call_args_list == [mock.call(CSS, mock_css_path),
+                                                  mock.call(CSS, mock_css_path)]
+
+
+def test_find_element_with_non_defaults(driver, element):
+    """ Verify the waiter can find and return an element when using
+        non-default kwargs
+    """
+    mock_xpath_path = "div[@id=mock-id]"
+
+    driver.find_element.side_effect = [None, element]
+
+    elem = waiter.find_element(driver, mock_xpath_path, by=By.XPATH)
 
-def test_find_element(driver, element):
-    """ Verify the water can find and return an element
+    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)]
+
+
+def test_find_write_with_defaults(driver, element):
+    """ Verify the waiter can find and write to an element, using
+        default kwargs
     """
+    mock_css_path = "div.mock-css-path"
+    mock_write_string = "mock write string"
+
     driver.find_element.side_effect = [None, element]
 
-    elem = waiter.find_element(driver, "div.mock-css-path")
+    elem = waiter.find_write(driver, mock_css_path, mock_write_string)
 
+    # 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(CSS, mock_css_path),
+                                                  mock.call(CSS, mock_css_path)]
+
+    # Element writing asserts
+    assert elem.clear.called
+    assert len(elem.send_keys.call_args_list) == 1
+    assert elem.send_keys.call_args == mock.call(mock_write_string)
+
+
+def test_find_write_with_non_defaults(driver, element):
+    """ Verify the waiter can find and write to an element, using
+        non-default kwargs
+    """
+    mock_id_path = "mock id"
+    mock_write_string = "mock write string"
+
+    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)
+
+    # 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)]
+
+    # 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)]