Browser

splinter.browser.Browser(driver_name: str = 'firefox', retry_count: int = 3, config=None, *args, **kwargs)

Get a new driver instance.

Extra arguments will be sent to the driver instance.

If there is no driver registered with the provided driver_name, this function will raise a splinter.exceptions.DriverNotFoundError exception.

Parameters:

• driver_name (str) – Name of the driver to use.

• retry_count (int) – Number of times to try and instantiate the driver.

Returns:

Driver instance

DriverAPI

class splinter.driver.DriverAPI

Basic driver API class.

back() → None

The browser will navigate to the previous URL in the history.

If there is no previous URL, this method does nothing.

check(name: str) → None

Check a checkbox by its name.

Parameters:

name (str) – name of the element to check.

Example

>>> browser.check("agree-with-terms")

If you call browser.check n times, the checkbox keeps checked, it never get unchecked.

To uncheck a checkbox, take a look in the uncheck method.

choose(name: str, value: str) → None

Choose a value in a radio buttons group.

Parameters:

• name (str) – name of the element to enter text into.

• value (str) – Value to choose.

Example

You have two radio buttons in a page, with the name gender and values ‘F’ and ‘M’.

>>> browser.choose('gender', 'F')

Then the female gender will be chosen.

property cookies: Type[CookieManagerAPI]

A CookieManager instance.

For more details, check the cookies manipulation section.

evaluate_script(script: str, *args: str) → Any

Similar to execute_script method.

Execute javascript in the browser and return the value of the expression.

Parameters:

script (str) – The piece of JavaScript to execute.

Example

>>> assert 4 == browser.evaluate_script('2 + 2')

execute_script(script: str, *args: str) → Any

Execute a piece of JavaScript in the browser.

Parameters:

script (str) – The piece of JavaScript to execute.

Example

>>> browser.execute_script('document.getElementById("body").innerHTML = "<p>Hello world!</p>"')

fill(name: str, value: str) → None

Fill the field identified by name with the content specified by value.

Parameters:

• name (str) – name of the element to enter text into.

• value (str) – Value to enter into the element.

fill_form(field_values, form_id: str | None = None, name: str | None = None) → None

Fill the fields identified by name with the content specified by value in a dict.

Currently, fill_form supports the following fields: text, password, textarea, checkbox, radio and select.

Checkboxes should be specified as a boolean in the dict.

Parameters:

• field_values (dict) – Values for all the fields in the form, in the pattern of {field name: field value}

• form_id (str) – Id of the form to fill. Can be used instead of name.

• name (str) – Name of the form to fill.

• ignore_missing (bool) – Ignore missing keys in the dict.

find_by_css(css_selector: str) → ElementList

Return an instance of ElementList, using a CSS selector to query the current page content.

Parameters:

css_selector (str) – CSS Selector to use in the search query.

find_by_id(id: str) → ElementList

Find an element on the current page by its id.

Even when only one element is find, this method returns an instance of ElementList

Parameters:

id (str) – id to use in the search query.

find_by_name(name: str) → ElementList

Find elements on the current page by their name.

Return an instance of ElementList.

Parameters:

name (str) – name to use in the search query.

find_by_tag(tag: str) → ElementList

Find all elements of a given tag in current page.

Returns an instance of ElementList

Parameters:

tag (str) – tag to use in the search query.

find_by_text(text: str) → ElementList

Find elements on the current page by their text.

Returns an instance of ElementList

Parameters:

text (str) – text to use in the search query.

find_by_value(value: str) → ElementList

Find elements on the current page by their value.

Returns an instance of ElementList

Parameters:

value (str) – value to use in the search query.

find_by_xpath(xpath: str) → ElementList

Return an instance of ElementList, using a xpath selector to query the current page content.

Parameters:

xpath (str) – Xpath to use in the search query.

find_option_by_text(text: str) → ElementList

Finds <option> elements by their text.

Returns an instance of ElementList

Parameters:

text (str) – text to use in the search query.

find_option_by_value(value: str) → ElementList

Find <option> elements by their value.

Returns an instance of ElementList

Parameters:

value (str) – value to use in the search query.

forward() → None

The browser will navigate to the next URL in the history.

If there is no URL to forward, this method does nothing.

get_alert() → Any

Change the context for working with alerts and prompts.

For more details, check the docs about iframes, alerts and prompts

get_iframe(name: Any) → Any

Change the context for working with iframes.

