Marionette Driver

https://firefox-source-docs.mozilla.org/python/marionette_driver.html
Admin
Marionette Driver is a Python package that provides an API for automating and testing Firefox by...
Tokens:9,848
Snippets:100
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install a Firefox Addon

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Initializes the Addons API and installs an extension from a specified file path.

```python
from marionette_driver.addons import Addons

addons = Addons(marionette)
addons.install("/path/to/extension.xpi")
```

--------------------------------

### marionette_driver.addons.Addons.install

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Installs a Firefox addon from a file path or base64-encoded data. Returns the addon ID string.

```APIDOC
## install(path=None, temp=False, data=None)

### Description
Install a Firefox addon, which can be used right away.

### Parameters
- **path** (string) - Optional - A file path to the extension to be installed.
- **temp** (boolean) - Optional - Install a temporary addon. Temporary addons will automatically be uninstalled on shutdown and do not need to be signed.
- **data** (string) - Optional - A base64-encoded string of a zip-packed addon.

### Returns
- **addon_id** (string) - The addon ID string of the newly installed addon.

### Raises
- **AddonInstallException**
```

--------------------------------

### start_session(capabilities=None, process_forked=False, timeout=None)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Create a new WebDriver session.

```APIDOC
## start_session(capabilities=None, process_forked=False, timeout=None)

### Description
Create a new WebDriver session. This method must be called before performing any other action.

### Parameters
- **capabilities** (dict) - Optional - Dictionary of Marionette-recognised capabilities.
- **process_forked** (boolean) - Optional - If True, the existing process forked itself.
- **timeout** (int) - Optional - Timeout in seconds for the server to be ready.

### Response
- **Returns** (dict) - A dictionary of the capabilities offered.
```

--------------------------------

### switch_to_window(handle, focus=True)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Switches the driver focus to the specified window handle. Subsequent commands will be directed at the new window.

```APIDOC
## switch_to_window(handle, focus=True)

### Description
Switch to the specified window; subsequent commands will be directed at the new window.

### Parameters
- **handle** (string) - Required - The id of the window to switch to.
- **focus** (boolean) - Optional - Determines whether to focus the window that we just switched to. Defaults to True.
```

--------------------------------

### using_prefs(prefs, default_branch=False)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Sets browser preferences within a context manager, restoring them upon exit.

```APIDOC
## using_prefs(prefs, default_branch=False)

### Description
Set preferences for code executed in a with block, and restores them on exit.

### Parameters
- **prefs** (dict) - Required - A dict containing one or more preferences and their values to be set.
- **default_branch** (boolean) - Optional - If True the preference value will be written to the default branch. Defaults to False.
```

--------------------------------

### Manage Marionette session timeouts

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Demonstrates how to initialize a session and configure the page load timeout.

```python
marionette = Marionette(...)
marionette.start_session()
marionette.timeout.page_load = 10
marionette.timeout.page_load
# => 10
```

--------------------------------

### fullscreen()

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Synchronously sets the user agent window to full screen or restores it if already in full screen.

```APIDOC
## fullscreen()

### Description
Synchronously sets the user agent window to full screen as if the user had done “View > Enter Full Screen”, or restores it if it is already in full screen.

### Returns
- **Window rect** (object) - The dimensions and position of the window.
```

--------------------------------

### open(type=None, focus=False, private=False)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Opens a new window or tab based on the specified context type.

```APIDOC
## open(type=None, focus=False, private=False)

### Description
Open a new window, or tab based on the specified context type.

### Parameters
- **type** (string) - Optional - Type of window to be opened ('tab' or 'window').
- **focus** (boolean) - Optional - If true, the opened window will be focused.
- **private** (boolean) - Optional - If true, open a private window.

### Returns
- **Dict** (object) - Contains the new window handle and the type of opened window.
```

--------------------------------

### restart(callback=None, clean=False, in_app=True, safe_mode=False, silent=False)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Restarts the currently running browser instance, optionally with a new profile or in safe mode.

```APIDOC
### Method
`restart(callback=None, clean=False, in_app=True, safe_mode=False, silent=False)`

### Description
Restarts the browser instance. Can force termination and spawn a new instance with the same or different profile.

### Parameters
- **callback** (callable) - Optional - Function to trigger the restart.
- **clean** (bool) - Optional - If True, uses a new profile after restart.
- **in_app** (bool) - Optional - If True, triggers restart from within the application.
- **safe_mode** (bool) - Optional - If True, restarts in safe mode.
- **silent** (bool) - Optional - If True, does not open any window (MacOS only).

### Returns
- **dict** - Details of the application restart.
```

--------------------------------

### Perform Action Sequence

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Chain input actions together and execute them using the ActionSequence class.

```python
ActionSequence(self.marionette, "key", id) \
   .key_down("a") \
   .key_up("a") \
   .perform()
```

