selenium.webdriver.firefox.webdriver

Classes

WebDriver([firefox_profile, firefox_binary, …])

Starts a new local session of Firefox.

class selenium.webdriver.firefox.webdriver.WebDriver(firefox_profile=None, firefox_binary=None, capabilities=None, proxy=None, executable_path='geckodriver', options=None, service_log_path='geckodriver.log', service_args=None, service=None, desired_capabilities=None, log_path=None, keep_alive=True)

Starts a new local session of Firefox.

Based on the combination and specificity of the various keyword arguments, a capabilities dictionary will be constructed that is passed to the remote end.

The keyword arguments given to this constructor are helpers to more easily allow Firefox WebDriver sessions to be customised with different options. They are mapped on to a capabilities dictionary that is passed on to the remote end.

As some of the options, such as firefox_profile and options.profile are mutually exclusive, precedence is given from how specific the setting is. capabilities is the least specific keyword argument, followed by options, followed by firefox_binary and firefox_profile.

In practice this means that if firefox_profile and options.profile are both set, the selected profile instance will always come from the most specific variable. In this case that would be firefox_profile. This will result in options.profile to be ignored because it is considered a less specific setting than the top-level firefox_profile keyword argument. Similarly, if you had specified a capabilities[“moz:firefoxOptions”][“profile”] Base64 string, this would rank below options.profile.

Parameters:

• firefox_profile – Deprecated: Instance of FirefoxProfile object or a string. If undefined, a fresh profile will be created in a temporary location on the system.
• firefox_binary – Deprecated: Instance of FirefoxBinary or full path to the Firefox binary. If undefined, the system default Firefox installation will be used.
• capabilities – Deprecated: Dictionary of desired capabilities.
• proxy – Deprecated: The proxy settings to use when communicating with Firefox via the extension connection.
• executable_path – Deprecated: Full path to override which geckodriver binary to use for Firefox 47.0.1 and greater, which defaults to picking up the binary from the system path.
• options – Instance of options.Options.
• service – (Optional) service instance for managing the starting and stopping of the driver.
• service_log_path – Deprecated: Where to log information from the driver.
• service_args – Deprecated: List of args to pass to the driver service
• desired_capabilities – Deprecated: alias of capabilities. In future versions of this library, this will replace ‘capabilities’. This will make the signature consistent with RemoteWebDriver.
• keep_alive – Whether to configure remote_connection.RemoteConnection to use HTTP keep-alive.

CONTEXT_CHROME = 'chrome'

CONTEXT_CONTENT = 'content'

add_cookie(cookie_dict) → None

Adds a cookie to your current session.

Args:

• cookie_dict: A dictionary object, with required keys - “name” and “value”;

  optional keys - “path”, “domain”, “secure”, “httpOnly”, “expiry”, “sameSite”

Usage:

driver.add_cookie({‘name’ : ‘foo’, ‘value’ : ‘bar’}) driver.add_cookie({‘name’ : ‘foo’, ‘value’ : ‘bar’, ‘path’ : ‘/’}) driver.add_cookie({‘name’ : ‘foo’, ‘value’ : ‘bar’, ‘path’ : ‘/’, ‘secure’:True}) driver.add_cookie({‘name’: ‘foo’, ‘value’: ‘bar’, ‘sameSite’: ‘Strict’})

add_credential(credential: selenium.webdriver.common.virtual_authenticator.Credential) → None

Injects a credential into the authenticator.

add_virtual_authenticator(options: selenium.webdriver.common.virtual_authenticator.VirtualAuthenticatorOptions) → None

Adds a virtual authenticator with the given options.

application_cache

Returns a ApplicationCache Object to interact with the browser app cache.

back() → None

Goes one step backward in the browser history.

Usage:

driver.back()

bidi_connection()

capabilities

returns the drivers current capabilities being used.

close() → None

Closes the current window.

Usage:

driver.close()

context(context)

Sets the context that Selenium commands are running in using a with statement. The state of the context on the server is saved before entering the block, and restored upon exiting it.

Parameters:context – Context, may be one of the class properties CONTEXT_CHROME or CONTEXT_CONTENT.

Usage example:

with selenium.context(selenium.CONTEXT_CHROME):
    # chrome scope
    ... do stuff ...

create_web_element(element_id: str) → selenium.webdriver.remote.webelement.WebElement

Creates a web element with the specified element_id.

current_url

Gets the URL of the current page.

Usage:

driver.current_url

current_window_handle

Returns the handle of the current window.

Usage:

driver.current_window_handle

delete_all_cookies() → None

Delete all cookies in the scope of the session.

Usage:

driver.delete_all_cookies()

delete_cookie(name) → None

Deletes a single cookie with the given name.

Usage:

driver.delete_cookie('my_cookie')

desired_capabilities

returns the drivers current desired capabilities being used.

execute(driver_command: str, params: dict = None) → dict

Sends a command to be executed by a command.CommandExecutor.

Args:

• driver_command: The name of the command to execute as a string.
• params: A dictionary of named parameters to send with the command.

Returns:

