findelement.rst (3020B)
1 Finding Elements 2 ================ 3 .. py:currentmodule:: marionette_driver.marionette 4 5 One of the most common and yet often most difficult tasks in Marionette is 6 finding a DOM element on a webpage or in the chrome UI. Marionette provides 7 several different search strategies to use when finding elements. All search 8 strategies work with both :func:`~Marionette.find_element` and 9 :func:`~Marionette.find_elements`, though some strategies are not implemented 10 in chrome scope. 11 12 In the event that more than one element is matched by the query, 13 :func:`~Marionette.find_element` will only return the first element found. In 14 the event that no elements are matched by the query, 15 :func:`~Marionette.find_element` will raise `NoSuchElementException` while 16 :func:`~Marionette.find_elements` will return an empty list. 17 18 Search Strategies 19 ----------------- 20 21 Search strategies are defined in the :class:`By` class:: 22 23 from marionette_driver import By 24 print(By.ID) 25 26 The strategies are: 27 28 * `id` - The easiest way to find an element is to refer to its id directly:: 29 30 container = client.find_element(By.ID, 'container') 31 32 * `class name` - To find elements belonging to a certain class, use `class name`:: 33 34 buttons = client.find_elements(By.CLASS_NAME, 'button') 35 36 * `css selector` - It's also possible to find elements using a `css selector`_:: 37 38 container_buttons = client.find_elements(By.CSS_SELECTOR, '#container .buttons') 39 40 * `name` - Find elements by their name attribute (not implemented in chrome 41 scope):: 42 43 form = client.find_element(By.NAME, 'signup') 44 45 * `tag name` - To find all the elements with a given tag, use `tag name`:: 46 47 paragraphs = client.find_elements(By.TAG_NAME, 'p') 48 49 * `link text` - A convenience strategy for finding link elements by their 50 innerHTML (not implemented in chrome scope):: 51 52 link = client.find_element(By.LINK_TEXT, 'Click me!') 53 54 * `partial link text` - Same as `link text` except substrings of the innerHTML 55 are matched (not implemented in chrome scope):: 56 57 link = client.find_element(By.PARTIAL_LINK_TEXT, 'Clic') 58 59 * `xpath` - Find elements using an xpath_ query:: 60 61 elem = client.find_element(By.XPATH, './/*[@id="foobar"') 62 63 .. _css selector: https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Getting_Started/Selectors 64 .. _xpath: https://developer.mozilla.org/en-US/docs/Web/XPath 65 66 67 68 Chaining Searches 69 ----------------- 70 71 In addition to the methods on the Marionette object, WebElement objects also 72 provide :func:`~WebElement.find_element` and :func:`~WebElement.find_elements` 73 methods. The difference is that only child nodes of the element will be searched. 74 Consider the following html snippet:: 75 76 <div id="content"> 77 <span id="main"></span> 78 </div> 79 <div id="footer"></div> 80 81 Doing the following will work:: 82 83 client.find_element(By.ID, 'container').find_element(By.ID, 'main') 84 85 But this will raise a `NoSuchElementException`:: 86 87 client.find_element(By.ID, 'container').find_element(By.ID, 'footer')