--------------------------------

### Setting Temporary Preferences

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Use the using_prefs method within a with statement to apply specific browser preferences that are automatically restored upon exit.

```python
with marionette.using_prefs({"browser.tabs.warnOnClose": True}):
    # ... do stuff ...
```

--------------------------------

### set_prefs(prefs, default_branch=False)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Set the value of a list of preferences.

```APIDOC
## set_prefs(prefs, default_branch=False)

### Description
Set the value of a list of preferences.

### Parameters
- **prefs** (dict) - Required - A dictionary containing one or more preferences and their values.
- **default_branch** (boolean) - Optional - If True, writes to the default branch.
```

--------------------------------

### Pass arguments to synchronous JavaScript

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Demonstrates passing primitive values and WebElement objects as arguments to a script.

```python
result = marionette.execute_script(
    "return arguments[0] + arguments[1];",
    script_args=(
        2,
        3,
    ),
)
assert result == 5
some_element = marionette.find_element(By.ID, "someElement")
sid = marionette.execute_script(
    "return arguments[0].id;", script_args=(some_element,)
)
assert some_element.get_attribute("id") == sid
```

--------------------------------

### ActionSequence

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

API for creating and performing action sequences such as clicks, key presses, and pointer movements.

```APIDOC
## ActionSequence

### Description
API for creating and performing action sequences. Each action method adds one or more actions to a queue. When perform() is called, the queued actions fire in order.

### Methods
- **click(element=None, button=0)**: Queue a click with the specified button.
- **key_down(value)**: Queue a keyDown action for value.
- **key_up(value)**: Queue a keyUp action for value.
- **perform()**: Perform all queued actions.
- **pointer_move(x, y, duration=None, origin=None)**: Queue a pointerMove action.
- **send_keys(keys)**: Queue a keyDown and keyUp action for each character in keys.
```

--------------------------------

### execute_async_script(script, script_args, new_sandbox, sandbox, script_timeout)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Executes an asynchronous JavaScript script in the current context.

```APIDOC
## execute_async_script(script, script_args, new_sandbox, sandbox, script_timeout)

### Description
Executes an asynchronous JavaScript script, and returns the result. The script is executed in the context set by the most recent set_context() call.

### Parameters
- **script** (string) - Required - The JavaScript code to execute.
- **script_args** (tuple) - Optional - Arguments to pass to the script.
- **new_sandbox** (boolean) - Optional - Whether to use a new sandbox.
- **sandbox** (string) - Optional - The name of the sandbox.
- **script_timeout** (integer) - Optional - Timeout for the script execution.
```

--------------------------------

### execute_script(script, script_args=(), new_sandbox=True, sandbox='default', script_timeout=None)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Executes a synchronous JavaScript script in the current context and returns the result.

```APIDOC
## execute_script(script, script_args=(), new_sandbox=True, sandbox='default', script_timeout=None)

### Description
Executes a synchronous JavaScript script, and returns the result (or None if the script does not return a value). The script is executed in the context set by the most recent set_context() call.

### Parameters
- **script** (string) - Required - A string containing the JavaScript to execute.
- **script_args** (iterable) - Optional - An iterable of arguments to pass to the script.
- **new_sandbox** (boolean) - Optional - If False, preserve global variables from the last execute_script call. Defaults to True.
- **sandbox** (string) - Optional - A tag referring to the sandbox to use. Defaults to 'default'.
- **script_timeout** (integer) - Optional - Timeout in milliseconds, overriding the session’s default script timeout.
```

--------------------------------

### switch_to_frame(frame=None)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Switch the current context to the specified frame.

```APIDOC
## switch_to_frame(frame=None)

### Description
Switch the current context to the specified frame. Subsequent commands will operate in the context of the specified frame.

### Parameters
- **frame** (WebElement|int) - Optional - A reference to the frame to switch to. If None, switches to the top-level frame.
```

--------------------------------

### using_context(context)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Sets the context (chrome or content) for Marionette commands using a context manager.

```APIDOC
## using_context(context)

### Description
Sets the context that Marionette 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** (string) - Required - Context, may be one of the class properties CONTEXT_CHROME or CONTEXT_CONTENT.
```

--------------------------------

### navigate(url)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Navigates the current top-level browsing context to the specified URL.

```APIDOC
## navigate(url)

### Description
Navigates the current top-level browsing context’s content frame to the given URL and waits for the document to load or the session’s page timeout duration to elapse.

### Parameters
- **url** (string) - Required - The URL to navigate to.
```

--------------------------------

### Execute asynchronous JavaScript with Marionette

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Demonstrates executing an async script that waits for a timeout before resolving.

