selenium.webdriver.remote.webdriver

The WebDriver implementation.

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='http://127.0.0.1:4444', desired_capabilities=None, browser_profile=None, proxy=None, keep_alive=True, file_detector=None, options=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://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol

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://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities

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

Args:

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

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

• desired_capabilities - A dictionary of capabilities to request when

  starting the browser session. Required parameter.

• browser_profile - A selenium.webdriver.firefox.firefox_profile.FirefoxProfile object.

  Only used if Firefox is requested. Optional.

• proxy - A selenium.webdriver.common.proxy.Proxy object. The browser session will

  be started with given proxy settings, if possible. Optional.

• keep_alive - Whether to configure remote_connection.RemoteConnection to use

  HTTP keep-alive. Defaults to True.

• file_detector - Pass custom file detector object during instantiation. If None,

  then default LocalFileDetector() will be used.

• options - instance of a driver options.Options class

add_cookie(cookie_dict)

Adds a cookie to your current session.

Args:

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

  optional keys - “path”, “domain”, “secure”, “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_js_error_listener()

Listens for JS errors and when the contextmanager exits check if there were JS Errors

Usage:

async with driver.add_js_error_listener() as error:
    driver.find_element(By.ID, "throwing-mouseover").click()
assert error is not None
assert error.exception_details.stack_trace.call_frames[0].function_name == "onmouseover"

add_listener(event_type)

Listens for certain events that are passed in.

Args:

• event_type: The type of event that we want to look at.

Usage:

async with driver.add_listener(Console.log) as messages:
    driver.execute_script("console.log('I like cheese')")
assert messages["message"] == "I love cheese"

application_cache

Returns a ApplicationCache Object to interact with the browser app cache

back()

Goes one step backward in the browser history.

Usage:

driver.back()

capabilities

returns the drivers current capabilities being used.

close()

Closes the current window.

Usage:

driver.close()

create_web_element(element_id)

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

Delete all cookies in the scope of the session.

Usage:

driver.delete_all_cookies()

delete_cookie(name)

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, params=None)

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, *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=None)

Find an element given a By strategy and locator.

Usage:

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

Return type:

WebElement

find_element_by_class_name(name)

Finds an element by class name.

Args:

• name: The class name of the element to find.

Returns:

• WebElement - the element if it was found

Raises:

• NoSuchElementException - if the element wasn’t found

Usage:

element = driver.find_element_by_class_name('foo')

find_element_by_css_selector(css_selector)

Finds an element by css selector.

Args:

• css_selector - CSS selector string, ex: ‘a.nav#home’

Returns:

• WebElement - the element if it was found

Raises:

• NoSuchElementException - if the element wasn’t found

Usage:

element = driver.find_element_by_css_selector('#foo')

find_element_by_id(id_)

Finds an element by id.

Args:

• id_ - The id of the element to be found.

Returns:

• WebElement - the element if it was found

Raises:

• NoSuchElementException - if the element wasn’t found

Usage:

element = driver.find_element_by_id('foo')

find_element_by_link_text(link_text)

Finds an element by link text.

Args:

• link_text: The text of the element to be found.

Returns:

• WebElement - the element if it was found

Raises:

• NoSuchElementException - if the element wasn’t found

Usage:

element = driver.find_element_by_link_text('Sign In')

find_element_by_name(name)

Finds an element by name.

Args:

• name: The name of the element to find.

Returns:

• WebElement - the element if it was found

Raises:

• NoSuchElementException - if the element wasn’t found

Usage:

element = driver.find_element_by_name('foo')

find_element_by_partial_link_text(link_text)

Finds an element by a partial match of its link text.

Args:

• link_text: The text of the element to partially match on.

Returns:

• WebElement - the element if it was found

Raises:

• NoSuchElementException - if the element wasn’t found

Usage:

element = driver.find_element_by_partial_link_text('Sign')

find_element_by_tag_name(name)

Finds an element by tag name.

Args:

• name - name of html tag (eg: h1, a, span)

Returns:

• WebElement - the element if it was found

Raises:

• NoSuchElementException - if the element wasn’t found

Usage:

element = driver.find_element_by_tag_name('h1')

find_element_by_xpath(xpath)

Finds an element by xpath.

