Bug 1510910 [wpt PR 14287] - Add actions builder API documentation, a=testonly
authorNavid Zolghadr <nzolghadr@chromium.org>
Thu, 13 Dec 2018 13:54:49 +0000
changeset 450613 ed532e0e19f8277197e0558c4413ae32db7e9148
parent 450612 9abc886d278287bdde769e9ff4a783259abb75fc
child 450614 212030474731023991adac8f38c20843ad3fd150
push id35208
push usercsabou@mozilla.com
push dateSat, 15 Dec 2018 02:48:07 +0000
treeherdermozilla-central@d86d184dc7d6 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerstestonly
bugs1510910, 14287
milestone66.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1510910 [wpt PR 14287] - Add actions builder API documentation, a=testonly Automatic update from web-platform-tests Add actions builder API documentation Add actions builder API documentation plus some examples -- Remove trailing space and add a "the" -- wpt-commits: 07e35f356cc4a6b2a27a0d9f2a14968d5ee7330a, d67fec6063da225ec5da00db820a401783922264 wpt-pr: 14287
testing/web-platform/tests/docs/_writing-tests/testdriver.md
--- a/testing/web-platform/tests/docs/_writing-tests/testdriver.md
+++ b/testing/web-platform/tests/docs/_writing-tests/testdriver.md
@@ -21,16 +21,51 @@ context (and not therefore in any frame 
 ### action_sequence
 Usage: `test_driver.action_sequence(actions)`
  * `actions`: an array of `Action` objects
 
 This function causes a sequence of actions to be sent to the browser. It is based of the [WebDriver API](https://w3c.github.io/webdriver/#actions).
 The action can be a keyboard action, a pointer action or a pause. It returns a `Promise` that
 resolves after the actions have been sent or rejects if an error was thrown.
 
+Test authors are encouraged to use the builder API to generate the sequence of actions. The builder
+API can be accessed via the `new test_driver.Actions()` object.
+
+Example:
+
+```js
+let text_box = document.getElementById("text");
+
+let actions = new test_driver.Actions()
+    .pointerMove(0, 0, {origin: text_box})
+    .pointerDown()
+    .pointerUp()
+    .addTick()
+    .keyDown("p")
+    .keyUp("p");
+
+actions.send();
+```
+
+Calling into `send()` is going to dispatch the action sequence (via `test_driver.action_sequence`) and also returns a `Promise` which should be handled however is appropriate in the test. The other functions in the `Actions()` object are going to modify the state of the object by adding a new action in the sequence and return the same object. So the functions can be easily chained as shown in the example above. Here is a list of helper functions in the `Actions` class:
+
+```
+pointerDown: Create a pointerDown event for the current default pointer source
+pointerUp: Create a pointerUp event for the current default pointer source
+pointerMove: Create a move event for the current default pointer source
+keyDown: Create a keyDown event for the current default key source
+keyUp: Create a keyUp event for the current default key source
+pause: Add a pause to the current tick
+addTick: Insert a new actions tick
+setPointer: Set the current default pointer source (By detault the pointerType is mouse)
+addPointer: Add a new pointer input source with the given name
+setKeyboard: Set the current default key source
+addKeyboard: Add a new key input source with the given name
+```
+
 ### bless
 
 Usage: `test_driver.bless(intent, action)`
  * `intent`: a string describing the motivation for this invocation
  * `action`: an optional function
 
 This function simulates [activation][activation], allowing tests to
 perform privileged operations that require user interaction. For