```python
marionette.timeout.script = 10
result = self.marionette.execute_async_script('''
  // this script waits 5 seconds, and then returns the number 1
  let [resolve] = arguments;
  setTimeout(function() {
    resolve(1);
  }, 5000);
''')
assert result == 1
```

--------------------------------

### Define Required Preferences for GeckoInstance

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

A dictionary containing default preferences required for the Gecko instance to operate in a test environment.

```python
required_prefs _ = {'app.normandy.api_url': '', 'apz.axis_lock.mode': 0, 'apz.content_response_timeout': 60000, 'browser.discovery.enabled': False, 'browser.http.blank_page_with_error_response.enabled': True, 'browser.newtabpage.activity-stream.asrouter.userprefs.cfr.features': False, 'browser.newtabpage.activity-stream.showSponsoredTopSites': False, 'browser.region.network.url': '', 'browser.topsites.contile.enabled': False, 'browser.translations.enable': False, 'browser.uitour.enabled': False, 'datareporting.healthreport.documentServerURI': 'http://%(server)s/dummy/healthreport/', 'datareporting.healthreport.logging.consoleEnabled': False, 'datareporting.healthreport.service.enabled': False, 'datareporting.healthreport.service.firstRun': False, 'datareporting.healthreport.uploadEnabled': False, 'datareporting.policy.dataSubmissionEnabled': False, 'datareporting.policy.dataSubmissionPolicyBypassNotification': True, 'datareporting.usage.uploadEnabled': False, 'dom.disable_open_during_load': False, 'dom.file.createInChild': True, 'dom.input_events.security.minNumTicks': 0, 'dom.input_events.security.minTimeElapsedInMS': 0, 'dom.ipc.reportProcessHangs': False, 'dom.max_chrome_script_run_time': 0, 'dom.max_script_run_time': 0, 'dom.navigation.navigationRateLimit.count': 0, 'dom.permissions.testing.enabled': True, 'dom.push.connection.enabled': False, 'dom.screenorientation.allow-lock': True, 'dom.successive_dialog_time_limit': 0, 'extensions.autoDisableScopes': 0, 'extensions.blocklist.detailsURL': 'http://%(server)s/extensions-dummy/blocklistDetailsURL', 'extensions.blocklist.itemURL': 'http://%(server)s/extensions-dummy/blocklistItemURL', 'extensions.enabledScopes': 5, 'extensions.formautofill.addresses.enabled': False, 'extensions.formautofill.creditCards.enabled': False, 'extensions.getAddons.cache.enabled': False, 'extensions.getAddons.discovery.api_url': 'data:, ', 'extensions.getAddons.get.url': 'http://%(server)s/extensions-dummy/repositoryGetURL', 'extensions.getAddons.search.browseURL': 'http://%(server)s/extensions-dummy/repositoryBrowseURL', 'extensions.hotfix.url': 'http://%(server)s/extensions-dummy/hotfixURL', 'extensions.installDistroAddons': False, 'extensions.systemAddon.update.enabled': False, 'extensions.update.background.url': 'http://%(server)s/extensions-dummy/updateBackgroundURL', 'extensions.update.enabled': False, 'extensions.update.notifyUser': False, 'extensions.update.url': 'http://%(server)s/extensions-dummy/updateURL', 'focusmanager.testmode': True, 'general.useragent.updates.enabled': False, 'geo.prompt.open_system_prefs': False, 'geo.provider.network.url': '', 'geo.provider.testing': True, 'geo.wifi.scan': False, 'gfx.webrender.all': True, 'identity.fxaccounts.auth.uri': 'https://{server}/dummy/fxa', 'idle.lastDailyNotification': -1, 'media.gmp-manager.updateEnabled': False, 'media.sanity-test.disabled': True, 'media.volume_scale': '0.01', 'mousewheel.allow_scrolling_more_than_one_page': True, 'network.captive-portal-service.enabled': False, 'network.connectivity-service.enabled': False, 'network.dns.native_https_query': False, 'network.http.prompt-temp-redirect': False, 'network.manage-offline-status': False, 'network.sntp.pools': '%(server)s', 'privacy.trackingprotection.enabled': False, 'privacy.trackingprotection.pbmode.enabled': False, 'remote.prefs.recommended': False, 'security.certerrors.mitm.priming.enabled': False, 'security.notification_enable_delay': 0, 'security.remote_settings.intermediates.enabled': False, 'security.webauthn.related_origin_requests_mode': 1, 'services.settings.loglevel': 'off', 'services.settings.server': 'data:,#remote-settings-dummy/v1', 'signon.management.page.breach-alerts.enabled': False, 'signon.management.page.vulnerable-passwords.enabled': False, 'signon.rememberSignons': False, 'telemetry.fog.test.localhost_port': -1, 'termsofuse.bypassNotification': True, 'toolkit.startup.max_resumed_crashes': -1, 'toolkit.telemetry.server': 'https://%(server)s/telemetry-dummy/', 'widget.windows.window_occlusion_tracking.enabled': False}
```

