Allow passing a Page instead of an ElementHandle to getAccessibilityTree (#344)

Author: calebeby

.changeset/tall-spies-type.md

@@ -0,0 +1,7 @@
+---
+'pleasantest': minor
+---
+
+Allow passing `page` instead of an `ElementHandle` to `getAccessibilityTree`.
+
+If `page` is passed, the accessibility tree will be of the root `html` element.

README.md

@@ -34,7 +34,7 @@ Pleasantest is a library that allows you test web applications using real browse
   - [User API: `PleasantestUser`](#user-api-pleasantestuser)
   - [Utilities API: `PleasantestUtils`](#utilities-api-pleasantestutils)
   - [`jest-dom` Matchers](#jest-dom-matchers)
-  - [`getAccessibilityTree`](#getaccessibilitytreeelement-options-accessibilitytreeoptions--promiseaccessibilitytreesnapshot)
+  - [`getAccessibilityTree`](#getaccessibilitytreeelement-elementhandle--page-options-accessibilitytreeoptions--promiseaccessibilitytreesnapshot)
 - [Puppeteer Tips](#puppeteer-tips)
 - [Comparisons with other testing tools](#comparisons-with-other-testing-tools)
 - [Limitations](#limitationsarchitectural-decisions)
@@ -223,7 +223,7 @@ test(
 );
 ```
 
-Another option is to use the [`getAccessibilityTree`](#getaccessibilitytreeelement-options-accessibilitytreeoptions--promiseaccessibilitytreesnapshot) function to create snapshots of the expected accessibility tree.
+Another option is to use the [`getAccessibilityTree`](#getaccessibilitytreeelement-elementhandle--page-options-accessibilitytreeoptions--promiseaccessibilitytreesnapshot) function to create snapshots of the expected accessibility tree.
 
 ### Performing Actions
 
@@ -737,7 +737,7 @@ test(
 );
 ```
 
-### `getAccessibilityTree(element, options?: AccessibilityTreeOptions) => Promise<AccessibilityTreeSnapshot>`
+### `getAccessibilityTree(element: ElementHandle | Page, options?: AccessibilityTreeOptions) => Promise<AccessibilityTreeSnapshot>`
 
 The `getAccessibilityTree` function is a top-level import from `pleasantest`. It is intended to be used with [Jest Snapshots](https://jestjs.io/docs/snapshot-testing#snapshot-testing-with-jest) to ensure that any changes to the accessibility tree of your component or application are intended and correct.
 
@@ -753,12 +753,10 @@ test(
   withBrowser(async ({ page }) => {
     // ... Load your content here (see Loading Content)
 
-    const bodyElement = await page.evaluateHandle(() => document.body);
-    // You could alternatively choose a more specific element for which to print the accessibility tree
-
     await expect(
       // Note the use of `await`; getAccessibilityTree returns a Promise
-      await getAccessibilityTree(bodyElement),
+      // Also, you could pass a specific element instead of the page
+      await getAccessibilityTree(page),
     ).toMatchInlineSnapshot();
   }),
 );
@@ -776,6 +774,8 @@ list
     text "something else"
 ```
 
+The first parameter must be either an `ElementHandle` or the `Page` object. If an `ElementHandle` is passed, the accessibility tree will contain only descendants of that element. If the `Page` object is passed, the accessibility tree will be of the entire document.
+
 The second parameter (optional) is `AccessibilityTreeOptions`, and it allows you to configure what is shown in the output.
 
 `AccessibilityTreeOptions` (all properties are optional):

src/accessibility/index.ts

@@ -1,4 +1,4 @@
-import type { ElementHandle } from 'puppeteer';
+import type { ElementHandle, Page } from 'puppeteer';
 import { createClientRuntimeServer } from '../module-server/client-runtime-server';
 import { assertElementHandle } from '../utils';
 import type { AsyncHookTracker } from '../async-hooks';
@@ -21,11 +21,21 @@ export interface AccessibilityTreeOptions {
 }
 
 const getAccessibilityTree = async (
-  element: ElementHandle,
+  element: ElementHandle | Page,
   options: AccessibilityTreeOptions = {},
 ): Promise<
   { [accessibilityTreeSymbol]: string; toString(): string } | undefined
 > => {
+  if (
+    // eslint-disable-next-line @cloudfour/typescript-eslint/no-unnecessary-condition
+    element &&
+    typeof element === 'object' &&
+    element.constructor.name === 'Page'
+  ) {
+    element = await element.evaluateHandle<ElementHandle>(
+      () => document.documentElement,
+    );
+  }
   const serverPromise = createClientRuntimeServer();
   assertElementHandle(element, getAccessibilityTreeWrapper);
 
@@ -49,10 +59,10 @@ const getAccessibilityTree = async (
   };
 };
 
-/** Wrapped version adds forgot await checks */
-const getAccessibilityTreeWrapper = async (
-  ...args: Parameters<typeof getAccessibilityTree>
-): ReturnType<typeof getAccessibilityTree> => {
+// Wrapped version adds forgot await checks
+const getAccessibilityTreeWrapper: typeof getAccessibilityTree = async (
+  ...args
+) => {
   const asyncHookTracker: AsyncHookTracker | false =
     activeAsyncHookTrackers.size === 1 &&
     activeAsyncHookTrackers[Symbol.iterator]().next().value;