Updated find_element method (baijum#99)

dysphere · web-flow · commit 3b13c2f8f864 · 2022-05-31T16:32:22.000+05:30
diff --git a/source/getting-started.rst b/source/getting-started.rst
@@ -13,11 +13,12 @@ Python like this.
 
   from selenium import webdriver
   from selenium.webdriver.common.keys import Keys
+  from selenium.webdriver.common.by import By
 
   driver = webdriver.Firefox()
   driver.get("http://www.python.org")
   assert "Python" in driver.title
-  elem = driver.find_element_by_name("q")
+  elem = driver.find_element(By.NAME, "q")
   elem.clear()
   elem.send_keys("pycon")
   elem.send_keys(Keys.RETURN)
@@ -36,12 +37,14 @@ Example Explained
 
 The `selenium.webdriver` module provides all the WebDriver implementations.
 Currently supported WebDriver implementations are Firefox, Chrome, IE and
-Remote.  The `Keys` class provide keys in the keyboard like RETURN, F1, ALT etc.
+Remote.  The `Keys` class provide keys in the keyboard like RETURN, F1, ALT etc. 
+The `By` class is used to locate elements within a document. 
 
 ::
 
   from selenium import webdriver
   from selenium.webdriver.common.keys import Keys
+  from selenium.webdriver.common.by import By
 
 Next, the instance of Firefox WebDriver is created.
 
@@ -61,13 +64,13 @@ The next line is an assertion to confirm that title has "Python" word in it::
 
   assert "Python" in driver.title
 
-WebDriver offers a number of ways to find elements using one of the
-`find_element_by_*` methods.  For example, the input text element can be located
-by its `name` attribute using `find_element_by_name` method.  A detailed
-explanation of finding elements is available in the :ref:`locating-elements`
+WebDriver offers a number of ways to find elements using the
+`find_element` method.  For example, the input text element can be located
+by its `name` attribute using the `find_element` method and using By.NAME as its first parameter.  
+A detailed explanation of finding elements is available in the :ref:`locating-elements`
 chapter::
 
-  elem = driver.find_element_by_name("q")
+  elem = driver.find_element(By.NAME, "q")
 
 Next, we are sending keys, this is similar to entering keys using your keyboard.
 Special keys can be sent using `Keys` class imported from
@@ -107,6 +110,7 @@ search functionality::
   import unittest
   from selenium import webdriver
   from selenium.webdriver.common.keys import Keys
+  from selenium.webdriver.common.by import By
 
   class PythonOrgSearch(unittest.TestCase):
 
@@ -117,7 +121,7 @@ search functionality::
           driver = self.driver
           driver.get("http://www.python.org")
           self.assertIn("Python", driver.title)
-          elem = driver.find_element_by_name("q")
+          elem = driver.find_element(By.NAME, "q")
           elem.send_keys("pycon")
           elem.send_keys(Keys.RETURN)
           self.assertNotIn("No results found.", driver.page_source)
@@ -157,13 +161,14 @@ based on Java's JUnit.  This module provides the framework for organizing the
 test cases.  The `selenium.webdriver` module provides all the WebDriver
 implementations.  Currently supported WebDriver implementations are Firefox,
 Chrome, IE and Remote.  The `Keys` class provides keys in the keyboard like
-RETURN, F1, ALT etc.
+RETURN, F1, ALT etc. The `By` class is used to locate elements within a document.
 
 ::
 
   import unittest
   from selenium import webdriver
   from selenium.webdriver.common.keys import Keys
+  from selenium.webdriver.common.by import By
 
 The test case class is inherited from `unittest.TestCase`.  Inheriting from
 `TestCase` class is the way to tell `unittest` module that this is a test case::
@@ -202,13 +207,13 @@ The next line is an assertion to confirm that title has "Python" word in it::
           self.assertIn("Python", driver.title)
 
 
-WebDriver offers a number of ways to find elements using one of the
-`find_element_by_*` methods.  For example, the input text element can be located
-by its `name` attribute using `find_element_by_name` method.  Detailed
+WebDriver offers a number of ways to find elements using the
+`find_element` method.  For example, the input text element can be located
+by its `name` attribute using the `find_element` method.  Detailed
 explanation of finding elements is available in the :ref:`locating-elements`
 chapter::
 
-          elem = driver.find_element_by_name("q")
+          elem = driver.find_element(By.NAME, "q")
 
 Next, we are sending keys, this is similar to entering keys using your keyboard.
 Special keys can be send using `Keys` class imported from
diff --git a/source/locating-elements.rst b/source/locating-elements.rst
@@ -4,34 +4,13 @@ Locating Elements
 -----------------
 
 There are various strategies to locate elements in a page.  You can use the most
-appropriate one for your case.  Selenium provides the following methods to
+appropriate one for your case.  Selenium provides the following method to
 locate elements in a page:
 
-- `find_element_by_id`
-- `find_element_by_name`
-- `find_element_by_xpath`
-- `find_element_by_link_text`
-- `find_element_by_partial_link_text`
-- `find_element_by_tag_name`
-- `find_element_by_class_name`
-- `find_element_by_css_selector`
-
+- `find_element`
 
 **To find multiple elements (these methods will return a list):**
 
-- `find_elements_by_name`
-- `find_elements_by_xpath`
-- `find_elements_by_link_text`
-- `find_elements_by_partial_link_text`
-- `find_elements_by_tag_name`
-- `find_elements_by_class_name`
-- `find_elements_by_css_selector`
-
-
-Apart from the public methods given above, there are two private methods which
-might be useful for locating page elements:
-
-- `find_element`
 - `find_elements`
 
 
@@ -42,18 +21,32 @@ Example usage::
   driver.find_element(By.XPATH, '//button[text()="Some text"]')
   driver.find_elements(By.XPATH, '//button')
 
-
+The attributes available for the `By` class are used to locate elements on a page.
 These are the attributes available for `By` class::
 
     ID = "id"
+    NAME = "name"
     XPATH = "xpath"
     LINK_TEXT = "link text"
     PARTIAL_LINK_TEXT = "partial link text"
-    NAME = "name"
     TAG_NAME = "tag name"
     CLASS_NAME = "class name"
     CSS_SELECTOR = "css selector"
 
+The 'By' class is used to specify which attribute is used to locate elements on a page.
+These are the various ways the attributes are used to locate elements on a page::
+
+  find_element(By.ID, "id")
+  find_element(By.NAME, "name")
+  find_element(By.XPATH, "xpath")
+  find_element(By.LINK_TEXT, "link text")
+  find_element(By.PARTIAL_LINK_TEXT, "partial link text")
+  find_element(By.TAG_NAME, "tag name")
+  find_element(By.CLASS_NAME, "class name")
+  find_element(By.CSS_SELECTOR, "css selector")
+
+If you want to locate several elements with the same attribute replace find_element with find_elements.
+
 
 Locating by Id
 ~~~~~~~~~~~~~~
@@ -77,7 +70,7 @@ For instance, consider this page source::
 
 The form element can be located like this::
 
-  login_form = driver.find_element_by_id('loginForm')
+  login_form = driver.find_element(By.ID, 'loginForm')
 
 
 Locating by Name
@@ -103,12 +96,12 @@ For instance, consider this page source::
 
 The username & password elements can be located like this::
 
-  username = driver.find_element_by_name('username')
-  password = driver.find_element_by_name('password')
+  username = driver.find_element(By.NAME, 'username')
+  password = driver.find_element(By.NAME, 'password')
 
 This will give the "Login" button as it occurs before the "Clear" button::
 
-  continue = driver.find_element_by_name('continue')
+  continue = driver.find_element(By.NAME, 'continue')
 
 
 Locating by XPath
@@ -148,9 +141,9 @@ For instance, consider this page source::
 
 The form elements can be located like this::
 
-  login_form = driver.find_element_by_xpath("/html/body/form[1]")
-  login_form = driver.find_element_by_xpath("//form[1]")
-  login_form = driver.find_element_by_xpath("//form[@id='loginForm']")
+  login_form = driver.find_element(By.XPATH, "/html/body/form[1]")
+  login_form = driver.find_element(By.XPATH, "//form[1]")
+  login_form = driver.find_element(By.XPATH, "//form[@id='loginForm']")
 
 
 1. Absolute path (would break if the HTML was changed only slightly)
@@ -161,9 +154,9 @@ The form elements can be located like this::
 
 The username element can be located like this::
 
-  username = driver.find_element_by_xpath("//form[input/@name='username']")
-  username = driver.find_element_by_xpath("//form[@id='loginForm']/input[1]")
-  username = driver.find_element_by_xpath("//input[@name='username']")
+  username = driver.find_element(By.XPATH, "//form[input/@name='username']")
+  username = driver.find_element(By.XPATH, "//form[@id='loginForm']/input[1]")
+  username = driver.find_element(By.XPATH, "//input[@name='username']")
 
 1. First form element with an input child element with `name` set to `username`
 
@@ -174,8 +167,8 @@ The username element can be located like this::
 
 The "Clear" button element can be located like this::
 
-  clear_button = driver.find_element_by_xpath("//input[@name='continue'][@type='button']")
-  clear_button = driver.find_element_by_xpath("//form[@id='loginForm']/input[4]")
+  clear_button = driver.find_element(By.XPATH, "//input[@name='continue'][@type='button']")
+  clear_button = driver.find_element(By.XPATH, "//form[@id='loginForm']/input[4]")
 
 
 1. Input with attribute `name` set to `continue` and attribute `type` set to
@@ -224,8 +217,8 @@ For instance, consider this page source::
 
 The continue.html link can be located like this::
 
-  continue_link = driver.find_element_by_link_text('Continue')
-  continue_link = driver.find_element_by_partial_link_text('Conti')
+  continue_link = driver.find_element(By.LINK_TEXT, 'Continue')
+  continue_link = driver.find_element(By.PARTIAL_LINK_TEXT, 'Conti')
 
 
 Locating Elements by Tag Name
@@ -246,7 +239,7 @@ For instance, consider this page source::
 
 The heading (h1) element can be located like this::
 
-  heading1 = driver.find_element_by_tag_name('h1')
+  heading1 = driver.find_element(By.TAG_NAME, 'h1')
 
 
 Locating Elements by Class Name
@@ -267,7 +260,7 @@ For instance, consider this page source::
 
 The "p" element can be located like this::
 
-  content = driver.find_element_by_class_name('content')
+  content = driver.find_element(By.CLASS_NAME, 'content')
 
 Locating Elements by CSS Selectors
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -288,7 +281,7 @@ For instance, consider this page source::
 
 The "p" element can be located like this::
 
-  content = driver.find_element_by_css_selector('p.content')
+  content = driver.find_element(By.CSS_SELECTOR, 'p.content')
 
 `Sauce Labs has good documentation
 <https://saucelabs.com/resources/articles/selenium-tips-css-selectors>`_ on CSS
diff --git a/source/navigating.rst b/source/navigating.rst
@@ -28,10 +28,10 @@ ways to find elements.  For example, given an element defined as::
 
 you could find it using any of::
 
-  element = driver.find_element_by_id("passwd-id")
-  element = driver.find_element_by_name("passwd")
-  element = driver.find_element_by_xpath("//input[@id='passwd-id']")
-  element = driver.find_element_by_css_selector("input#passwd-id")
+  element = driver.find_element(By.ID, "passwd-id")
+  element = driver.find_element(By.NAME, "passwd")
+  element = driver.find_element(By.XPATH, "//input[@id='passwd-id']")
+  element = driver.find_element(By.CSS_SELECTOR, "input#passwd-id")
 
 You can also look for a link by its text, but be careful! The text must be an
 exact match! You should also be careful when using `XPATH in WebDriver`.  If
@@ -74,8 +74,8 @@ about the other elements? You can "toggle" the state of the drop down, and you
 can use "setSelected" to set something like an `OPTION` tag selected.  Dealing
 with `SELECT` tags isn't too bad::
 
-    element = driver.find_element_by_xpath("//select[@name='name']")
-    all_options = element.find_elements_by_tag_name("option")
+    element = driver.find_element(By.XPATH, "//select[@name='name']")
+    all_options = element.find_elements(By.TAG_NAME, "option")
     for option in all_options:
         print("Value is: %s" % option.get_attribute("value"))
         option.click()
@@ -88,23 +88,23 @@ elements. WebDriver's support classes include one called a "Select", which
 provides useful methods for interacting with these::
 
     from selenium.webdriver.support.ui import Select
-    select = Select(driver.find_element_by_name('name'))
+    select = Select(driver.find_element(By.NAME, 'name'))
     select.select_by_index(index)
     select.select_by_visible_text("text")
     select.select_by_value(value)
 
 
 WebDriver also provides features for deselecting all the selected options::
 
-    select = Select(driver.find_element_by_id('id'))
+    select = Select(driver.find_element(By.ID, 'id'))
     select.deselect_all()
 
 This will deselect all OPTIONs from that particular SELECT on the page.
 
 Suppose in a test, we need the list of all default selected options, Select
 class provides a property method that returns a list::
 
-    select = Select(driver.find_element_by_xpath("//select[@name='name']"))
+    select = Select(driver.find_element(By.XPATH, "//select[@name='name']"))
     all_selected_options = select.all_selected_options
     
 To get all available options::
@@ -131,8 +131,8 @@ Drag and drop
 You can use drag and drop, either moving an element by a certain amount, or on
 to another element::
 
-  element = driver.find_element_by_name("source")
-  target = driver.find_element_by_name("target")
+  element = driver.find_element(By.NAME, "source")
+  target = driver.find_element(By.NAME, "target")
 
   from selenium.webdriver import ActionChains
   action_chains = ActionChains(driver)
