From ac5bb1ce7256a7be55fdc692ec449145acc8d993 Mon Sep 17 00:00:00 2001 From: jsfehler Date: Thu, 13 Jun 2024 12:31:18 -0400 Subject: [PATCH] Cleanup find element docs, add browser.find() info (#1298) --- docs/conf.py | 2 + docs/find-elements.rst | 184 +++++++++++++++++++++++++++++++++++++++++ docs/finding.rst | 113 ------------------------- docs/index.rst | 2 +- 4 files changed, 187 insertions(+), 114 deletions(-) create mode 100644 docs/find-elements.rst delete mode 100644 docs/finding.rst diff --git a/docs/conf.py b/docs/conf.py index 6fcd7f1fa..bb7efd5bf 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -33,7 +33,9 @@ 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', + 'sphinx.ext.intersphinx', 'sphinx_immaterial', + ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/find-elements.rst b/docs/find-elements.rst new file mode 100644 index 000000000..bdb3b1a2f --- /dev/null +++ b/docs/find-elements.rst @@ -0,0 +1,184 @@ +.. Copyright 2012 splinter authors. All rights reserved. + Use of this source code is governed by a BSD-style + license that can be found in the LICENSE file. + +.. meta:: + :description: Find Elements + :keywords: splinter, python, tutorial, find, selectors + ++++++++++++++ +Find Elements ++++++++++++++ + +Find Methods +============ + +Splinter's browser provides 8 methods for finding elements. + +Example +------- + +Given the following HTML: + +.. highlight:: html + +:: + + Do it! + +The following methods will find the element: + +.. highlight:: python + +:: + + from splinter import Browser + + + browser = Browser() + + elems = browser.find_by_css('#btn_13') + elems = browser.find_by_xpath("//input[@id='btn_13']") + elems = browser.find_by_tag('input') + elems = browser.find_by_name('clickMeBtn') + elems = browser.find_by_text('Do it!') + elems = browser.find_by_id('btn_13') + elems = browser.find_by_value('Click Me!') + elems = browser.find('clickMeBtn') + + +Each of these methods returns an :ref:`ElementList ` with all matching elements. + +browser.find() +-------------- + +Unlike the other finder methods, ``browser.find()`` does not specify the strategy used. +By default, it searches for an element by `name`. + +This can be can changed to `css` or `xpath` using the ``browser.set_find_strategy()`` method. + +.. highlight:: python + +:: + + from splinter import Browser + + + browser = Browser() + browser.set_find_strategy('css') + + elems = browser.find('#btn_13') + +This will stay in effect for the entire life cycle of your script, unless +explicitly changed again. + +Although ``browser.find()`` has a less explicit naming structure, it's also less verbose. +If the majority of your selectors use the same strategy it can improve the readability of your script. + +Find Within Elements +==================== + +Elements implement the same finder methods as the browser. +The only difference being the root of the find operation. +Only child elements of the root element will be searched for. + +.. highlight:: python + +:: + + from splinter import Browser + + + browser = Browser() + + all_divs = browser.find_by_tag("div") + child_elements = all_divs.first.find_by_css(".item") + +Find Links +========== + +To target only links on a page, the ``links`` namespace provides 4 find methods. +This is available at both the browser and element level. + +Example +------- + +Given the following HTML: + +.. highlight:: html + +:: + +
+ Link for Example.com +
+ +The following methods will find the element: + +.. highlight:: python + +:: + + from splinter import Browser + + + browser = Browser() + + links_found = browser.links.find_by_text('Link for Example.com') + links_found = browser.links.find_by_partial_text('for Example') + links_found = browser.links.find_by_href('http://example.com') + links_found = browser.links.find_by_partial_href('example') + + elem = browser.find_by_css('.main').first + links_found = my_element.links.find_by_text('Link for Example.com') + links_found = my_element.links.find_by_partial_text('for Example.com') + links_found = my_element.links.find_by_href('http://example.com') + links_found = my_element.links.find_by_partial_href('example') + + +As the other ``find_*`` methods, these return an :ref:`ElementList `. + + +ElementList +=========== +.. _element-list: + +These objects are functionally similar to Python's list object, +but with a few differences: + +Get the first found element with the ``first`` attribute: + +.. highlight:: python + +:: + + first_found = browser.find('clickMeBtn').first + +Get the last found element with ``last`` attribute: + +.. highlight:: python + +:: + + last_found = browser.find('clickMeBtn').last + +Get by index: + +.. highlight:: python + +:: + + second_found = browser.find('clickMeBtn')[1] + + +Handling Empty Lists +-------------------- + +If an element is not found, the element finding methods return an empty ElementList. +If you try to access items in this list, a +:class:`splinter.exceptions.ElementDoesNotExist` exception will be raised. + +Further Reading +--------------- + +For more details see the API reference for the :class:`ElementList ` class. diff --git a/docs/finding.rst b/docs/finding.rst deleted file mode 100644 index 4886ec015..000000000 --- a/docs/finding.rst +++ /dev/null @@ -1,113 +0,0 @@ -.. Copyright 2012 splinter authors. All rights reserved. - Use of this source code is governed by a BSD-style - license that can be found in the LICENSE file. - -.. meta:: - :description: Finding elements - :keywords: splinter, python, tutorial, find, selectors - -+++++++++++++ -Find Elements -+++++++++++++ - -Splinter provides 6 methods for finding elements in the page, one for each -selector type: ``css``, ``xpath``, ``tag``, ``name``, ``id``, ``value``, -``text``. -Examples: - -.. highlight:: python - -:: - - browser.find_by_css('h1') - browser.find_by_xpath('//h1') - browser.find_by_tag('h1') - browser.find_by_name('name') - browser.find_by_text('Hello World!') - browser.find_by_id('firstheader') - browser.find_by_value('query') - - -Each of these methods returns a list with the found elements. You can get the -first found element with the ``first`` shortcut: - -.. highlight:: python - -:: - - first_found = browser.find_by_name('name').first - -There's also the ``last`` shortcut -- obviously, it returns the last found -element: - -.. highlight:: python - -:: - - last_found = browser.find_by_name('name').last - - -Get Element by Index -==================== - -You also can use an index to get the desired element in the list of found -elements: - -.. highlight:: python - -:: - - second_found = browser.find_by_name('name')[1] - -About ``browser.find_by_id()`` -============================== - -A web page should have only one id, so the ``find_by_id`` method returns always -a list with just one element. - -Finding links -============= - -If you want to target only links on a page, you can use the methods provided in the -links namespace. This in available at both the browser and element level. - -Examples: - -.. highlight:: python - -:: - - links_found = browser.links.find_by_text('Link for Example.com') - links_found = browser.links.find_by_partial_text('for Example') - links_found = browser.links.find_by_href('http://example.com') - links_found = browser.links.find_by_partial_href('example') - - links_found = browser.find_by_css('.main').links.find_by_text('Link for Example.com') - links_found = browser.find_by_css('.main').links.find_by_partial_text('for Example.com') - links_found = browser.find_by_css('.main').links.find_by_href('http://example.com') - links_found = browser.find_by_css('.main').links.find_by_partial_href('example') - - -As the other ``find_*`` methods, these returns a list of all found elements. - - -Chaining find of elements -========================= - -Finding methods are chainable, so you can find the descendants of a previously -found element. - -.. highlight:: python - -:: - - divs = browser.find_by_tag("div") - within_elements = divs.first.find_by_name("name") - - -``ElementDoesNotExist`` exception -================================= - -If an element is not found, the ``find_*`` methods return an empty list. But -if you try to access an element in this list, the method will raise the -:class:`splinter.exceptions.ElementDoesNotExist` exception. diff --git a/docs/index.rst b/docs/index.rst index 3b37becd3..1b3a33806 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -31,7 +31,7 @@ browser config - finding + find-elements elements-in-the-page mouse-interaction matchers