--------------------------------

### Check for element presence with Wait

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Use these patterns to verify that specific elements are present in the current DOM context. Note that presence does not guarantee visibility.

```python
els = Wait(marionette).until(expected.elements_present(By.TAG_NAME, "a"))
```

```python
els = Wait(marionette).until(
    expected.elements_present(lambda m: m.find_elements(By.TAG_NAME, "a"))
)
```

--------------------------------

### Set Multiple Browser Preferences

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Updates multiple browser preferences simultaneously using a dictionary.

```python
marionette.set_prefs({"browser.tabs.warnOnClose": True})
```

--------------------------------

### Alert

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

A class for interacting with alerts and modal dialogs.

```APIDOC
## Alert

### Description
A class for interacting with alerts. Allows accepting, dismissing, and sending keys to modal dialogs.

### Methods
- **accept()**: Accept a currently displayed modal dialog.
- **dismiss()**: Dismiss a currently displayed modal dialog.
- **send_keys(*string)**: Send keys to the currently displayed text input area in an open tab modal dialog.
- **text**: Property that returns the currently displayed text in a tab modal.
```

--------------------------------

### screenshot(element=None, format='base64', full=True, scroll=True)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Captures a screenshot of a web element or the current frame.

```APIDOC
### Method
`screenshot(element=None, format='base64', full=True, scroll=True)`

### Description
Takes a screenshot of the current frame or a specific element. Returns a base64 encoded PNG string by default.

### Parameters
- **element** (object) - Optional - The element to capture.
- **format** (str) - Optional - The image format.
- **full** (bool) - Optional - Whether to capture the full frame.
- **scroll** (bool) - Optional - Whether to scroll to the element.

### Returns
- **str** - Base64 encoded PNG image.
```

--------------------------------

### Switching Marionette Context

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Use the using_context method with a with statement to temporarily switch the execution context between chrome and content scopes.

```python
with marionette.using_context(marionette.CONTEXT_CHROME):
    # chrome scope
    ... do stuff ...
```

--------------------------------

### set_pref(pref, value, default_branch=False)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Set the value of the specified preference.

```APIDOC
## set_pref(pref, value, default_branch=False)

### Description
Set the value of the specified preference.

### Parameters
- **pref** (string) - Required - Name of the preference.
- **value** (any) - Required - The value to set the preference to. If None, resets to default.
- **default_branch** (boolean) - Optional - If True, writes to the default branch.
```

--------------------------------

### send_keys(*strings)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Sends a string via synthesized keypresses to the element. Arrays are joined into a string, and integers are coerced into strings.

```APIDOC
## send_keys(*strings)

### Description
Sends the string via synthesized keypresses to the element. If an array is passed in, it will be joined into a string. If an integer is passed in, it will be coerced into a string.

### Parameters
- **strings** (list) - Required - The string or sequence of keys to send to the element.
```

--------------------------------

### Execute synchronous JavaScript with Marionette

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Basic usage of execute_script to run simple JavaScript and return a value.

```python
result = marionette.execute_script("return 1;")
assert result == 1
```

--------------------------------

### Retrieve Localized Property

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Use the L10n class to fetch translated strings from .properties files using a unique property ID.

```python
from marionette_driver.localization import L10n
l10n = L10n(marionette)

l10n.localize_property(["chrome://global/locale/findbar.properties"], "FastFind"))
```

--------------------------------

### Interact with Alerts

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Use the Alert class to accept or dismiss modal dialogs displayed in the browser.

```python
Alert(marionette).accept()
Alert(marionette).dismiss()
```

--------------------------------

### Wait.until

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Repeatedly runs a condition until its return value evaluates to true, or its timeout expires.

```APIDOC
## Wait.until(condition, is_true=None, message='')

### Description
Repeatedly runs a condition until its return value evaluates to true, or its timeout expires. If the condition returns null or does not evaluate to true, it will wait until the timeout is reached before raising a TimeoutException.

### Parameters
- **condition** (callable) - Required - A function whose return value will be returned if it evaluates to true.
- **is_true** (callable) - Optional - A predicate that terminates the wait when it evaluates to False.
- **message** (string) - Optional - A custom message to include in the exception if the wait times out.
```

--------------------------------

### get_pref(pref, default_branch=False, value_type='unspecified')

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Retrieves the value of a specified browser preference.

```APIDOC
## get_pref(pref, default_branch=False, value_type='unspecified')

### Description
Get the value of the specified preference.

### Parameters
- **pref** (string) - Required - Name of the preference.
- **default_branch** (boolean) - Optional - If True, reads from the default branch. Defaults to False.
- **value_type** (string) - Optional - XPCOM interface of the complex value (e.g., 'nsIFile', 'nsIPrefLocalizedString').

### Usage Example
marionette.get_pref("browser.tabs.warnOnClose")
```