The command’s JSON response loaded into a dictionary object.

execute_async_script(script: str, *args)

Asynchronously Executes JavaScript in the current window/frame.

Args:

• script: The JavaScript to execute.
• *args: Any applicable arguments for your JavaScript.

Usage:

script = "var callback = arguments[arguments.length - 1]; " \
         "window.setTimeout(function(){ callback('timeout') }, 3000);"
driver.execute_async_script(script)

execute_script(script, *args)

Synchronously Executes JavaScript in the current window/frame.

Args:

• script: The JavaScript to execute.
• *args: Any applicable arguments for your JavaScript.

Usage:

driver.execute_script('return document.title;')

file_detector

file_detector_context(file_detector_class, *args, **kwargs)

Overrides the current file detector (if necessary) in limited context. Ensures the original file detector is set afterwards.

Example:

with webdriver.file_detector_context(UselessFileDetector):

someinput.send_keys(‘/etc/hosts’)

Args:

• file_detector_class - Class of the desired file detector. If the class is different

  from the current file_detector, then the class is instantiated with args and kwargs and used as a file detector during the duration of the context manager.

• args - Optional arguments that get passed to the file detector class during

  instantiation.

• kwargs - Keyword arguments, passed the same way as args.

find_element(by='id', value: Optional[str] = None) → selenium.webdriver.remote.webelement.WebElement

Find an element given a By strategy and locator.

Usage:

element = driver.find_element(By.ID, 'foo')

Return type:

WebElement

find_elements(by='id', value: Optional[str] = None) → List[selenium.webdriver.remote.webelement.WebElement]

Find elements given a By strategy and locator.

Usage:

elements = driver.find_elements(By.CLASS_NAME, 'foo')

Return type:

list of WebElement

firefox_profile

forward() → None

Goes one step forward in the browser history.

Usage:

driver.forward()

fullscreen_window() → None

Invokes the window manager-specific ‘full screen’ operation.

get(url: str) → None

Loads a web page in the current browser session.

get_cookie(name) → Optional[Dict]

Get a single cookie by name. Returns the cookie if found, None if not.

Usage:

driver.get_cookie('my_cookie')

get_cookies() → List[dict]

Returns a set of dictionaries, corresponding to cookies visible in the current session.

Usage:

driver.get_cookies()

get_credentials() → List[selenium.webdriver.common.virtual_authenticator.Credential]

Returns the list of credentials owned by the authenticator.

get_full_page_screenshot_as_base64() → str

Gets the full document screenshot of the current window as a base64 encoded string which is useful in embedded images in HTML.

Usage:

driver.get_full_page_screenshot_as_base64()

get_full_page_screenshot_as_file(filename) → bool

Saves a full document screenshot of the current window to a PNG image file. Returns False if there is any IOError, else returns True. Use full paths in your filename.

Args:

• filename: The full path you wish to save your screenshot to. This should end with a .png extension.

Usage:

driver.get_full_page_screenshot_as_file('/Screenshots/foo.png')

get_full_page_screenshot_as_png() → bytes

Gets the full document screenshot of the current window as a binary data.

Usage:

driver.get_full_page_screenshot_as_png()

get_log(log_type)

Gets the log for a given log type.

Args:

• log_type: type of log that which will be returned

Usage:

driver.get_log('browser')
driver.get_log('driver')
driver.get_log('client')
driver.get_log('server')

get_pinned_scripts() → List[str]

get_screenshot_as_base64() → str

Gets the screenshot of the current window as a base64 encoded string which is useful in embedded images in HTML.

Usage:

driver.get_screenshot_as_base64()

get_screenshot_as_file(filename) → bool

Saves a screenshot of the current window to a PNG image file. Returns False if there is any IOError, else returns True. Use full paths in your filename.

Args:

• filename: The full path you wish to save your screenshot to. This should end with a .png extension.

Usage:

driver.get_screenshot_as_file('/Screenshots/foo.png')

get_screenshot_as_png() → bytes

Gets the screenshot of the current window as a binary data.

Usage:

driver.get_screenshot_as_png()

get_window_position(windowHandle='current') → dict

Gets the x,y position of the current window.

Usage:

driver.get_window_position()

get_window_rect() → dict

Gets the x, y coordinates of the window as well as height and width of the current window.

Usage:

driver.get_window_rect()

get_window_size(windowHandle: str = 'current') → dict

Gets the width and height of the current window.

Usage:

driver.get_window_size()

implicitly_wait(time_to_wait: float) → None

Sets a sticky timeout to implicitly wait for an element to be found, or a command to complete. This method only needs to be called one time per session. To set the timeout for calls to execute_async_script, see set_script_timeout.

Args:

• time_to_wait: Amount of time to wait (in seconds)

Usage:

driver.implicitly_wait(30)

install_addon(path, temporary=False) → str

Installs Firefox addon.

Returns identifier of installed addon. This identifier can later be used to uninstall addon.

Parameters:

• temporary – allows you to load browser extensions temporarily during a session
• path – Absolute path to the addon that will be installed.

Usage:

