1 files changed, 235 insertions, 0 deletions
diff --git a/testing/web-platform/tests/docs/writing-tests/testdriver.md b/testing/web-platform/tests/docs/writing-tests/testdriver.md
new file mode 100644
index 0000000000..24159e82cc
--- /dev/null
+++ b/testing/web-platform/tests/docs/writing-tests/testdriver.md
@@ -0,0 +1,235 @@
+# testdriver.js Automation
+
+```eval_rst
+
+.. 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).
+
+It is currently supported only for [testharness.js](testharness)
+tests.
+
+## 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):
+
+```html
+<script src="/resources/testdriver.js"></script>
+<script src="/resources/testdriver-vendor.js"></script>
+```
+
+## API ##
+
+testdriver.js exposes its API through the `test_driver` variable in
+the global scope.
+
+### User Interaction ###
+
+```eval_rst
+.. js:autofunction:: test_driver.click
+.. js:autofunction:: test_driver.send_keys
+.. js:autofunction:: test_driver.action_sequence
+.. js:autofunction:: test_driver.bless
+```
+
+### Window State ###
+```eval_rst
+.. js:autofunction:: test_driver.minimize_window
+.. js:autofunction:: test_driver.set_window_rect
+```
+
+### Cookies ###
+```eval_rst
+.. js:autofunction:: test_driver.delete_all_cookies
+.. js:autofunction:: test_driver.get_all_cookies
+.. js:autofunction:: test_driver.get_named_cookie
+```
+
+### Permissions ###
+```eval_rst
+.. js:autofunction:: test_driver.set_permission
+```
+
+### Authentication ###
+
+```eval_rst
+.. 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 ###
+```eval_rst
+.. js:autofunction:: test_driver.freeze
+```
+
+### Reporting Observer ###
+```eval_rst
+.. js:autofunction:: test_driver.generate_test_report
+```
+
+### Storage ###
+```eval_rst
+.. js:autofunction:: test_driver.set_storage_access
+
+```
+
+### Accessibility ###
+```eval_rst
+.. js:autofunction:: test_driver.get_computed_label
+.. js:autofunction:: test_driver.get_computed_role
+
+```
+
+### Seure Payment Confirmation ###
+```eval_rst
+.. js:autofunction:: test_driver.set_spc_transaction_mode
+```
+
+### 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);
+}
+```
+
+```eval_rst
+.. 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`](#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`](#test_driver.message_test)
+function that can be used to send arbitary messages to the test
+window. For example, in an auxillary browsing context:
+
+```js
+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](#Actions) API `testdriver-actions.js` must be
+included in the document, in addition to `testdriver.js`:
+
+```html
+<script src="/resources/testdriver-actions.js"></script>
+```
+
+### API ###
+
+```eval_rst
+.. 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:
+
+```js
+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.
+
+### send_keys
+
+Usage: `test_driver.send_keys(element, keys)`
+ * _element_: a DOM Element object
+ * _keys_: string to send to the element
+
+This function causes the string _keys_ to be sent to the target
+element (an `Element` object), potentially scrolling the document to
+make it possible to send keys. It returns a promise that resolves
+after the keys have been sent, or rejects if the keys cannot be sent
+to the element.
+
+This works with elements in other frames/windows as long as they are
+same-origin with the test, and the test does not depend on the
+window.name property remaining unset on the target window.
+
+Note that if the element that the keys need to be sent to does not have
+a unique ID, the document must not have any DOM mutations made
+between the function being called and the promise settling.
+
+To send special keys, one must send the respective key's codepoint. Since this uses the WebDriver protocol, you can find a [list for code points to special keys in the spec](https://w3c.github.io/webdriver/#keyboard-actions).
+For example, to send the tab key you would send "\uE004".
+
+_Note: these special-key codepoints are not necessarily what you would expect. For example, <kbd>Esc</kbd> is the invalid Unicode character `\uE00C`, not the `\u001B` Escape character from ASCII._
+
+[activation]: https://html.spec.whatwg.org/multipage/interaction.html#activation
+
+### set_permission
+
+Usage: `test_driver.set_permission(descriptor, state, context=null)`
+ * _descriptor_: a
+   [PermissionDescriptor](https://w3c.github.io/permissions/#dictdef-permissiondescriptor)
+   or derived object
+ * _state_: a
+   [PermissionState](https://w3c.github.io/permissions/#enumdef-permissionstate)
+   value
+ * context: a WindowProxy for the browsing context in which to perform the call
+
+This function causes permission requests and queries for the status of a
+certain permission type (e.g. "push", or "background-fetch") to always
+return _state_. It returns a promise that resolves after the permission has
+been set to be overridden with _state_.
+
+Example:
+
+``` js
+await test_driver.set_permission({ name: "background-fetch" }, "denied");
+await test_driver.set_permission({ name: "push", userVisibleOnly: true }, "granted");
+```