--------------------------------

### WebElement.click()

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Simulates a mouse click on the specified DOM element.

```APIDOC
## WebElement.click()

### Description
Simulates a click on the element.
```

--------------------------------

### set_user_verified(authenticator_id, uv)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Sets the user verification status for a virtual authenticator.

```APIDOC
### set_user_verified(authenticator_id, uv)

Updates the user verification (uv) status for the authenticator.

#### Parameters
- **authenticator_id** (string) - Required - The ID of the authenticator.
- **uv** (boolean) - Required - The user verification status to set.
```

--------------------------------

### Wait for element visibility

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Use element_displayed to wait until an element is visible in the DOM. Visibility requires both display and non-zero dimensions.

```python
displayed = Wait(marionette).until(expected.element_displayed(By.ID, "foo"))
```

```python
el = marionette.find_element(By.ID, "foo")
displayed = Wait(marionette).until(expected.element_displayed(el))
```

--------------------------------

### add_virtual_authenticator(config)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Adds a new virtual authenticator with the specified configuration.

```APIDOC
### add_virtual_authenticator(config)

Adds a new virtual authenticator to the Marionette session.

#### Parameters
- **config** (object) - Required - The configuration object for the virtual authenticator.
```

--------------------------------

### Check for element absence with Wait

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Use these patterns to verify that specific elements are not present in the current DOM context.

```python
r = Wait(marionette).until(expected.elements_not_present(By.TAG_NAME, "a"))
```

```python
r = Wait(marionette).until(
    expected.elements_not_present(lambda m: m.find_elements(By.TAG_NAME, "a"))
)
```

--------------------------------

### marionette_driver.geckoinstance.GeckoInstance.close

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Closes the managed Gecko process.

```APIDOC
## GeckoInstance.close(clean=False)

### Description
Close the managed Gecko process. Depending on self.runner_class, setting clean to True may also kill the emulator process in which this instance is running.

### Parameters
- **clean** (boolean) - Optional - If True, also perform runner cleanup.
```

--------------------------------

### find_elements(method, target, id=None)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Locates all WebElements matching the provided method and target.

```APIDOC
## find_elements(method, target, id=None)

### Description
Returns a list of all WebElement instances that match the specified method and target in the current context.

### Parameters
- **method** (string) - Required - The method to use to locate the elements.
- **target** (string) - Required - The target of the search.
- **id** (string) - Optional - If specified, search for elements only inside the element with the specified id.
```

--------------------------------

### Wait for element presence

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Use element_present to wait until an element exists in the DOM, regardless of visibility.

```python
el = Wait(marionette).until(expected.element_present(By.ID, "foo"))
```

```python
el = Wait(marionette).until(
    expected.element_present(lambda m: m.find_element(By.ID, "foo"))
)
```

--------------------------------

### marionette_driver.keys.Keys

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

The Keys class provides a mapping of keyboard keys to their corresponding Unicode characters used by the Marionette driver.

```APIDOC
## marionette_driver.keys.Keys

### Description
Provides constants for keyboard keys to be used in input actions.

### Constants
- **ADD**: '\ue025'
- **ALT**: '\ue00a'
- **ARROW_DOWN**: '\ue015'
- **ARROW_LEFT**: '\ue012'
- **ARROW_RIGHT**: '\ue014'
- **ARROW_UP**: '\ue013'
- **BACK_SPACE**: '\ue003'
- **ENTER**: '\ue007'
- **ESCAPE**: '\ue00c'
- **TAB**: '\ue004'
```

--------------------------------

### quit(clean=False, in_app=True, callback=None)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Triggers a shutdown of the currently running browser instance and deletes the active Marionette session.

```APIDOC
### Method
`quit(clean=False, in_app=True, callback=None)`

### Description
Shuts down the browser instance and deletes the active session. Allows for profile manipulation when the application is not running.

### Parameters
- **clean** (bool) - Optional - If True, a new profile will be used after the next start.
- **in_app** (bool) - Optional - If True, triggers quit from within the application.
- **callback** (callable) - Optional - Function to trigger the shutdown.

### Returns
- **dict** - Details of the application shutdown, including 'cause' and 'forced' status.
```

--------------------------------

### Set Browser Preference

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Updates a single browser preference. Setting the value to None resets the preference to its default.

```python
marionette.set_pref("browser.tabs.warnOnClose", True)
```

--------------------------------

### set_context(context)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Sets the context that Marionette commands are running in.

```APIDOC
## set_context(context)

### Description
Sets the context that Marionette commands are running in.

### Parameters
- **context** (Context) - Required - May be one of the class properties CONTEXT_CHROME or CONTEXT_CONTENT.
```

