testdriver.js Automation

.. contents:: Table of Contents
   :depth: 3
   :local:
   :backlinks: none

testdriver.js provides a means to automate tests that cannot be written purely using web platform APIs. Outside of automation contexts, it allows human operators to provide expected input manually (for operations which may be described in simple terms).

testdriver.js supports the following test types:

• testharness.js tests
• reftests and print-reftests that use the

class=reftest-wait attribute on the root element to control completion

• crashtests that use the class=test-wait attribute to control

completion

Markup ##

The testdriver.js and testdriver-vendor.js must both be included in any document that uses testdriver (and in the top-level test document when using testdriver from a different context):

<script src="/resources/testdriver.js"></script>
<script src="/resources/testdriver-vendor.js"></script>

WebDriver BiDi ##

The api in test_driver.bidi provides access to the WebDriver BiDi protocol.

Markup ###

To use WebDriver BiDi, enable the bidi feature in testdriver.js by adding the feature=bidi query string parameter. Details are in RFC 214: Add testdriver features.

<script src="/resources/testdriver.js?feature=bidi"></script>

// META: script=/resources/testdriver.js?feature=bidi

Example.

Context ###

A WebDriver BiDi "browsing context" is equivalent to an HTML navigable. In WebDriver BiDi, you can interact with any browsing context, regardless of whether it's currently active. You can target a specific browsing context using either its unique string ID or its WindowProxy object.

:Context: (*String|WindowProxy*)  A browsing context. Can be specified by its ID
          (a string) or using a `WindowProxy` object.

Events ###

To receive WebDriver BiDi events, you need to subscribe to them. Events are only emitted for browsing contexts with an active subscription. You can also create a global subscription to receive events from all the contexts.

If there are buffered events, they will be emitted before the subcsribe command's promise is resolved.

API ##

testdriver.js exposes its API through the test_driver variable in the global scope.

User Interaction ###

.. js:autofunction:: test_driver.click
.. js:autofunction:: test_driver.send_keys
.. js:autofunction:: test_driver.action_sequence
.. js:autofunction:: test_driver.bless

Window State ###

.. js:autofunction:: test_driver.minimize_window
.. js:autofunction:: test_driver.set_window_rect

Cookies ###

.. js:autofunction:: test_driver.delete_all_cookies
.. js:autofunction:: test_driver.get_all_cookies
.. js:autofunction:: test_driver.get_named_cookie

Permissions ###

.. js:autofunction:: test_driver.set_permission
.. js:autofunction:: test_driver.bidi.permissions.set_permission

Authentication ###

.. js:autofunction:: test_driver.add_virtual_authenticator
.. js:autofunction:: test_driver.remove_virtual_authenticator
.. js:autofunction:: test_driver.add_credential
.. js:autofunction:: test_driver.get_credentials
.. js:autofunction:: test_driver.remove_credential
.. js:autofunction:: test_driver.remove_all_credentials
.. js:autofunction:: test_driver.set_user_verified

Page Lifecycle ###

.. js:autofunction:: test_driver.freeze

Reporting Observer ###

.. js:autofunction:: test_driver.generate_test_report

Storage ###

.. js:autofunction:: test_driver.set_storage_access

Accessibility ###

.. js:autofunction:: test_driver.get_computed_label
.. js:autofunction:: test_driver.get_computed_role

Secure Payment Confirmation ###

.. js:autofunction:: test_driver.set_spc_transaction_mode

Federated Credential Management ###

.. js:autofunction:: test_driver.cancel_fedcm_dialog
.. js:autofunction:: test_driver.click_fedcm_dialog_button
.. js:autofunction:: test_driver.select_fedcm_account
.. js:autofunction:: test_driver.get_fedcm_account_list
.. js:autofunction:: test_driver.get_fedcm_dialog_title
.. js:autofunction:: test_driver.get_fedcm_dialog_type
.. js:autofunction:: test_driver.set_fedcm_delay_enabled
.. js:autofunction:: test_driver.reset_fedcm_cooldown

Sensors ###

.. js:autofunction:: test_driver.create_virtual_sensor
.. js:autofunction:: test_driver.update_virtual_sensor
.. js:autofunction:: test_driver.remove_virtual_sensor
.. js:autofunction:: test_driver.get_virtual_sensor_information

Device Posture ###

.. js:autofunction:: test_driver.set_device_posture
.. js:autofunction:: test_driver.clear_device_posture

Bounce Tracking Mitigations ###

.. js:autofunction:: test_driver.run_bounce_tracking_mitigations

Compute Pressure ###

.. js:autofunction:: test_driver.create_virtual_pressure_source
.. js:autofunction:: test_driver.update_virtual_pressure_source
.. js:autofunction:: test_driver.remove_virtual_pressure_source

Viewport Segments ###

.. js:autofunction:: test_driver.set_display_features
.. js:autofunction:: test_driver.clear_display_features

Global Privacy Control ###

.. js:autofunction:: test_driver.set_global_privacy_control
.. js:autofunction:: test_driver.set_global_privacy_control

Using test_driver in other browsing contexts ###