Args:

• xpath - The xpath locator of the element to find.

Returns:

• WebElement - the element if it was found

Raises:

• NoSuchElementException - if the element wasn’t found

Usage:

element = driver.find_element_by_xpath('//div/td[1]')

find_elements(by='id', value=None)

Find elements given a By strategy and locator.

Usage:

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

Return type:

list of WebElement

find_elements_by_class_name(name)

Finds elements by class name.

Args:

• name: The class name of the elements to find.

Returns:

• list of WebElement - a list with elements if any was found. An empty list if not

Usage:

elements = driver.find_elements_by_class_name('foo')

find_elements_by_css_selector(css_selector)

Finds elements by css selector.

Args:

• css_selector - CSS selector string, ex: ‘a.nav#home’

Returns:

• list of WebElement - a list with elements if any was found. An empty list if not

Usage:

elements = driver.find_elements_by_css_selector('.foo')

find_elements_by_id(id_)

Finds multiple elements by id.

Args:

• id_ - The id of the elements to be found.

Returns:

• list of WebElement - a list with elements if any was found. An empty list if not

Usage:

elements = driver.find_elements_by_id('foo')

find_elements_by_link_text(text)

Finds elements by link text.

Args:

• link_text: The text of the elements to be found.

Returns:

• list of webelement - a list with elements if any was found. an empty list if not

Usage:

elements = driver.find_elements_by_link_text('Sign In')

find_elements_by_name(name)

Finds elements by name.

Args:

• name: The name of the elements to find.

Returns:

• list of webelement - a list with elements if any was found. an empty list if not

Usage:

elements = driver.find_elements_by_name('foo')

find_elements_by_partial_link_text(link_text)

Finds elements by a partial match of their link text.

Args:

• link_text: The text of the element to partial match on.

Returns:

• list of webelement - a list with elements if any was found. an empty list if not

Usage:

elements = driver.find_elements_by_partial_link_text('Sign')

find_elements_by_tag_name(name)

Finds elements by tag name.

Args:

• name - name of html tag (eg: h1, a, span)

Returns:

• list of WebElement - a list with elements if any was found. An empty list if not

Usage:

elements = driver.find_elements_by_tag_name('h1')

find_elements_by_xpath(xpath)

Finds multiple elements by xpath.

Args:

• xpath - The xpath locator of the elements to be found.

Returns:

• list of WebElement - a list with elements if any was found. An empty list if not

Usage:

elements = driver.find_elements_by_xpath("//div[contains(@class, 'foo')]")

forward()

Goes one step forward in the browser history.

Usage:

driver.forward()

fullscreen_window()

Invokes the window manager-specific ‘full screen’ operation

get(url)

Loads a web page in the current browser session.

get_cookie(name)

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

Usage:

driver.get_cookie('my_cookie')

get_cookies()

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

Usage:

driver.get_cookies()

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

get_screenshot_as_base64()

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)

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

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

Usage:

driver.get_screenshot_as_png()

get_window_position(windowHandle='current')

Gets the x,y position of the current window.

Usage:

driver.get_window_position()

get_window_rect()

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='current')

Gets the width and height of the current window.

Usage:

driver.get_window_size()

implicitly_wait(time_to_wait)

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)

log_types

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

Usage:

driver.log_types

maximize_window()

Maximizes the current window that webdriver is using

minimize_window()

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)

quit()

Quits the driver and closes every associated window.

Usage:

driver.quit()

refresh()

Refreshes the current page.

Usage:

driver.refresh()

save_screenshot(filename)

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_page_load_timeout(time_to_wait)

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)

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_window_position(x, y, windowHandle='current')

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)

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='current')

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, browser_profile=None)

Creates a new session with the desired capabilities.

Args:

• browser_name - The name of the browser to request.
• version - Which browser version to request.
• platform - Which platform to request the browser on.
• javascript_enabled - Whether the new session should support JavaScript.
• 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

unpin(script_key)

window_handles

Returns the handles of all windows within the current session.

Usage:

driver.window_handles

selenium.webdriver.remote.webdriver.get_remote_connection(capabilities, command_executor, keep_alive, ignore_local_proxy=False)

selenium.webdriver.remote.webdriver.import_cdp()