feat(accessibility): snapshot the accessibility tree

docs/api.md

@@ -90,6 +90,7 @@
   * [page.$$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args)
   * [page.$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args-1)
   * [page.$x(expression)](#pagexexpression)
+  * [page.accessibility](#pageaccessibility)
   * [page.addScriptTag(options)](#pageaddscripttagoptions)
   * [page.addStyleTag(options)](#pageaddstyletagoptions)
   * [page.authenticate(credentials)](#pageauthenticatecredentials)
@@ -156,6 +157,8 @@
   * [worker.evaluateHandle(pageFunction, ...args)](#workerevaluatehandlepagefunction-args)
   * [worker.executionContext()](#workerexecutioncontext)
   * [worker.url()](#workerurl)
+- [class: Accessibility](#class-accessibility)
+  * [accessibility.snapshot([options])](#accessibilitysnapshotoptions)
 - [class: Keyboard](#class-keyboard)
   * [keyboard.down(key[, options])](#keyboarddownkey-options)
   * [keyboard.press(key[, options])](#keyboardpresskey-options)
@@ -1047,6 +1050,9 @@ The method evaluates the XPath expression.
 
 Shortcut for [page.mainFrame().$x(expression)](#framexexpression)
 
+#### page.accessibility
+- returns: <[Accessibility]>
+
 #### page.addScriptTag(options)
 - `options` <[Object]>
   - `url` <[string]> URL of a script to be added.
@@ -1982,6 +1988,79 @@ Shortcut for [(await worker.executionContext()).evaluateHandle(pageFunction, ...
 #### worker.url()
 - returns: <[string]>
 
+### class: Accessibility
+
+The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader).
+
+Accessibility is a very platform-specific thing. On different platforms, there are different screen readers that might have wildly different output.
+
+Blink - Chrome's rendering engine - has a concept of "accessibility tree", which is than translated into different platform-specific APIs. Accessibility namespace gives users
+access to the Blink Accessibility Tree.
+
+Most of the accessibility tree gets filtered out when converting from Blink AX Tree to Platform-specific AX-Tree or by screen readers themselves. By default, Puppeteer tries to approximate this filtering, exposing only the "interesting" nodes of the tree.
+
+
+
+#### accessibility.snapshot([options])
+- `options` <[Object]>
+  - `interestingOnly` <[boolean]> Prune uninteresting nodes from the tree. Defaults to `true`.
+- returns: <[Promise]<[AXNode]>> Returns an AXNode object with the following properties:
+  - `role` <[string]> The [role](https://www.w3.org/TR/wai-aria/#usage_intro).
+  - `name` <[string]> A human readable name for the node.
+  - `value` <[string]|[number]> The current value of the node.
+  - `description` <[string]> An additional human readable description of the node.
+  - `keyshortcuts` <[string]> Keyboard shortcuts associated with this node.
+  - `roledescription` <[string]> A human readable alternative to the role.
+  - `valuetext` <[string]> A description of the current value.
+  - `disabled` <[boolean]> Whether the node is disabled.
+  - `expanded` <[boolean]> Whether the node is expanded or collapsed.
+  - `focused` <[boolean]> Whether the node is focused.
+  - `modal` <[boolean]> Whether the node is [modal](https://en.wikipedia.org/wiki/Modal_window).
+  - `multiline` <[boolean]> Whether the node text input supports multiline.
+  - `multiselectable` <[boolean]> Whether more than one child can be selected.
+  - `readonly` <[boolean]> Whether the node is read only.
+  - `required` <[boolean]> Whether the node is required.
+  - `selected` <[boolean]> Whether the node is selected in its parent node.
+  - `checked` <[boolean]|[string]> Whether the checkbox is checked, or "mixed".
+  - `pressed` <[boolean]|[string]> Whether the toggle button is checked, or "mixed".
+  - `level` <[number]> The level of a heading.
+  - `valuemin` <[number]> The minimum value in a node.
+  - `valuemax` <[number]> The maximum value in a node.
+  - `autocomplete` <[string]> What kind of autocomplete is supported by a control.
+  - `haspopup` <[string]> What kind of popup is currently being shown for a node.
+  - `invalid` <[string]> Whether and in what way this node's value is invalid.
+  - `orientation` <[string]> Whether the node is oriented horizontally or vertically.
+  - `children` <[Array]<[AXNode]>> Child nodes of this node, if any.
+
+Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page.
+
+> **NOTE** The Chromium accessibility tree contains nodes that go unused on most platforms and by
+most screen readers. Puppeteer will discard them as well for an easier to process tree,
+unless `interestingOnly` is set to `false`.
+
+An example of dumping the entire accessibility tree:
+```js
+const snapshot = await page.accessibility.snapshot();
+console.log(snapshot);
+```
+
+An example of logging the focused node's name:
+```js
+const snapshot = await page.accessibility.snapshot();
+const node = findFocusedNode(snapshot);
+console.log(node && node.name);
+
+function findFocusedNode(node) {
+  if (node.focused)
+    return node;
+  for (const child of node.children || []) {
+    const foundNode = findFocusedNode(child);
+    return foundNode;
+  }
+  return null;
+}
+```
+
 ### class: Keyboard
 
 Keyboard provides an api for managing a virtual keyboard. The high level api is [`keyboard.type`](#keyboardtypetext-options), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.
@@ -3431,3 +3510,5 @@ TimeoutError is emitted whenever certain operations are terminated due to timeou
 [UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time"
 [SecurityDetails]: #class-securitydetails "SecurityDetails"
 [Worker]: #class-worker "Worker"
+[Accessibility]: #class-accessibility "Accessibility"
+[AXNode]: #accessibilitysnapshotoptions "AXNode"