From 0b3d52a70ed5b39868b5b4cd8ddd8ce4318fbd31 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Fri, 5 Jun 2020 15:20:11 +0100 Subject: [PATCH] feat(new-docs): add TSDoc comments to `Accessibility` (#5971) * feat(new-docs): add tsdoc to `Accessibility` --- .../puppeteer.accessibility._constructor_.md | 20 --- new-docs/puppeteer.accessibility.md | 16 ++- new-docs/puppeteer.accessibility.snapshot.md | 48 ++++++- new-docs/puppeteer.md | 4 +- ...puppeteer.serializedaxnode.autocomplete.md | 11 ++ .../puppeteer.serializedaxnode.checked.md | 13 ++ .../puppeteer.serializedaxnode.children.md | 13 ++ .../puppeteer.serializedaxnode.description.md | 13 ++ .../puppeteer.serializedaxnode.disabled.md | 11 ++ .../puppeteer.serializedaxnode.expanded.md | 11 ++ .../puppeteer.serializedaxnode.focused.md | 11 ++ .../puppeteer.serializedaxnode.haspopup.md | 11 ++ .../puppeteer.serializedaxnode.invalid.md | 13 ++ ...puppeteer.serializedaxnode.keyshortcuts.md | 13 ++ new-docs/puppeteer.serializedaxnode.level.md | 13 ++ new-docs/puppeteer.serializedaxnode.md | 45 +++++++ new-docs/puppeteer.serializedaxnode.modal.md | 11 ++ .../puppeteer.serializedaxnode.multiline.md | 11 ++ ...peteer.serializedaxnode.multiselectable.md | 13 ++ new-docs/puppeteer.serializedaxnode.name.md | 13 ++ .../puppeteer.serializedaxnode.orientation.md | 11 ++ .../puppeteer.serializedaxnode.pressed.md | 13 ++ .../puppeteer.serializedaxnode.readonly.md | 11 ++ .../puppeteer.serializedaxnode.required.md | 11 ++ new-docs/puppeteer.serializedaxnode.role.md | 13 ++ ...peteer.serializedaxnode.roledescription.md | 13 ++ .../puppeteer.serializedaxnode.selected.md | 11 ++ new-docs/puppeteer.serializedaxnode.value.md | 13 ++ .../puppeteer.serializedaxnode.valuemax.md | 11 ++ .../puppeteer.serializedaxnode.valuemin.md | 11 ++ .../puppeteer.serializedaxnode.valuetext.md | 13 ++ ...ppeteer.snapshotoptions.interestingonly.md | 13 ++ new-docs/puppeteer.snapshotoptions.md | 20 +++ new-docs/puppeteer.snapshotoptions.root.md | 13 ++ src/Accessibility.ts | 126 +++++++++++++++++- utils/doclint/check_public_api/index.js | 7 + 36 files changed, 590 insertions(+), 34 deletions(-) delete mode 100644 new-docs/puppeteer.accessibility._constructor_.md create mode 100644 new-docs/puppeteer.serializedaxnode.autocomplete.md create mode 100644 new-docs/puppeteer.serializedaxnode.checked.md create mode 100644 new-docs/puppeteer.serializedaxnode.children.md create mode 100644 new-docs/puppeteer.serializedaxnode.description.md create mode 100644 new-docs/puppeteer.serializedaxnode.disabled.md create mode 100644 new-docs/puppeteer.serializedaxnode.expanded.md create mode 100644 new-docs/puppeteer.serializedaxnode.focused.md create mode 100644 new-docs/puppeteer.serializedaxnode.haspopup.md create mode 100644 new-docs/puppeteer.serializedaxnode.invalid.md create mode 100644 new-docs/puppeteer.serializedaxnode.keyshortcuts.md create mode 100644 new-docs/puppeteer.serializedaxnode.level.md create mode 100644 new-docs/puppeteer.serializedaxnode.md create mode 100644 new-docs/puppeteer.serializedaxnode.modal.md create mode 100644 new-docs/puppeteer.serializedaxnode.multiline.md create mode 100644 new-docs/puppeteer.serializedaxnode.multiselectable.md create mode 100644 new-docs/puppeteer.serializedaxnode.name.md create mode 100644 new-docs/puppeteer.serializedaxnode.orientation.md create mode 100644 new-docs/puppeteer.serializedaxnode.pressed.md create mode 100644 new-docs/puppeteer.serializedaxnode.readonly.md create mode 100644 new-docs/puppeteer.serializedaxnode.required.md create mode 100644 new-docs/puppeteer.serializedaxnode.role.md create mode 100644 new-docs/puppeteer.serializedaxnode.roledescription.md create mode 100644 new-docs/puppeteer.serializedaxnode.selected.md create mode 100644 new-docs/puppeteer.serializedaxnode.value.md create mode 100644 new-docs/puppeteer.serializedaxnode.valuemax.md create mode 100644 new-docs/puppeteer.serializedaxnode.valuemin.md create mode 100644 new-docs/puppeteer.serializedaxnode.valuetext.md create mode 100644 new-docs/puppeteer.snapshotoptions.interestingonly.md create mode 100644 new-docs/puppeteer.snapshotoptions.md create mode 100644 new-docs/puppeteer.snapshotoptions.root.md diff --git a/new-docs/puppeteer.accessibility._constructor_.md b/new-docs/puppeteer.accessibility._constructor_.md deleted file mode 100644 index 2ad712d6..00000000 --- a/new-docs/puppeteer.accessibility._constructor_.md +++ /dev/null @@ -1,20 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Accessibility](./puppeteer.accessibility.md) > [(constructor)](./puppeteer.accessibility._constructor_.md) - -## Accessibility.(constructor) - -Constructs a new instance of the `Accessibility` class - -Signature: - -```typescript -constructor(client: CDPSession); -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| client | [CDPSession](./puppeteer.cdpsession.md) | | - diff --git a/new-docs/puppeteer.accessibility.md b/new-docs/puppeteer.accessibility.md index 2d405b15..3f8b4b90 100644 --- a/new-docs/puppeteer.accessibility.md +++ b/new-docs/puppeteer.accessibility.md @@ -4,21 +4,27 @@ ## Accessibility class +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) or [switches](https://en.wikipedia.org/wiki/Switch_access). + Signature: ```typescript export declare class Accessibility ``` -## Constructors +## Remarks -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(client)](./puppeteer.accessibility._constructor_.md) | | Constructs a new instance of the Accessibility class | +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 then 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 assistive technologies themselves. By default, Puppeteer tries to approximate this filtering, exposing only the "interesting" nodes of the tree. + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Accessibility` class. ## Methods | Method | Modifiers | Description | | --- | --- | --- | -| [snapshot(options)](./puppeteer.accessibility.snapshot.md) | | | +| [snapshot(options)](./puppeteer.accessibility.snapshot.md) | | Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page. | diff --git a/new-docs/puppeteer.accessibility.snapshot.md b/new-docs/puppeteer.accessibility.snapshot.md index a00d01db..736733a5 100644 --- a/new-docs/puppeteer.accessibility.snapshot.md +++ b/new-docs/puppeteer.accessibility.snapshot.md @@ -4,22 +4,58 @@ ## Accessibility.snapshot() method +Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page. + Signature: ```typescript -snapshot(options?: { - interestingOnly?: boolean; - root?: ElementHandle; - }): Promise; +snapshot(options?: SnapshotOptions): Promise; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| options | { interestingOnly?: boolean; root?: [ElementHandle](./puppeteer.elementhandle.md); } | | +| options | [SnapshotOptions](./puppeteer.snapshotoptions.md) | | Returns: -Promise<SerializedAXNode> +Promise<[SerializedAXNode](./puppeteer.serializedaxnode.md)> + +An AXNode object represeting the snapshot. + +## Remarks + +\*\*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`. + +## Example 1 + +An example of dumping the entire accessibility tree: + +```js +const snapshot = await page.accessibility.snapshot(); +console.log(snapshot); + +``` + +## Example 2 + +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; +} + +``` diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index 332fb055..30b9b751 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -8,7 +8,7 @@ | Class | Description | | --- | --- | -| [Accessibility](./puppeteer.accessibility.md) | | +| [Accessibility](./puppeteer.accessibility.md) | 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) or [switches](https://en.wikipedia.org/wiki/Switch_access). | | [Browser](./puppeteer.browser.md) | | | [BrowserContext](./puppeteer.browsercontext.md) | | | [BrowserFetcher](./puppeteer.browserfetcher.md) | | @@ -53,6 +53,8 @@ | Interface | Description | | --- | --- | | [BrowserFetcherOptions](./puppeteer.browserfetcheroptions.md) | | +| [SerializedAXNode](./puppeteer.serializedaxnode.md) | Represents a Node and the properties of it that are relevant to Accessibility. | +| [SnapshotOptions](./puppeteer.snapshotoptions.md) | | ## Variables diff --git a/new-docs/puppeteer.serializedaxnode.autocomplete.md b/new-docs/puppeteer.serializedaxnode.autocomplete.md new file mode 100644 index 00000000..86565a31 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.autocomplete.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [autocomplete](./puppeteer.serializedaxnode.autocomplete.md) + +## SerializedAXNode.autocomplete property + +Signature: + +```typescript +autocomplete?: string; +``` diff --git a/new-docs/puppeteer.serializedaxnode.checked.md b/new-docs/puppeteer.serializedaxnode.checked.md new file mode 100644 index 00000000..63cb4177 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.checked.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [checked](./puppeteer.serializedaxnode.checked.md) + +## SerializedAXNode.checked property + +Whether the checkbox is checked, or in a [mixed state](https://www.w3.org/TR/wai-aria-practices/examples/checkbox/checkbox-2/checkbox-2.html). + +Signature: + +```typescript +checked?: boolean | 'mixed'; +``` diff --git a/new-docs/puppeteer.serializedaxnode.children.md b/new-docs/puppeteer.serializedaxnode.children.md new file mode 100644 index 00000000..cb3d6c27 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.children.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [children](./puppeteer.serializedaxnode.children.md) + +## SerializedAXNode.children property + +Children of this node, if there are any. + +Signature: + +```typescript +children?: SerializedAXNode[]; +``` diff --git a/new-docs/puppeteer.serializedaxnode.description.md b/new-docs/puppeteer.serializedaxnode.description.md new file mode 100644 index 00000000..1bb34720 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.description.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [description](./puppeteer.serializedaxnode.description.md) + +## SerializedAXNode.description property + +An additional human readable description of the node. + +Signature: + +```typescript +description?: string; +``` diff --git a/new-docs/puppeteer.serializedaxnode.disabled.md b/new-docs/puppeteer.serializedaxnode.disabled.md new file mode 100644 index 00000000..884f09a1 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.disabled.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [disabled](./puppeteer.serializedaxnode.disabled.md) + +## SerializedAXNode.disabled property + +Signature: + +```typescript +disabled?: boolean; +``` diff --git a/new-docs/puppeteer.serializedaxnode.expanded.md b/new-docs/puppeteer.serializedaxnode.expanded.md new file mode 100644 index 00000000..c975c5df --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.expanded.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [expanded](./puppeteer.serializedaxnode.expanded.md) + +## SerializedAXNode.expanded property + +Signature: + +```typescript +expanded?: boolean; +``` diff --git a/new-docs/puppeteer.serializedaxnode.focused.md b/new-docs/puppeteer.serializedaxnode.focused.md new file mode 100644 index 00000000..491fc306 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.focused.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [focused](./puppeteer.serializedaxnode.focused.md) + +## SerializedAXNode.focused property + +Signature: + +```typescript +focused?: boolean; +``` diff --git a/new-docs/puppeteer.serializedaxnode.haspopup.md b/new-docs/puppeteer.serializedaxnode.haspopup.md new file mode 100644 index 00000000..489b1703 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.haspopup.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [haspopup](./puppeteer.serializedaxnode.haspopup.md) + +## SerializedAXNode.haspopup property + +Signature: + +```typescript +haspopup?: string; +``` diff --git a/new-docs/puppeteer.serializedaxnode.invalid.md b/new-docs/puppeteer.serializedaxnode.invalid.md new file mode 100644 index 00000000..a6516cff --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.invalid.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [invalid](./puppeteer.serializedaxnode.invalid.md) + +## SerializedAXNode.invalid property + +Whether and in what way this node's value is invalid. + +Signature: + +```typescript +invalid?: string; +``` diff --git a/new-docs/puppeteer.serializedaxnode.keyshortcuts.md b/new-docs/puppeteer.serializedaxnode.keyshortcuts.md new file mode 100644 index 00000000..d4de7990 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.keyshortcuts.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [keyshortcuts](./puppeteer.serializedaxnode.keyshortcuts.md) + +## SerializedAXNode.keyshortcuts property + +Any keyboard shortcuts associated with this node. + +Signature: + +```typescript +keyshortcuts?: string; +``` diff --git a/new-docs/puppeteer.serializedaxnode.level.md b/new-docs/puppeteer.serializedaxnode.level.md new file mode 100644 index 00000000..227a3c43 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.level.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [level](./puppeteer.serializedaxnode.level.md) + +## SerializedAXNode.level property + +The level of a heading. + +Signature: + +```typescript +level?: number; +``` diff --git a/new-docs/puppeteer.serializedaxnode.md b/new-docs/puppeteer.serializedaxnode.md new file mode 100644 index 00000000..bd9c23c0 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.md @@ -0,0 +1,45 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) + +## SerializedAXNode interface + +Represents a Node and the properties of it that are relevant to Accessibility. + +Signature: + +```typescript +export interface SerializedAXNode +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [autocomplete](./puppeteer.serializedaxnode.autocomplete.md) | string | | +| [checked](./puppeteer.serializedaxnode.checked.md) | boolean \| 'mixed' | Whether the checkbox is checked, or in a [mixed state](https://www.w3.org/TR/wai-aria-practices/examples/checkbox/checkbox-2/checkbox-2.html). | +| [children](./puppeteer.serializedaxnode.children.md) | [SerializedAXNode](./puppeteer.serializedaxnode.md)\[\] | Children of this node, if there are any. | +| [description](./puppeteer.serializedaxnode.description.md) | string | An additional human readable description of the node. | +| [disabled](./puppeteer.serializedaxnode.disabled.md) | boolean | | +| [expanded](./puppeteer.serializedaxnode.expanded.md) | boolean | | +| [focused](./puppeteer.serializedaxnode.focused.md) | boolean | | +| [haspopup](./puppeteer.serializedaxnode.haspopup.md) | string | | +| [invalid](./puppeteer.serializedaxnode.invalid.md) | string | Whether and in what way this node's value is invalid. | +| [keyshortcuts](./puppeteer.serializedaxnode.keyshortcuts.md) | string | Any keyboard shortcuts associated with this node. | +| [level](./puppeteer.serializedaxnode.level.md) | number | The level of a heading. | +| [modal](./puppeteer.serializedaxnode.modal.md) | boolean | | +| [multiline](./puppeteer.serializedaxnode.multiline.md) | boolean | | +| [multiselectable](./puppeteer.serializedaxnode.multiselectable.md) | boolean | Whether more than one child can be selected. | +| [name](./puppeteer.serializedaxnode.name.md) | string | A human readable name for the node. | +| [orientation](./puppeteer.serializedaxnode.orientation.md) | string | | +| [pressed](./puppeteer.serializedaxnode.pressed.md) | boolean \| 'mixed' | Whether the node is checked or in a mixed state. | +| [readonly](./puppeteer.serializedaxnode.readonly.md) | boolean | | +| [required](./puppeteer.serializedaxnode.required.md) | boolean | | +| [role](./puppeteer.serializedaxnode.role.md) | string | The [role](https://www.w3.org/TR/wai-aria/#usage_intro) of the node. | +| [roledescription](./puppeteer.serializedaxnode.roledescription.md) | string | A human readable alternative to the role. | +| [selected](./puppeteer.serializedaxnode.selected.md) | boolean | | +| [value](./puppeteer.serializedaxnode.value.md) | string \| number | The current value of the node. | +| [valuemax](./puppeteer.serializedaxnode.valuemax.md) | number | | +| [valuemin](./puppeteer.serializedaxnode.valuemin.md) | number | | +| [valuetext](./puppeteer.serializedaxnode.valuetext.md) | string | A description of the current value. | + diff --git a/new-docs/puppeteer.serializedaxnode.modal.md b/new-docs/puppeteer.serializedaxnode.modal.md new file mode 100644 index 00000000..b69c65c6 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.modal.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [modal](./puppeteer.serializedaxnode.modal.md) + +## SerializedAXNode.modal property + +Signature: + +```typescript +modal?: boolean; +``` diff --git a/new-docs/puppeteer.serializedaxnode.multiline.md b/new-docs/puppeteer.serializedaxnode.multiline.md new file mode 100644 index 00000000..f74bdb3d --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.multiline.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [multiline](./puppeteer.serializedaxnode.multiline.md) + +## SerializedAXNode.multiline property + +Signature: + +```typescript +multiline?: boolean; +``` diff --git a/new-docs/puppeteer.serializedaxnode.multiselectable.md b/new-docs/puppeteer.serializedaxnode.multiselectable.md new file mode 100644 index 00000000..ff1bbf29 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.multiselectable.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [multiselectable](./puppeteer.serializedaxnode.multiselectable.md) + +## SerializedAXNode.multiselectable property + +Whether more than one child can be selected. + +Signature: + +```typescript +multiselectable?: boolean; +``` diff --git a/new-docs/puppeteer.serializedaxnode.name.md b/new-docs/puppeteer.serializedaxnode.name.md new file mode 100644 index 00000000..2345d7e1 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.name.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [name](./puppeteer.serializedaxnode.name.md) + +## SerializedAXNode.name property + +A human readable name for the node. + +Signature: + +```typescript +name?: string; +``` diff --git a/new-docs/puppeteer.serializedaxnode.orientation.md b/new-docs/puppeteer.serializedaxnode.orientation.md new file mode 100644 index 00000000..5ac78cd0 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.orientation.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [orientation](./puppeteer.serializedaxnode.orientation.md) + +## SerializedAXNode.orientation property + +Signature: + +```typescript +orientation?: string; +``` diff --git a/new-docs/puppeteer.serializedaxnode.pressed.md b/new-docs/puppeteer.serializedaxnode.pressed.md new file mode 100644 index 00000000..1ae8af0c --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.pressed.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [pressed](./puppeteer.serializedaxnode.pressed.md) + +## SerializedAXNode.pressed property + +Whether the node is checked or in a mixed state. + +Signature: + +```typescript +pressed?: boolean | 'mixed'; +``` diff --git a/new-docs/puppeteer.serializedaxnode.readonly.md b/new-docs/puppeteer.serializedaxnode.readonly.md new file mode 100644 index 00000000..b0a6c1c4 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.readonly.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [readonly](./puppeteer.serializedaxnode.readonly.md) + +## SerializedAXNode.readonly property + +Signature: + +```typescript +readonly?: boolean; +``` diff --git a/new-docs/puppeteer.serializedaxnode.required.md b/new-docs/puppeteer.serializedaxnode.required.md new file mode 100644 index 00000000..f0f1434c --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.required.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [required](./puppeteer.serializedaxnode.required.md) + +## SerializedAXNode.required property + +Signature: + +```typescript +required?: boolean; +``` diff --git a/new-docs/puppeteer.serializedaxnode.role.md b/new-docs/puppeteer.serializedaxnode.role.md new file mode 100644 index 00000000..dc68b637 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.role.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [role](./puppeteer.serializedaxnode.role.md) + +## SerializedAXNode.role property + +The [role](https://www.w3.org/TR/wai-aria/#usage_intro) of the node. + +Signature: + +```typescript +role: string; +``` diff --git a/new-docs/puppeteer.serializedaxnode.roledescription.md b/new-docs/puppeteer.serializedaxnode.roledescription.md new file mode 100644 index 00000000..8092ad93 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.roledescription.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [roledescription](./puppeteer.serializedaxnode.roledescription.md) + +## SerializedAXNode.roledescription property + +A human readable alternative to the role. + +Signature: + +```typescript +roledescription?: string; +``` diff --git a/new-docs/puppeteer.serializedaxnode.selected.md b/new-docs/puppeteer.serializedaxnode.selected.md new file mode 100644 index 00000000..4ceae057 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.selected.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [selected](./puppeteer.serializedaxnode.selected.md) + +## SerializedAXNode.selected property + +Signature: + +```typescript +selected?: boolean; +``` diff --git a/new-docs/puppeteer.serializedaxnode.value.md b/new-docs/puppeteer.serializedaxnode.value.md new file mode 100644 index 00000000..0c29a7d7 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.value.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [value](./puppeteer.serializedaxnode.value.md) + +## SerializedAXNode.value property + +The current value of the node. + +Signature: + +```typescript +value?: string | number; +``` diff --git a/new-docs/puppeteer.serializedaxnode.valuemax.md b/new-docs/puppeteer.serializedaxnode.valuemax.md new file mode 100644 index 00000000..4ce2ef70 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.valuemax.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [valuemax](./puppeteer.serializedaxnode.valuemax.md) + +## SerializedAXNode.valuemax property + +Signature: + +```typescript +valuemax?: number; +``` diff --git a/new-docs/puppeteer.serializedaxnode.valuemin.md b/new-docs/puppeteer.serializedaxnode.valuemin.md new file mode 100644 index 00000000..effc2237 --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.valuemin.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [valuemin](./puppeteer.serializedaxnode.valuemin.md) + +## SerializedAXNode.valuemin property + +Signature: + +```typescript +valuemin?: number; +``` diff --git a/new-docs/puppeteer.serializedaxnode.valuetext.md b/new-docs/puppeteer.serializedaxnode.valuetext.md new file mode 100644 index 00000000..bb377e0f --- /dev/null +++ b/new-docs/puppeteer.serializedaxnode.valuetext.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SerializedAXNode](./puppeteer.serializedaxnode.md) > [valuetext](./puppeteer.serializedaxnode.valuetext.md) + +## SerializedAXNode.valuetext property + +A description of the current value. + +Signature: + +```typescript +valuetext?: string; +``` diff --git a/new-docs/puppeteer.snapshotoptions.interestingonly.md b/new-docs/puppeteer.snapshotoptions.interestingonly.md new file mode 100644 index 00000000..38fdd689 --- /dev/null +++ b/new-docs/puppeteer.snapshotoptions.interestingonly.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SnapshotOptions](./puppeteer.snapshotoptions.md) > [interestingOnly](./puppeteer.snapshotoptions.interestingonly.md) + +## SnapshotOptions.interestingOnly property + +Prune unintersting nodes from the tree. + +Signature: + +```typescript +interestingOnly?: boolean; +``` diff --git a/new-docs/puppeteer.snapshotoptions.md b/new-docs/puppeteer.snapshotoptions.md new file mode 100644 index 00000000..6b652841 --- /dev/null +++ b/new-docs/puppeteer.snapshotoptions.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SnapshotOptions](./puppeteer.snapshotoptions.md) + +## SnapshotOptions interface + + +Signature: + +```typescript +export interface SnapshotOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [interestingOnly](./puppeteer.snapshotoptions.interestingonly.md) | boolean | Prune unintersting nodes from the tree. | +| [root](./puppeteer.snapshotoptions.root.md) | [ElementHandle](./puppeteer.elementhandle.md) | Prune unintersting nodes from the tree. | + diff --git a/new-docs/puppeteer.snapshotoptions.root.md b/new-docs/puppeteer.snapshotoptions.root.md new file mode 100644 index 00000000..e7824b9f --- /dev/null +++ b/new-docs/puppeteer.snapshotoptions.root.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [SnapshotOptions](./puppeteer.snapshotoptions.md) > [root](./puppeteer.snapshotoptions.root.md) + +## SnapshotOptions.root property + +Prune unintersting nodes from the tree. + +Signature: + +```typescript +root?: ElementHandle; +``` diff --git a/src/Accessibility.ts b/src/Accessibility.ts index 5db521d6..2746119f 100644 --- a/src/Accessibility.ts +++ b/src/Accessibility.ts @@ -18,44 +18,166 @@ import { CDPSession } from './Connection'; import { ElementHandle } from './JSHandle'; import Protocol from './protocol'; -interface SerializedAXNode { +/** + * Represents a Node and the properties of it that are relevant to Accessibility. + * @public + */ +export interface SerializedAXNode { + /** + * The {@link https://www.w3.org/TR/wai-aria/#usage_intro | role} of the node. + */ role: string; + /** + * A human readable name for the node. + */ name?: string; + /** + * The current value of the node. + */ value?: string | number; + /** + * An additional human readable description of the node. + */ description?: string; + /** + * Any keyboard shortcuts associated with this node. + */ keyshortcuts?: string; + /** + * A human readable alternative to the role. + */ roledescription?: string; + /** + * A description of the current value. + */ valuetext?: string; disabled?: boolean; expanded?: boolean; focused?: boolean; modal?: boolean; multiline?: boolean; + /** + * Whether more than one child can be selected. + */ multiselectable?: boolean; readonly?: boolean; required?: boolean; selected?: boolean; + /** + * Whether the checkbox is checked, or in a {@link https://www.w3.org/TR/wai-aria-practices/examples/checkbox/checkbox-2/checkbox-2.html | mixed state}. + */ checked?: boolean | 'mixed'; + /** + * Whether the node is checked or in a mixed state. + */ pressed?: boolean | 'mixed'; + /** + * The level of a heading. + */ level?: number; valuemin?: number; valuemax?: number; autocomplete?: string; haspopup?: string; + /** + * Whether and in what way this node's value is invalid. + */ invalid?: string; orientation?: string; + /** + * Children of this node, if there are any. + */ children?: SerializedAXNode[]; } +/** + * @public + */ +export interface SnapshotOptions { + /** + * Prune unintersting nodes from the tree. + * @defaultValue true + */ + interestingOnly?: boolean; + /** + * Prune unintersting nodes from the tree. + * @defaultValue The root node of the entire page. + */ + root?: ElementHandle; +} + +/** + * The Accessibility class provides methods for inspecting Chromium's + * accessibility tree. The accessibility tree is used by assistive technology + * such as {@link https://en.wikipedia.org/wiki/Screen_reader | screen readers} or + * {@link https://en.wikipedia.org/wiki/Switch_access | switches}. + * + * @remarks + * + * 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 then 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 assistive technologies themselves. + * By default, Puppeteer tries to approximate this filtering, exposing only + * the "interesting" nodes of the tree. + * + * @public + */ export class Accessibility { private _client: CDPSession; + /** + * @internal + */ constructor(client: CDPSession) { this._client = client; } + /** + * Captures the current state of the accessibility tree. + * The returned object represents the root accessible node of the page. + * + * @remarks + * + * **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`. + * + * @example + * An example of dumping the entire accessibility tree: + * ```js + * const snapshot = await page.accessibility.snapshot(); + * console.log(snapshot); + * ``` + * + * @example + * 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; + * } + * ``` + * + * @returns An AXNode object represeting the snapshot. + * + */ public async snapshot( - options: { interestingOnly?: boolean; root?: ElementHandle } = {} + options: SnapshotOptions = {} ): Promise { const { interestingOnly = true, root = null } = options; const { nodes } = await this._client.send('Accessibility.getFullAXTree'); diff --git a/utils/doclint/check_public_api/index.js b/utils/doclint/check_public_api/index.js index 2e401cfa..2c5ff56e 100644 --- a/utils/doclint/check_public_api/index.js +++ b/utils/doclint/check_public_api/index.js @@ -612,6 +612,13 @@ function compareDocumentations(actual, expected) { expectedName: 'VisionDeficiency', }, ], + [ + 'Method Accessibility.snapshot() options', + { + actualName: 'Object', + expectedName: 'SnapshotOptions', + }, + ], ]); const expectedForSource = expectedNamingMismatches.get(source);