Find Elements

Find Methods

Splinter’s browser provides 8 methods for finding elements.

Example

Given the following HTML:

<input type="button" id="btn_13" name="clickMeBtn" value="Click Me!">Do it!</input>

The following methods will find the element:

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 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.

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.

from splinter import Browser


browser = Browser()

all_divs = browser.find_by_tag("div")
child_elements = all_divs.first.find_by_css(".item")

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:

<div class="main">
    <a href="http://example.com">Link for Example.com</a>
</div>

The following methods will find the element:

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 ElementList.

ElementList

These objects are functionally similar to Python’s list object, but with a few differences:

Get the first found element with the first attribute:

first_found = browser.find('clickMeBtn').first

Get the last found element with last attribute:

last_found = browser.find('clickMeBtn').last

Get by index:

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 splinter.exceptions.ElementDoesNotExist exception will be raised.

Further Reading

For more details see the API reference for the ElementList class.