For more details, check the docs about iframes, alerts and prompts

property html: str

Source of current page.

html_snapshot(name: str = '', suffix: str = '.html', encoding: str = 'utf-8', unique_file: bool = True) → str

Write the current html to a file.

Parameters:

• name (str) – File name.

• suffix (str) – File extension.

• encoding (str) – File encoding.

• unique_file (str) – If true, the filename will include a path to the system temp directory and extra characters at the end to ensure the file is unique.

Returns:

Full file name of the created html snapshot.

Return type:

str

is_element_not_present_by_css(css_selector: str, wait_time: int | None = None) → bool

Verify if an element is not present in the current page.

Parameters:

• css (str) – css selector for the element.

• wait_time (int) – Number of seconds to search.

Returns:

True if the element is not present and False if is present.

Return type:

bool

is_element_not_present_by_id(id: str, wait_time: int | None = None) → bool

Verify if an element is not present in the current page.

Parameters:

• id (str) – id for the element.

• wait_time (int) – Number of seconds to search.

Returns:

True if the element is not present and False if is present.

Return type:

bool

is_element_not_present_by_name(name: str, wait_time: int | None = None) → bool

Verify if an element is not present in the current page.

Parameters:

• name (str) – name of the element.

• wait_time (int) – Number of seconds to search.

Returns:

True if the element is not present and False if is present.

Return type:

bool

is_element_not_present_by_tag(tag: str, wait_time: int | None = None) → bool

Verify if an element is not present in the current page.

Parameters:

• tag (str) – tag of the element.

• wait_time (int) – Number of seconds to search.

Returns:

True if the element is not present and False if is present.

Return type:

bool

is_element_not_present_by_text(text: str, wait_time: int | None = None) → bool

Verify if an element is not present in the current page.

Parameters:

• text (str) – text in the element.

• wait_time (int) – Number of seconds to search.

Returns:

True if the element is not present and False if is present.

Return type:

bool

is_element_not_present_by_value(value: str, wait_time: int | None = None) → bool

Verify if an element is not present in the current page.

Parameters:

• value (str) – value in the element.

• wait_time (int) – Number of seconds to search.

Returns:

True if the element is not present and False if is present.

Return type:

bool

is_element_not_present_by_xpath(xpath: str, wait_time: int | None = None) → bool

Verify if an element is not present in the current page.

Parameters:

• xpath (str) – xpath of the element.

• wait_time (int) – Number of seconds to search.

Returns:

True if the element is not present and False if is present.

Return type:

bool

is_element_present_by_css(css_selector: str, wait_time: int | None = None) → bool

Verify if an element is present in the current page.

Parameters:

• css (str) – css selector for the element.

• wait_time (int) – Number of seconds to search.

Returns:

True if the element is present and False if is not present.

Return type:

bool

is_element_present_by_id(id: str, wait_time: int | None = None) → bool

Verify if an element is present in the current page.

Parameters:

• id (str) – id for the element.

• wait_time (int) – Number of seconds to search.

Returns:

True if the element is present and False if is not present.

Return type:

bool

is_element_present_by_name(name: str, wait_time: int | None = None) → bool

Verify if an element is present in the current page.

Parameters:

• name (str) – name of the element.

• wait_time (int) – Number of seconds to search.

Returns:

True if the element is present and False if is not present.

Return type:

bool

is_element_present_by_tag(tag: str, wait_time: int | None = None) → bool

Verify if an element is present in the current page.

Parameters:

• tag (str) – tag of the element.

• wait_time (int) – Number of seconds to search.

Returns:

True if the element is present and False if is not present.

Return type:

bool

is_element_present_by_text(text: str, wait_time: int | None = None) → bool

Verify if an element is present in the current page.

Parameters:

• text (str) – text in the element.

• wait_time (int) – Number of seconds to search.

Returns:

True if the element is present and False if is not present.

Return type:

bool

is_element_present_by_value(value: str, wait_time: int | None = None) → bool

Verify if an element is present in the current page.

Parameters:

• value (str) – value in the element.

• wait_time (int) – Number of seconds to search.

Returns:

True if the element is present and False if is not present.

Return type:

bool

is_element_present_by_xpath(xpath: str, wait_time: int | None = None) → bool

Verify if an element is present in the current page.

Parameters:

• xpath (str) – xpath of the element.

• wait_time (int) – Number of seconds to search.

Returns:

True if the element is present and False if is not present.

Return type:

bool

