Firefox WebDriver¶
External Requirements¶
The following applications are required:
Geckodriver must also be available on your operating system’s PATH environment variable.
Dependencies¶
To use Firefox, the python bindings for Selenium 3 or Selenium 4 must be installed.
When splinter is installed via pip, the selenium3 or selenium4 extra argument can be provided. This will automatically install the latest version of Selenium 3 or Selenium 4, respectively.
python -m pip install splinter[selenium3]
Installing Geckodriver¶
Mac OS X¶
The recommended way is by using Homebrew:
brew install geckodriver
Usage¶
To use the Firefox driver, pass the string firefox
when you create
the Browser
instance:
from splinter import Browser
browser = Browser('firefox')
Note: if you don’t provide any driver to Browser
function, firefox
will be used.
Headless mode¶
Starting with Firefox 55, Firefox can run in a headless mode.
To use headless mode, pass the headless argument when creating a new Browser instance.
from splinter import Browser
browser = Browser('firefox', headless=True)
Incognito mode¶
To use Firefox’s incognito mode, pass the incognito argument when creating a Browser instance.
from splinter import Browser
browser = Browser('firefox', incognito=True)
Specify Profile¶
You can specify a Firefox profile for using on Browser
function
using the profile
keyword (passing the name of the profile as a str
instance):
from splinter import Browser
browser = Browser('firefox', profile='my_profile')
If you don’t specify a profile, a new temporary profile will be created (and deleted when you close
the browser).
Firefox Extensions¶
An extension for firefox is a .xpi archive.
To use an extension in Firefox webdriver profile you need to give the path of
the extension, using the extensions keyword (passing the extensions as a list
instance):
from splinter import Browser
browser = Browser('firefox', extensions=['extension1.xpi', 'extension2.xpi'])
After the browser is closed, extensions will be deleted from the profile, even if the profile is not a temporary one.
Selenium Capabilities¶
from splinter import Browser
browser = Browser('firefox', capabilities={'acceptSslCerts': True})
You can pass any selenium read-write DesiredCapabilities parameters for Firefox.
API docs¶
-
class
splinter.driver.webdriver.firefox.
WebDriver
(options=None, profile=None, extensions=None, user_agent=None, profile_preferences=None, fullscreen=False, wait_time=2, capabilities=None, headless=False, incognito=False, **kwargs)¶ -
attach_file
(name, value)¶ Fill the field identified by
name
with the content specified byvalue
.Parameters: - name (str) – name of the element to enter text into.
- value (str) – Value to enter into the element.
-
back
()¶ The browser will navigate to the previous URL in the history.
If there is no previous URL, this method does nothing.
-
check
(name)¶ 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, value)¶ 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.
A
CookieManager
instance.For more details, check the cookies manipulation section.
-
evaluate_script
(script, *args)¶ 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, *args)¶ 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, value)¶ Fill the field identified by
name
with the content specified byvalue
.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=None, name=None, ignore_missing=False)¶ Fill the fields identified by
name
with the content specified byvalue
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
(finder, finder_kwargs=None, original_find: str = None, original_query: str = None, wait_time: int = None)¶ Wrapper for finding elements.
Must be attached to a class.
Returns: ElementList
-
find_by_css
(css_selector, wait_time=None)¶ 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, wait_time=None)¶ 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, wait_time=None)¶ 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, wait_time=None)¶ 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=None, wait_time=None)¶ 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, wait_time=None)¶ 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, original_find='xpath', original_query=None, wait_time=None)¶ 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)¶ 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)¶ Find
<option>
elements by their value.Returns an instance of
ElementList
Parameters: value (str) – value to use in the search query.
-
forward
()¶ The browser will navigate to the next URL in the history.
If there is no URL to forward, this method does nothing.
-
get_alert
(wait_time=None)¶ Change the context for working with alerts and prompts.
For more details, check the docs about iframes, alerts and prompts
-
get_iframe
(frame_reference)¶ Change the context for working with iframes.
For more details, check the docs about iframes, alerts and prompts
-
html
¶ Source of current page.
-
html_snapshot
(name='', suffix='.html', encoding='utf-8', unique_file=True)¶ 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, wait_time=None)¶ 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, wait_time=None)¶ 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, wait_time=None)¶ 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, wait_time=None)¶ 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, wait_time=None)¶ 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, wait_time=None)¶ 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, wait_time=None)¶ 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, wait_time=None)¶ 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, wait_time=None)¶ 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, wait_time=None)¶ 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, wait_time=None)¶ 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, wait_time=None)¶ 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, wait_time=None)¶ 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, wait_time=None)¶ 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, wait_time=None)¶ 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
()¶ Quit the browser, closing its windows (if it has one).
-
reload
()¶ Revisits the current URL.
-
screenshot
(name='', suffix='.png', full=False, unique_file=True)¶ 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, value)¶ Select an
<option>
element in an<select>
element using thename
of the<select>
and thevalue
of the<option>
.Parameters: - name (str) – name of the option element.
- value (str) – Value to select.
Example
>>> browser.select("state", "NY")
-
title
¶ Title of current page.
-
type
(name, value, slowly=False)¶ 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)¶ 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.
-
url
¶ URL of current page.
-
visit
(url)¶ Use the browser to navigate to the given URL.
Parameters: url (str) – URL path.
-