selenium.webdriver.remote.webdriver

The WebDriver implementation.

Functions

create_matches(options)
get_remote_connection(capabilities, ...[, ...])
import_cdp()

Classes

BaseWebDriver()	Abstract Base Class for all Webdriver subtypes.
WebDriver([command_executor, keep_alive, ...])	Controls a browser by sending commands to a remote server.

selenium.webdriver.remote.webdriver.import_cdp()

selenium.webdriver.remote.webdriver.get_remote_connection(capabilities: dict, command_executor: str | RemoteConnection, keep_alive: bool, ignore_local_proxy: bool, client_config: ClientConfig | None = None) → RemoteConnection

selenium.webdriver.remote.webdriver.create_matches(options: List[BaseOptions]) → Dict

class selenium.webdriver.remote.webdriver.BaseWebDriver

Abstract Base Class for all Webdriver subtypes.

ABC’s allow custom implementations of Webdriver to be registered so that isinstance type checks will succeed.

class selenium.webdriver.remote.webdriver.WebDriver(command_executor: str | RemoteConnection = 'http://127.0.0.1:4444', keep_alive: bool = True, file_detector: FileDetector | None = None, options: BaseOptions | List[BaseOptions] | None = None, locator_converter: LocatorConverter | None = None, web_element_cls: type | None = None, client_config: ClientConfig | None = None)

Controls a browser by sending commands to a remote server. This server is expected to be running the WebDriver wire protocol as defined at https://www.selenium.dev/documentation/legacy/json_wire_protocol/.

Attributes:

session_id - String ID of the browser session started and controlled by this WebDriver. capabilities - Dictionary of effective capabilities of this browser session as returned

by the remote server. See https://www.selenium.dev/documentation/legacy/desired_capabilities/

command_executor : str or remote_connection.RemoteConnection object used to execute commands. error_handler - errorhandler.ErrorHandler object used to handle errors.

Create a new driver that will issue commands using the wire protocol.

Parameters:

command_executorstr or remote_connection.RemoteConnection

• Either a string representing the URL of the remote server or a custom

remote_connection.RemoteConnection object. Defaults to ‘http://127.0.0.1:4444/wd/hub’.

keep_alivebool (Deprecated)

• Whether to configure remote_connection.RemoteConnection to use HTTP keep-alive. Defaults to True.

file_detectorobject or None

• Pass a custom file detector object during instantiation. If None, the default

  LocalFileDetector() will be used.

optionsoptions.Options

• Instance of a driver options.Options class.

locator_converterobject or None

• Custom locator converter to use. Defaults to None.

web_element_clsclass

• Custom class to use for web elements. Defaults to WebElement.

client_configobject or None

• Custom client configuration to use. Defaults to None.

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.

Parameters:

file_detector_classobject

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

argstuple

• Optional arguments that get passed to the file detector class during instantiation.

kwargsdict

• Keyword arguments, passed the same way as args.

Example:

>>> with webdriver.file_detector_context(UselessFileDetector):
>>>    someinput.send_keys('/etc/hosts')

property mobile: Mobile

property name: str

Returns the name of the underlying browser for this instance.

Example:

>>> name = driver.name

start_client()

Called before starting a new session.

This method may be overridden to define custom startup behavior.

stop_client()

Called after executing a quit command.

This method may be overridden to define custom shutdown behavior.

start_session(capabilities: dict) → None

Creates a new session with the desired capabilities.

Parameters:

capabilitiesdict

• A capabilities dict to start the session with.

create_web_element(element_id: str) → WebElement

Creates a web element with the specified element_id.

execute_cdp_cmd(cmd: str, cmd_args: dict)

Execute Chrome Devtools Protocol command and get returned result The command and command args should follow chrome devtools protocol domains/commands, refer to link https://chromedevtools.github.io/devtools-protocol/

Parameters:

cmdstr,

• Command name

cmd_argsdict

• Command args

• Empty dict {} if there is no command args

Returns:

A dict, empty dict {} if there is no result to return.

• To getResponseBody: {‘base64Encoded’: False, ‘body’: ‘response body string’}

Example:

>>> driver.execute_cdp_cmd("Network.getResponseBody", {"requestId": requestId})

execute(driver_command: str, params: dict[str, Any] | None = None) → dict[str, Any]

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

