Allow matcher to accept Axe results object

.changeset/wild-shrimps-mix.md

@@ -0,0 +1,5 @@
+---
+'expect-axe-playwright': minor
+---
+
+Allow matcher to accept Axe results object

README.md

@@ -73,6 +73,19 @@ Or pass a locator to test part of the page:
 await expect(page.locator('#my-element')).toBeAccessible()
 ```
 
+You can also pass an [Axe results
+object](https://www.deque.com/axe/core-documentation/api-documentation/#results-object)
+to the matcher:
+
+```js
+import { waitForAxeResults } from 'expect-axe-playwright'
+
+test('should be accessible', async ({ page }) => {
+  const { results } = await waitForAxeResults(page)
+  await expect(results).toBeAccessible()
+})
+```
+
 #### Axe run options
 
 You can configure options that should be passed to aXe at the project or

src/index.ts

@@ -1,2 +1,3 @@
 import matchers from './matchers'
+export { waitForAxeResults } from './waitForAxeResults'
 export default matchers

src/matchers/toBeAccessible/index.spec.ts

@@ -129,4 +129,16 @@ test.describe.parallel('toBeAccessible', () => {
       .catch(() => Promise.resolve())
     expect(attachmentExists(filename)).toBe(true)
   })
+
+  test.describe('with Axe results object', async () => {
+    test('positive', async () => {
+      const results = { violations: [] }
+      await expect(results).toBeAccessible()
+    })
+
+    test('negative', async () => {
+      const results = { violations: [{ id: 'foo', nodes: [] }] }
+      await expect(results).not.toBeAccessible()
+    })
+  })
 })

src/matchers/toBeAccessible/index.ts

@@ -1,44 +1,41 @@
 import test from '@playwright/test'
 import type { MatcherState } from '@playwright/test/types/expect-types'
-import type { Result, RunOptions } from 'axe-core'
+import type { AxeResults, Result } from 'axe-core'
+import type { MatcherOptions } from '../../types'
+import type { Handle } from '../../utils/locator'
 import createHTMLReport from 'axe-reporter-html'
 import merge from 'merge-deep'
 import { attach } from '../../utils/attachments'
-import { injectAxe, runAxe } from '../../utils/axe'
-import { Handle, resolveLocator } from '../../utils/matcher'
-import { poll } from '../../utils/poll'
+import { waitForAxeResults } from '../../waitForAxeResults'
 
 const summarize = (violations: Result[]) =>
   violations
     .map((violation) => `${violation.id}(${violation.nodes.length})`)
     .join(', ')
 
-interface MatcherOptions extends RunOptions {
-  timeout?: number
-  filename?: string
+async function getResults(obj: Handle | AxeResults, options: MatcherOptions) {
+  if ((obj as AxeResults).violations) {
+    const results = obj as AxeResults
+    return {
+      results,
+      ok: !results.violations.length,
+    }
+  } else {
+    return waitForAxeResults(obj as Handle, options)
+  }
 }
 
 export async function toBeAccessible(
   this: MatcherState,
-  handle: Handle,
-  { timeout, ...options }: MatcherOptions = {}
+  obj: Handle | AxeResults,
+  options: MatcherOptions = {}
 ) {
   try {
-    const locator = resolveLocator(handle)
-    await injectAxe(locator)
+    const { results, ok } = await getResults(obj, options)
 
     const info = test.info()
     const opts = merge(info.project.use.axeOptions, options)
 
-    const { ok, results } = await poll(locator, timeout, async () => {
-      const results = await runAxe(locator, opts)
-
-      return {
-        ok: !results.violations.length,
-        results,
-      }
-    })
-
     // If there are violations, attach an HTML report to the test for additional
     // visibility into the issue.
     if (!ok) {

src/types/index.ts

@@ -0,0 +1,6 @@
+import type { RunOptions } from 'axe-core'
+
+export interface MatcherOptions extends RunOptions {
+  timeout?: number
+  filename?: string
+}

src/waitForAxeResults.spec.ts

@@ -0,0 +1,21 @@
+import { expect, test } from '@playwright/test'
+import { readFile } from './utils/file'
+import { waitForAxeResults } from './waitForAxeResults'
+
+test.describe('waitForAxeResults', () => {
+  test('should be ok for page with no axe violations', async ({ page }) => {
+    const content = await readFile('accessible.html')
+    await page.setContent(content)
+    const { ok, results } = await waitForAxeResults(page)
+    expect(results.violations).toHaveLength(0)
+    expect(ok).toBe(true)
+  })
+
+  test('should not be ok for page with axe violations', async ({ page }) => {
+    const content = await readFile('inaccessible.html')
+    await page.setContent(content)
+    const { ok, results } = await waitForAxeResults(page)
+    expect(results.violations.length).toBeGreaterThan(0)
+    expect(ok).toBe(false)
+  })
+})

src/waitForAxeResults.ts

@@ -0,0 +1,28 @@
+import test from '@playwright/test'
+import type { AxeResults, RunOptions } from 'axe-core'
+import { Handle, resolveLocator } from './utils/locator'
+import merge from 'merge-deep'
+import { poll } from './utils/poll'
+import { injectAxe, runAxe } from './utils/axe'
+
+/**
+ * Injects axe onto page, waits for the page to be ready, then runs axe against
+ * the provided element handle (which could be the entire page).
+ */
+export async function waitForAxeResults(
+  handle: Handle,
+  { timeout, ...options }: { timeout?: number } & RunOptions = {}
+) {
+  const info = test.info()
+  const opts = merge(info.project.use.axeOptions, options)
+  const locator = resolveLocator(handle)
+  await injectAxe(locator)
+  return poll(locator, timeout, async () => {
+    const results = await runAxe(locator, opts)
+
+    return {
+      ok: !results.violations.length,
+      results,
+    }
+  })
+}