driver.install_addon('/path/to/firebug.xpi')

log_types

Gets a list of the available log types. This only works with w3c compliant browsers.

Usage:

driver.log_types

maximize_window() → None

Maximizes the current window that webdriver is using.

minimize_window() → None

Invokes the window manager-specific ‘minimize’ operation.

mobile

name

Returns the name of the underlying browser for this instance.

Usage:

name = driver.name

orientation

Gets the current orientation of the device.

Usage:

orientation = driver.orientation

page_source

Gets the source of the current page.

Usage:

driver.page_source

pin_script(script: str, script_key=None) → selenium.webdriver.remote.script_key.ScriptKey

Store common javascript scripts to be executed later by a unique hashable ID.

print_page(print_options: Optional[selenium.webdriver.common.print_page_options.PrintOptions] = None) → str

Takes PDF of the current page.

The driver makes a best effort to return a PDF based on the provided parameters.

quit() → None

Quits the driver and close every associated window.

refresh() → None

Refreshes the current page.

Usage:

driver.refresh()

remove_all_credentials() → None

Removes all credentials from the authenticator.

remove_credential(credential_id: Union[str, bytearray]) → None

Removes a credential from the authenticator.

remove_virtual_authenticator() → None

Removes a previously added virtual authenticator.

The authenticator is no longer valid after removal, so no methods may be called.

save_full_page_screenshot(filename) → bool

Saves a full document screenshot of the current window to a PNG image file. Returns False if there is any IOError, else returns True. Use full paths in your filename.

Args:

• filename: The full path you wish to save your screenshot to. This should end with a .png extension.

Usage:

driver.save_full_page_screenshot('/Screenshots/foo.png')

save_screenshot(filename) → bool

Saves a screenshot of the current window to a PNG image file. Returns False if there is any IOError, else returns True. Use full paths in your filename.

Args:

• filename: The full path you wish to save your screenshot to. This should end with a .png extension.

Usage:

driver.save_screenshot('/Screenshots/foo.png')

set_context(context) → None

set_page_load_timeout(time_to_wait: float) → None

Set the amount of time to wait for a page load to complete before throwing an error.

Args:

• time_to_wait: The amount of time to wait

Usage:

driver.set_page_load_timeout(30)

set_script_timeout(time_to_wait: float) → None

Set the amount of time that the script should wait during an execute_async_script call before throwing an error.

Args:

• time_to_wait: The amount of time to wait (in seconds)

Usage:

driver.set_script_timeout(30)

set_user_verified(verified: bool) → None

Sets whether the authenticator will simulate success or fail on user verification.

verified: True if the authenticator will pass user verification, False otherwise.

set_window_position(x, y, windowHandle: str = 'current') → dict

Sets the x,y position of the current window. (window.moveTo)

Args:

• x: the x-coordinate in pixels to set the window position
• y: the y-coordinate in pixels to set the window position

Usage:

driver.set_window_position(0,0)

set_window_rect(x=None, y=None, width=None, height=None) → dict

Sets the x, y coordinates of the window as well as height and width of the current window. This method is only supported for W3C compatible browsers; other browsers should use set_window_position and set_window_size.

Usage:

driver.set_window_rect(x=10, y=10)
driver.set_window_rect(width=100, height=200)
driver.set_window_rect(x=10, y=10, width=100, height=200)

set_window_size(width, height, windowHandle: str = 'current') → None

Sets the width and height of the current window. (window.resizeTo)

Args:

• width: the width in pixels to set the window to
• height: the height in pixels to set the window to

Usage:

driver.set_window_size(800,600)

start_client()

Called before starting a new session.

This method may be overridden to define custom startup behavior.

start_session(capabilities: dict, browser_profile=None) → None

Creates a new session with the desired capabilities.

Args:

• capabilities - a capabilities dict to start the session with.
• browser_profile - A selenium.webdriver.firefox.firefox_profile.FirefoxProfile object. Only used if Firefox is requested.

stop_client()

Called after executing a quit command.

This method may be overridden to define custom shutdown behavior.

switch_to

Returns:

• SwitchTo: an object containing all options to switch focus into

Usage:

element = driver.switch_to.active_element
alert = driver.switch_to.alert
driver.switch_to.default_content()
driver.switch_to.frame('frame_name')
driver.switch_to.frame(1)
driver.switch_to.frame(driver.find_elements(By.TAG_NAME, "iframe")[0])
driver.switch_to.parent_frame()
driver.switch_to.window('main')

timeouts

Get all the timeouts that have been set on the current session.

Usage:

::

driver.timeouts

Return type:

Timeout

title

Returns the title of the current page.

Usage:

title = driver.title

uninstall_addon(identifier) → None

Uninstalls Firefox addon using its identifier.

Usage:

driver.uninstall_addon('addon@foo.com')

unpin(script_key: selenium.webdriver.remote.script_key.ScriptKey) → None

Remove a pinned script from storage.

virtual_authenticator_id

Returns the id of the virtual authenticator.

window_handles

Returns the handles of all windows within the current session.

Usage:

driver.window_handles