is_text_present(text: str, wait_time: int | None = None) → bool

Check if a piece of text is on the page.

Parameters:

• text (str) – text to use in the search query.

• wait_time (int) – Number of seconds to search for the text.

Returns:

True if finds a match for the text and False if not.

Return type:

bool

new_tab(url: str) → None

The browser will navigate to the given URL in a new tab.

Parameters:

url (str) – URL path.

quit() → None

Quit the browser, closing its windows (if it has one).

reload() → None

Revisits the current URL.

screenshot(name: str | None = None, suffix: str | None = None, full: bool = False, unique_file: bool = True) → str

Take a screenshot of the current page and save it locally.

Parameters:

• name (str) – File name for the screenshot.

• suffix (str) – File extension for the screenshot.

• full (bool) – If the screenshot should be full screen or not.

• unique_file (bool) – If true, the filename will include a path to the system temp directory and extra characters at the end to ensure the file is unique.

Returns:

Full file name of the created screenshot.

Return type:

str

select(name: str, value: str) → None

Select an <option> element in an <select> element using the name of the <select> and the value of the <option>.

Parameters:

• name (str) – name of the option element.

• value (str) – Value to select.

Example

>>> browser.select("state", "NY")

property title: str

Title of current page.

type(name: str, value: str, slowly: bool = False) → str

Type a value into an element.

It’s useful to test javascript events like keyPress, keyUp, keyDown, etc.

Parameters:

• name (str) – name of the element to enter text into.

• value (str) – Value to enter into the element.

• slowly (bool) – If True, this function returns an iterator which will type one character per iteration.

uncheck(name: str) → None

Uncheck a checkbox by its name.

Parameters:

name (str) – name of the element to uncheck.

Example

>>> browser.uncheck("send-me-emails")

If you call brower.uncheck n times, the checkbox keeps unchecked, it never get checked.

To check a checkbox, take a look in the check method.

property url: str

URL of current page.

visit(url: str) → None

Use the browser to navigate to the given URL.

Parameters:

url (str) – URL path.

ElementAPI

class splinter.driver.ElementAPI

Basic element API class.

Any element in the page can be represented as an instance of ElementAPI.

Once you have an instance, you can easily access attributes like a dict:

>>> element = browser.find_by_id("link-logo").first
>>> assert element['href'] == 'https://splinter.readthedocs.io'

You can also interact with the instance using the methods and properties listed below.

check() → None

Check the element, if it’s “checkable” (e.g.: a checkbox).

If the element is already checked, this method does nothing. For unchecking elements, take a loot in the uncheck method.

property checked: bool

Get the checked status of the element.

Example

>>> element.check()
>>> assert element.checked
>>> element.uncheck()
>>> assert not element.checked

clear() → None

Reset the field value.

click() → None

Click the element.

fill(value: str) → None

Fill the element with text content.

Parameters:

value (str) – Value to enter into the element.

has_class(class_name: str) → bool

Indicates whether the element has the given class.

is_not_visible(wait_time: int | None = None) → bool

Check if an element is not visible within the given wait time.

Parameters:

wait_time (int) – Time in seconds to check for the element.

Returns:

bool

is_visible(wait_time: int | None = None) → bool

Check if an element is visible within the given wait time.

Parameters:

wait_time (int) – Time in seconds to check for the element.

Returns:

bool

mouse_out() → None

Move the mouse away from the element.

mouse_over() → None

Move the mouse over the element.

screenshot(name: str | None = None, suffix: str | None = None, full: bool = False, unique_file: bool = True) → str

Take a screenshot of the element.

select(value: str, slowly: bool = False) → None

Select an <option> element in the element using the value of the <option>.

Example

>>> element.select("NY")

property shadow_root

Get the shadow root of an element’s shadow DOM.

property text: str

All of the text within the element. HTML tags are stripped.

type(value: str, slowly: bool = False) → str

Type the value in the element.

If slowly is True, this function returns an iterator which will type one character per iteration.

It’s useful to test javascript events like keyPress, keyUp, keyDown, etc.

Example

>>> from selenium.webdriver.common.keys import Keys
>>> ElementAPI.type(Keys.RETURN)

uncheck() → None

Uncheck the element, if it’s “checkable” (e.g.: a checkbox).

If the element is already unchecked, this method does nothing. For checking elements, take a loot in the check method.

property value: str

Value of the element, usually a form element

property visible: bool

Get the current visibility status of the element.

Returns:

bool