--------------------------------

### add_credential(authenticator_id, credential)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Adds a credential to a specific virtual authenticator.

```APIDOC
### add_credential(authenticator_id, credential)

Registers a new credential for the specified authenticator.

#### Parameters
- **authenticator_id** (string) - Required - The ID of the authenticator.
- **credential** (object) - Required - The credential data to add.
```

--------------------------------

### Set Marionette Context

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Switches the execution context between chrome and content modes.

```python
marionette.set_context(marionette.CONTEXT_CHROME)
```

--------------------------------

### Interact with Browser Alerts

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Retrieves an alert object to perform actions like accepting the alert or reading its text.

```python
alert = self.marionette.switch_to_alert()
text = alert.text
alert.accept()
```

--------------------------------

### Retrieve a browser preference

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Fetches the value of a specific browser preference using the Marionette driver.

```python
marionette.get_pref("browser.tabs.warnOnClose")
```

--------------------------------

### get_credentials(authenticator_id)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Retrieves all credentials associated with a specific virtual authenticator.

```APIDOC
### get_credentials(authenticator_id)

Returns a list of credentials for the given authenticator.

#### Parameters
- **authenticator_id** (string) - Required - The ID of the authenticator.
```

--------------------------------

### marionette_driver.by.By

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Constants used for locating elements within the Marionette driver.

```APIDOC
## By

### Description
Locator strategy constants used to identify elements.

### Constants
- **CLASS_NAME**: 'class name'
- **CSS_SELECTOR**: 'css selector'
- **ID**: 'id'
- **LINK_TEXT**: 'link text'
- **NAME**: 'name'
- **PARTIAL_LINK_TEXT**: 'partial link text'
- **TAG_NAME**: 'tag name'
- **XPATH**: 'xpath'
```

--------------------------------

### Access window properties in JavaScript

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Use window.wrappedJSObject to access non-standard properties of the window object.

```python
result = marionette.execute_script('''
  window.wrappedJSObject.test1 = "foo";
  window.wrappedJSObject.test2 = "bar";
  return window.wrappedJSObject.test1 + window.wrappedJSObject.test2;
  ''')
assert result == "foobar"
```

--------------------------------

### marionette_driver.geckoinstance.FennecInstance.close

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Closes the managed Gecko process for Fennec instances.

```APIDOC
## FennecInstance.close(clean=False)

### Description
Close the managed Gecko process. If clean is True and the Fennec instance is running in an emulator managed by mozrunner, this will stop the emulator.

### Parameters
- **clean** (boolean) - Optional - If True, also perform runner cleanup.
```

--------------------------------

### marionette_driver.expected.elements_present

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Checks that web elements are present in the DOM of the current context.

```APIDOC
## elements_present(*args)

### Description
Checks that web elements are present in the DOM of the current context. This does not necessarily mean that the elements are visible.

### Parameters
- **args** (locator or function) - Required - A locator or a function returning a list of web elements to check.

### Returns
- **list/boolean** - A list of web elements once they are located, or False.
```

--------------------------------

### find_element(method, target, id=None)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Locates a single WebElement based on the provided method and target.

```APIDOC
## find_element(method, target, id=None)

### Description
Returns a WebElement instance that matches the specified method and target in the current context. If no element matches, a NoSuchElementException will be raised.

### Parameters
- **method** (string) - Required - The method to use to locate the element (e.g., 'id', 'name', 'class name', 'tag name', 'css selector', 'link text', 'partial link text', 'xpath').
- **target** (string) - Required - The target of the search.
- **id** (string) - Optional - If specified, search for elements only inside the element with the specified id.
```

--------------------------------

### Wait for element invisibility

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Use element_not_displayed to wait until an element is no longer visible or is stale.

```python
hidden = Wait(marionette).until(expected.element_not_displayed(By.ID, "foo"))
```

```python
el = marionette.find_element(By.ID, "foo")
hidden = Wait(marionette).until(expected.element_not_displayed(el))
```

--------------------------------

### Persist global variables between scripts

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Set new_sandbox to False to persist global variables across multiple script execution calls.

```python
marionette.execute_script("global.test1 = 'foo';")
result = self.marionette.execute_script(
    "return global.test1;", new_sandbox=False
)
assert result == "foo"
```

--------------------------------

### Add cookies to the session

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Adds a cookie to the current session using a dictionary with required name and value keys.

```python
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,
})
```

--------------------------------

### L10n.localize_property

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Retrieves the localized string for a specified property ID from a list of property files.

```APIDOC
## L10n.localize_property

### Description
Retrieve the localized string for the specified property id.

### Parameters
- **properties_urls** (List) - Required - List of .properties URLs which will be used to search for the property.
- **property_id** (String) - Required - ID of the property to retrieve the localized string for.

### Returns
- The localized string for the requested property.

### Raises
- NoSuchElementException
```