Testdriver can be used in browsing contexts (i.e. windows or frames) from which it's possible to get a reference to the top-level test context. There are two basic approaches depending on whether the context in which testdriver is used is same-origin with the test context, or different origin.

For same-origin contexts, the context can be passed directly into the testdriver API calls. For functions that take an element argument this is done implicitly using the owner document of the element. For functions that don't take an element, this is done via an explicit context argument, which takes a WindowProxy object.

Example:

let win = window.open("example.html")
win.onload = () => {
  await test_driver.set_permission({ name: "background-fetch" }, "denied", win);
}

.. js:autofunction:: test_driver.set_test_context
.. js:autofunction:: test_driver.message_test

For cross-origin cases, passing in the context doesn't work because of limitations in the WebDriver protocol used to implement testdriver in a cross-browser fashion. Instead one may include the testdriver scripts directly in the relevant document, and use the `test_driver.set_test_context` API to specify the browsing context containing testharness.js. Commands are then sent via postMessage to the test context. For convenience there is also a `test_driver.message_test` function that can be used to send arbitrary messages to the test window. For example, in an auxillary browsing context:

test_driver.set_test_context(window.opener)
await test_driver.click(document.getElementsByTagName("button")[0])
test_driver.message_test("click complete")

The requirement to have a handle to the test window does mean it's currently not possible to write tests where such handles can't be obtained e.g. in the case of rel=noopener.

Actions ###

Markup ####

To use the Actions API testdriver-actions.js must be included in the document, in addition to testdriver.js:

<script src="/resources/testdriver-actions.js"></script>

API ####

.. js:autoclass:: Actions
   :members:

Using in other browsing contexts ####

For the actions API, the context can be set using the setContext method on the builder:

let actions = new test_driver.Actions()
    .setContext(frames[0])
    .keyDown("p")
    .keyUp("p");
await actions.send();

Note that if an action uses an element reference, the context will be derived from that element, and must match any explicitly set context. Using elements in multiple contexts in a single action chain is not supported.

Log

This module corresponds to the WebDriver BiDi Log module and provides access to browser logs.

Entry added

This provides methods to subscribe to and listen for the `log.entryAdded` event.

Example:

await test_driver.bidi.log.entry_added.subscribe();
const log_entry_promise = test_driver.bidi.log.entry_added.once();
console.log("some message");
const event = await log_entry_promise;

.. js:autofunction:: test_driver.bidi.log.entry_added.subscribe
.. js:autofunction:: test_driver.bidi.log.entry_added.on
.. js:autofunction:: test_driver.bidi.log.entry_added.once

Bluetooth ###

The module provides access to Web Bluetooth.

.. js:autofunction:: test_driver.bidi.bluetooth.handle_request_device_prompt
.. js:autofunction:: test_driver.bidi.bluetooth.simulate_adapter
.. js:autofunction:: test_driver.bidi.bluetooth.disable_simulation
.. js:autofunction:: test_driver.bidi.bluetooth.simulate_preconnected_peripheral
.. js:autofunction:: test_driver.bidi.bluetooth.simulate_gatt_connection_response
.. js:autofunction:: test_driver.bidi.bluetooth.simulate_gatt_disconnection
.. js:autofunction:: test_driver.bidi.bluetooth.simulate_service
.. js:autofunction:: test_driver.bidi.bluetooth.simulate_characteristic
.. js:autofunction:: test_driver.bidi.bluetooth.simulate_characteristic_response
.. js:autofunction:: test_driver.bidi.bluetooth.simulate_descriptor
.. js:autofunction:: test_driver.bidi.bluetooth.simulate_descriptor_response
.. js:autofunction:: test_driver.bidi.bluetooth.request_device_prompt_updated.subscribe
.. js:autofunction:: test_driver.bidi.bluetooth.request_device_prompt_updated.on
.. js:autofunction:: test_driver.bidi.bluetooth.request_device_prompt_updated.once
.. js:autofunction:: test_driver.bidi.bluetooth.gatt_connection_attempted.subscribe
.. js:autofunction:: test_driver.bidi.bluetooth.gatt_connection_attempted.on
.. js:autofunction:: test_driver.bidi.bluetooth.gatt_connection_attempted.once
.. js:autofunction:: test_driver.bidi.bluetooth.characteristic_event_generated.subscribe
.. js:autofunction:: test_driver.bidi.bluetooth.characteristic_event_generated.on
.. js:autofunction:: test_driver.bidi.bluetooth.characteristic_event_generated.once
.. js:autofunction:: test_driver.bidi.bluetooth.descriptor_event_generated.subscribe
.. js:autofunction:: test_driver.bidi.bluetooth.descriptor_event_generated.on
.. js:autofunction:: test_driver.bidi.bluetooth.descriptor_event_generated.once

Emulation ###

Emulation of browser APIs via WebDriver BiDi Emulation.

.. js:autofunction:: test_driver.bidi.emulation.set_geolocation_override
.. js:autofunction:: test_driver.bidi.emulation.set_locale_override
.. js:autofunction:: test_driver.bidi.emulation.set_screen_orientation_override