Parameters:

driver_commandstr

• The name of the command to execute as a string.

paramsdict

• A dictionary of named Parameters to send with the command.

Returns:

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

get(url: str) → None

Navigate the browser to the specified URL in the current window or tab.

The method does not return until the page is fully loaded (i.e. the onload event has fired).

Parameters:

urlstr

• The URL to be opened by the browser.

• Must include the protocol (e.g., http://, https://).

Example:

>>> driver = webdriver.Chrome()
>>> driver.get("https://example.com")

property title: str

Returns the title of the current page.

Example:

>>> element = driver.find_element(By.ID, "foo")
>>> print(element.title())

pin_script(script: str, script_key=None) → ScriptKey

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

Example:

>>> script = "return document.getElementById('foo').value"

unpin(script_key: ScriptKey) → None

Remove a pinned script from storage.

Example:

>>> driver.unpin(script_key)

get_pinned_scripts() → List[str]

Return a list of all pinned scripts.

Example:

>>> pinned_scripts = driver.get_pinned_scripts()

execute_script(script: str, *args)

Synchronously Executes JavaScript in the current window/frame.

Parameters:

scriptstr

• The javascript to execute.

*argstuple

• Any applicable arguments for your JavaScript.

Example:

>>> input_id = "username"
>>> input_value = "test_user"
>>> driver.execute_script("document.getElementById(arguments[0]).value = arguments[1];", input_id, input_value)

execute_async_script(script: str, *args)

Asynchronously Executes JavaScript in the current window/frame.

Parameters:

scriptstr

• The javascript to execute.

*argstuple

• Any applicable arguments for your JavaScript.

Example:

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

property current_url: str

Gets the URL of the current page.

Example:

>>> print(driver.current_url)

property page_source: str

Gets the source of the current page.

Example:

>>> print(driver.page_source)

close() → None

Closes the current window.

Example:

>>> driver.close()

quit() → None

Quits the driver and closes every associated window.

Example:

>>> driver.quit()

property current_window_handle: str

Returns the handle of the current window.

Example:

>>> print(driver.current_window_handle)

property window_handles: List[str]

Returns the handles of all windows within the current session.

Example:

>>> print(driver.window_handles)

maximize_window() → None

Maximizes the current window that webdriver is using.

Example:

>>> driver.maximize_window()

fullscreen_window() → None

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

Example:

>>> driver.fullscreen_window()

minimize_window() → None

Invokes the window manager-specific ‘minimize’ operation.

print_page(print_options: PrintOptions | None = None) → str

Takes PDF of the current page.

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

Example:

>>> driver.print_page()

property switch_to: SwitchTo

Return an object containing all options to switch focus into.

Returns:

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

Examples:

>>> 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")

back() → None

Goes one step backward in the browser history.

Example:

>>> driver.back()

forward() → None

Goes one step forward in the browser history.

Example:

>>> driver.forward()

refresh() → None

Refreshes the current page.

Example:

>>> driver.refresh()

get_cookies() → List[dict]

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

Returns:

cookies:List[dict] : A list of dictionaries, corresponding to cookies visible in the current

Example:

>>> cookies = driver.get_cookies()

get_cookie(name) → Dict | None

Get a single cookie by name. Raises ValueError if the name is empty or whitespace. Returns the cookie if found, None if not.

Example:

>>> cookie = driver.get_cookie("my_cookie")

delete_cookie(name) → None

Deletes a single cookie with the given name. Raises ValueError if the name is empty or whitespace.

Example:

>>> driver.delete_cookie("my_cookie")

delete_all_cookies() → None

Delete all cookies in the scope of the session.

Example:

>>> driver.delete_all_cookies()

add_cookie(cookie_dict) → None

Adds a cookie to your current session.

Parameters:

cookie_dictdict

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

• Optional keys - “path”, “domain”, “secure”, “httpOnly”, “expiry”, “sameSite”

Examples:

>>> 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"})

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.

Parameters:

time_to_waitfloat

• Amount of time to wait (in seconds)

Example:

>>> driver.implicitly_wait(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.

Parameters:

time_to_waitfloat

• The amount of time to wait (in seconds)

Example:

>>> driver.set_script_timeout(30)

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.

Parameters:

time_to_waitfloat

• The amount of time to wait (in seconds)

Example:

>>> driver.set_page_load_timeout(30)

property timeouts: Timeouts

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

Returns:

Timeouts: A named tuple with the following fields:

• implicit_wait: The time to wait for elements to be found.

• page_load: The time to wait for a page to load.

• script: The time to wait for scripts to execute.

Example:

>>> driver.timeouts

find_element(by='id', value: str | None = None) → WebElement

Find an element given a By strategy and locator.

Parameters:

byselenium.webdriver.common.by.By

The locating strategy to use. Default is By.ID. Supported values include: - By.ID: Locate by element ID. - By.NAME: Locate by the name attribute. - By.XPATH: Locate by an XPath expression. - By.CSS_SELECTOR: Locate by a CSS selector. - By.CLASS_NAME: Locate by the class attribute. - By.TAG_NAME: Locate by the tag name (e.g., “input”, “button”). - By.LINK_TEXT: Locate a link element by its exact text. - By.PARTIAL_LINK_TEXT: Locate a link element by partial text match. - RelativeBy: Locate elements relative to a specified root element.

Example:

element = driver.find_element(By.ID, ‘foo’)

Returns:

WebElement

The first matching WebElement found on the page.

find_elements(by='id', value: str | None = None) → List[WebElement]

Find elements given a By strategy and locator.

Parameters:

byselenium.webdriver.common.by.By

The locating strategy to use. Default is By.ID. Supported values include: - By.ID: Locate by element ID. - By.NAME: Locate by the name attribute. - By.XPATH: Locate by an XPath expression. - By.CSS_SELECTOR: Locate by a CSS selector. - By.CLASS_NAME: Locate by the class attribute. - By.TAG_NAME: Locate by the tag name (e.g., “input”, “button”). - By.LINK_TEXT: Locate a link element by its exact text. - By.PARTIAL_LINK_TEXT: Locate a link element by partial text match. - RelativeBy: Locate elements relative to a specified root element.

Example:

element = driver.find_elements(By.ID, ‘foo’)

Returns:

List[WebElement]

list of WebElements matching locator strategy found on the page.

property capabilities: dict

Returns the drivers current capabilities being used.

Example:

>>> print(driver.capabilities)

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.

Parameters:

filenamestr

• The full path you wish to save your screenshot to. This

• should end with a .png extension.

Example:

>>> driver.get_screenshot_as_file("/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.

Parameters:

filenamestr

• The full path you wish to save your screenshot to. This

• should end with a .png extension.

Example:

>>> driver.save_screenshot("/Screenshots/foo.png")

get_screenshot_as_png() → bytes

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

Example:

>>> driver.get_screenshot_as_png()

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.

Example:

>>> driver.get_screenshot_as_base64()

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

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

Parameters:

widthint

• the width in pixels to set the window to

heightint

• the height in pixels to set the window to

Example:

>>> driver.set_window_size(800, 600)

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

Gets the width and height of the current window.

Example:

>>> driver.get_window_size()

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

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

Parameters:

xfloat

• The x-coordinate in pixels to set the window position

yfloat

• The y-coordinate in pixels to set the window position

Example:

>>> driver.set_window_position(0, 0)

get_window_position(windowHandle='current') → dict

Gets the x,y position of the current window.

Example:

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

Example:

>>> driver.get_window_rect()

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.

Example:

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

property file_detector: FileDetector

property orientation

Gets the current orientation of the device.

Example:

>>> orientation = driver.orientation

start_devtools()

bidi_connection()

property script

property network

property browser

Returns a browser module object for BiDi browser commands.

Returns:

Browser: an object containing access to BiDi browser commands.

Examples:

>>> user_context = driver.browser.create_user_context()
>>> user_contexts = driver.browser.get_user_contexts()
>>> client_windows = driver.browser.get_client_windows()
>>> driver.browser.remove_user_context(user_context)

property browsing_context

Returns a browsing context module object for BiDi browsing context commands.

Returns:

BrowsingContext: an object containing access to BiDi browsing context commands.

Examples:

>>> context_id = driver.browsing_context.create(type="tab")
>>> driver.browsing_context.navigate(context=context_id, url="https://www.selenium.dev")
>>> driver.browsing_context.capture_screenshot(context=context_id)
>>> driver.browsing_context.close(context_id)

property storage

Returns a storage module object for BiDi storage commands.

Returns:

Storage: an object containing access to BiDi storage commands.

Examples:

>>> cookie_filter = CookieFilter(name="example")
>>> result = driver.storage.get_cookies(filter=cookie_filter)
>>> driver.storage.set_cookie(cookie=PartialCookie(
        "name", BytesValue(BytesValue.TYPE_STRING, "value"), "domain")
    )
>>> driver.storage.delete_cookies(filter=CookieFilter(name="example"))

property webextension

Returns a webextension module object for BiDi webextension commands.

Returns:

WebExtension: an object containing access to BiDi webextension commands.

Examples:

>>> extension_path = "/path/to/extension"
>>> extension_result = driver.webextension.install(path=extension_path)
>>> driver.webextension.uninstall(extension_result)

add_virtual_authenticator(options: VirtualAuthenticatorOptions) → None

Adds a virtual authenticator with the given options.

Example:

>>> from selenium.webdriver.common.virtual_authenticator import VirtualAuthenticatorOptions
>>> options = VirtualAuthenticatorOptions(protocol="u2f", transport="usb", device_id="myDevice123")
>>> driver.add_virtual_authenticator(options)

property virtual_authenticator_id: str

Returns the id of the virtual authenticator.

Example:

>>> print(driver.virtual_authenticator_id)

remove_virtual_authenticator() → None

Removes a previously added virtual authenticator.

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

Example:

>>> driver.remove_virtual_authenticator()

add_credential(credential: Credential) → None

Injects a credential into the authenticator.

Example:

>>> from selenium.webdriver.common.credential import Credential
>>> credential = Credential(id="user@example.com", password="aPassword")
>>> driver.add_credential(credential)

get_credentials() → List[Credential]

Returns the list of credentials owned by the authenticator.

Example:

>>> credentials = driver.get_credentials()

remove_credential(credential_id: str | bytearray) → None

Removes a credential from the authenticator.

Example:

>>> credential_id = "user@example.com"
>>> driver.remove_credential(credential_id)

remove_all_credentials() → None

Removes all credentials from the authenticator.

Example:

>>> driver.remove_all_credentials()

set_user_verified(verified: bool) → None

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

Parameters:

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

Example:

>>> driver.set_user_verified(True)

get_downloadable_files() → list

Retrieves the downloadable files as a list of file names.

Example:

>>> files = driver.get_downloadable_files()

download_file(file_name: str, target_directory: str) → None

Downloads a file with the specified file name to the target directory.

Parameters:

file_namestr

• The name of the file to download.

target_directorystr

• The path to the directory to save the downloaded file.

Example:

>>> driver.download_file("example.zip", "/path/to/directory")

delete_downloadable_files() → None

Deletes all downloadable files.

Example:

>>> driver.delete_downloadable_files()

property fedcm: FedCM

Returns the Federated Credential Management (FedCM) dialog object for interaction.

Returns:

FedCM: an object providing access to all Federated Credential Management (FedCM) dialog commands.

Examples:

>>> title = driver.fedcm.title
>>> subtitle = driver.fedcm.subtitle
>>> dialog_type = driver.fedcm.dialog_type
>>> accounts = driver.fedcm.account_list
>>> driver.fedcm.select_account(0)
>>> driver.fedcm.accept()
>>> driver.fedcm.dismiss()
>>> driver.fedcm.enable_delay()
>>> driver.fedcm.disable_delay()
>>> driver.fedcm.reset_cooldown()

property supports_fedcm: bool

Returns whether the browser supports FedCM capabilities.

Example:

>>> print(driver.supports_fedcm)

property dialog

Returns the FedCM dialog object for interaction.

Example:

>>> dialog = driver.dialog

fedcm_dialog(timeout=5, poll_frequency=0.5, ignored_exceptions=None)

Waits for and returns the FedCM dialog.

Parameters:

timeoutint

• How long to wait for the dialog

poll_frequencyfloatHow

• Frequently to poll

ignored_exceptionsAny

• Exceptions to ignore while waiting

Returns:

The FedCM dialog object if found

Raises:

TimeoutException if dialog doesn’t appear WebDriverException if FedCM not supported