--------------------------------

### marionette_driver.timeout.Timeouts

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Manages timeout settings for a Marionette session, including page load, script execution, and implicit wait times.

```APIDOC
## class marionette_driver.timeout.Timeouts

### Description
Manages timeout settings in the Marionette session. Users can configure page load, script, and implicit wait timeouts.

### Properties
- **implicit** (int) - The time to wait for the implicit element location strategy.
- **page_load** (int) - The time to wait for the page loading to complete.
- **script** (int) - The time to wait for injected scripts to finish.

### Methods
- **reset()** - Resets all timeouts to their default values.
```

--------------------------------

### marionette_driver.expected.element_present

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Checks that a web element is present in the DOM of the current context.

```APIDOC
## class marionette_driver.expected.element_present(*args)

### Description
Checks that a web element is present in the DOM.

### Parameters
- **args** (locator or function) - Required - The locator or function returning a web element.

### Returns
- **WebElement|bool** - The web element once it is located, or False.
```

--------------------------------

### marionette_driver.expected.elements_not_present

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Checks that web elements are not present in the DOM of the current context.

```APIDOC
## elements_not_present(*args)

### Description
Checks that web elements are not present in the DOM of the current context.

### Parameters
- **args** (locator or function) - Required - A locator or a function returning a list of web elements to check.

### Returns
- **boolean** - True if elements are missing, False if one or more are present.
```

--------------------------------

### add_cookie(cookie)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Adds a cookie to the current session.

```APIDOC
## add_cookie(cookie)

### Description
Adds a cookie to your current session.

### Parameters
- **cookie** (dictionary) - Required - A dictionary object with required keys 'name' and 'value'; optional keys 'path', 'domain', 'secure', 'expiry'.
```

--------------------------------

### marionette_driver.date_time_value.DateTimeValue

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Interface for setting the value of HTML5 date and time input elements.

```APIDOC
## DateTimeValue(element)

### Description
Interface for setting the value of HTML5 “date” and “time” input elements.

### Properties
- **date** (string) - Retrieve or set the element’s date value.
- **time** (string) - Retrieve or set the element’s time value.

### Example
```python
element = marionette.find_element(By.ID, "date-test")
dt_value = DateTimeValue(element)
dt_value.date = datetime(1998, 6, 2)
```
```

--------------------------------

### marionette_driver.addons.Addons.uninstall

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Uninstalls a Firefox addon by its ID.

```APIDOC
## uninstall(addon_id)

### Description
Uninstall a Firefox addon. If the addon is restartless, it will be uninstalled right away. Otherwise a restart using restart() will be needed.

### Parameters
- **addon_id** (string) - Required - The addon ID string to uninstall.
```

--------------------------------

### marionette_driver.expected.element_not_present

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Checks that a web element is not present in the DOM of the current context.

```APIDOC
## class marionette_driver.expected.element_not_present(*args)

### Description
Checks that a web element is not present in the DOM.

### Parameters
- **args** (locator or function) - Required - The locator or function returning a web element.

### Returns
- **bool** - True if element is not present, False if it is present.
```

--------------------------------

### Set HTML5 Date Input Value

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Use the DateTimeValue class to interact with HTML5 date and time input elements. Requires a valid Marionette element reference.

```python
element = marionette.find_element(By.ID, "date-test")
dt_value = DateTimeValue(element)
dt_value.date = datetime(1998, 6, 2)
```

--------------------------------

### value_of_css_property(property_name)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Retrieves the value of a specified CSS property for the element.

```APIDOC
## value_of_css_property(property_name)

### Description
Gets the value of the specified CSS property name.

### Parameters
- **property_name** (string) - Required - Property name to get the value of.
```

--------------------------------

### WebElement.clear()

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Clears the input value of the specified DOM element.

```APIDOC
## WebElement.clear()

### Description
Clears the input of the element.
```

--------------------------------

### marionette_driver.expected.element_not_displayed

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

An expectation for checking that an element is not visible.

```APIDOC
## class marionette_driver.expected.element_not_displayed(*args)

### Description
Checks that an element is not visible in the DOM.

### Parameters
- **args** (locator or web element) - Required - The locator or web element to check.

### Returns
- **bool** - True if element is hidden, False if displayed.
```

--------------------------------

### Wait for element absence

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Use element_not_present to wait until an element is removed from the DOM.

```python
r = Wait(marionette).until(expected.element_not_present(By.ID, "foo"))
```

```python
r = Wait(marionette).until(
    expected.element_present(lambda m: m.find_element(By.ID, "foo"))
)
```

--------------------------------

### marionette_driver.expected.element_selected

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

An expectation for checking that the given element is selected.

```APIDOC
## class marionette_driver.expected.element_selected(element)

### Description
Checks that the given element is selected.

### Parameters
- **element** (WebElement) - Required - The element to check.

### Returns
- **bool** - True if element is selected, False otherwise.
```

--------------------------------

### marionette_driver.transport.TcpTransport

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Handles TCP communication with the Marionette remote server, including connection management and message exchange.

```APIDOC
## class marionette_driver.transport.TcpTransport

### Description
Socket client that communicates with Marionette via TCP. It handles the protocol of the remote debugger in Gecko.

### Methods
- **connect()** - Connects to the server and processes the initial hello message. Returns a tuple of (protocol_level, application_type).
- **close()** - Closes the socket and frees resources.
- **receive(unmarshal=True)** - Waits for the next complete response from the remote. If unmarshal is True, returns a Message object.
- **request(name, params)** - Sends a command message to the remote server and waits for a response.
- **send(obj)** - Sends a message or JSON serializable object to the remote server.
- **respond(obj)** - Sends a response to a command.
```

--------------------------------

### marionette_driver.expected.element_displayed

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

An expectation for checking that an element is visible. Visibility means the element is displayed and has height and width greater than 0 pixels.

```APIDOC
## class marionette_driver.expected.element_displayed(*args)

### Description
Checks that an element is visible in the DOM.

### Parameters
- **args** (locator or web element) - Required - The locator or web element to check.

### Returns
- **bool** - True if element is displayed, False if hidden.
```

--------------------------------

### marionette_driver.expected.element_not_selected

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

An expectation for checking that the given element is not selected.

```APIDOC
## class marionette_driver.expected.element_not_selected(element)

### Description
Checks that the given element is not selected.

### Parameters
- **element** (WebElement) - Required - The element to check.

### Returns
- **bool** - True if element is not selected, False if selected.
```

--------------------------------

### Delete all session cookies

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Removes all cookies currently associated with the session.

```python
driver.delete_all_cookies()
```

--------------------------------

### remove_all_credentials(authenticator_id)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Removes all credentials associated with a specific virtual authenticator.

```APIDOC
### remove_all_credentials(authenticator_id)

Clears all credentials for the specified authenticator.

#### Parameters
- **authenticator_id** (string) - Required - The ID of the authenticator.
```

--------------------------------

### marionette_driver.expected.element_enabled

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

An expectation for checking that the given element is enabled.

```APIDOC
## class marionette_driver.expected.element_enabled(element)

### Description
Checks that the given element is enabled.

### Parameters
- **element** (WebElement) - Required - The element to check.

### Returns
- **bool** - True if element is enabled, False otherwise.
```

--------------------------------

### marionette_driver.expected.element_not_enabled

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

An expectation for checking that the given element is disabled.

```APIDOC
## class marionette_driver.expected.element_not_enabled(element)

### Description
Checks that the given element is disabled.

### Parameters
- **element** (WebElement) - Required - The element to check.

### Returns
- **bool** - True if element is disabled, False if enabled.
```

--------------------------------

### Wait for element staleness

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Use element_stale to wait until an element is detached from the DOM.

```python
el = marionette.find_element(By.ID, "foo")
# ...
Wait(marionette).until(expected.element_stale(el))
```

--------------------------------

### delete_cookie(name)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Deletes a specific cookie by name.

```APIDOC
## delete_cookie(name)

### Description
Delete a cookie by its name.

### Parameters
- **name** (string) - Required - Name of cookie to delete.
```

--------------------------------

### remove_credential(authenticator_id, credential_id)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Removes a specific credential from an authenticator.

```APIDOC
### remove_credential(authenticator_id, credential_id)

Deletes a specific credential from the authenticator.

#### Parameters
- **authenticator_id** (string) - Required - The ID of the authenticator.
- **credential_id** (string) - Required - The ID of the credential to remove.
```

--------------------------------

### Delete a specific cookie

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Removes a cookie by its specified name.

```python
driver.delete_cookie("foo")
```

--------------------------------

### remove_virtual_authenticator(authenticator_id)

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Removes an existing virtual authenticator by its ID.

```APIDOC
### remove_virtual_authenticator(authenticator_id)

Removes a virtual authenticator from the session.

#### Parameters
- **authenticator_id** (string) - Required - The unique identifier of the authenticator to remove.
```

--------------------------------

### marionette_driver.expected.element_stale

Source: https://firefox-source-docs.mozilla.org/python/marionette_driver.html

Check that the given element is no longer attached to DOM of the current context.

```APIDOC
## class marionette_driver.expected.element_stale(element)

### Description
Checks that the element is no longer attached to the DOM.

### Parameters
- **element** (WebElement) - Required - The element to check.

### Returns
- **bool** - False if the element is still attached, True otherwise.
```
Tokens:
Raw