feat: Initial release

Mark Skelton · Mark Skelton · commit e70fd0494fd5 · 2021-07-08T17:13:28.000-05:00
diff --git a/.eslintrc b/.eslintrc
@@ -1,8 +1,11 @@
 {
   "parser": "@typescript-eslint/parser",
-  "plugins": ["@typescript-eslint"],
   "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
   "env": {
     "node": true
+  },
+  "rules": {
+    "@typescript-eslint/no-non-null-assertion": "off",
+    "@typescript-eslint/explicit-module-boundary-types": "off"
   }
 }
diff --git a/index.d.ts b/index.d.ts
@@ -1,5 +1,6 @@
 interface AxePlaywrightMatchers<R> {
   toBeAccessible(): Promise<R>
+  toBeAccessible(selector: string): Promise<R>
 }
 
 declare global {
diff --git a/playwright.config.ts b/playwright.config.ts
@@ -4,5 +4,6 @@ import { matchers } from './src'
 expect.extend(matchers)
 
 export default {
+  globalSetup: require.resolve('./src/config/globalSetup'),
   testDir: 'src',
 } as PlaywrightTestConfig
diff --git a/src/config/globalSetup.ts b/src/config/globalSetup.ts
@@ -0,0 +1,26 @@
+import http from 'http'
+import type { AddressInfo } from 'net'
+import { readFile } from '../utils/file'
+
+function listener(req: http.IncomingMessage, res: http.ServerResponse) {
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const file = req.url!.replace('/', '')
+
+  readFile(file).then((html) => {
+    res.writeHead(200)
+    res.end(html)
+  })
+}
+
+export default async function globalSetup() {
+  const server = http.createServer(listener)
+  await new Promise((done) => server.listen(done))
+
+  // Expose port to the tests
+  const address = server.address() as AddressInfo
+  process.env.SERVER_PORT = String(address.port)
+
+  return async () => {
+    await new Promise((done) => server.close(done))
+  }
+}
diff --git a/src/config/templates/accessible.html b/src/config/templates/accessible.html
@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Foo</title>
+  </head>
+  <body>
+    <main>
+      <h1>Bar</h1>
+    </main>
+  </body>
+</html>
diff --git a/src/config/templates/inaccessible.html b/src/config/templates/inaccessible.html
@@ -0,0 +1,7 @@
+<!DOCTYPE html>
+<html>
+  <head> </head>
+  <body>
+    <h1>Bar</h1>
+  </body>
+</html>
diff --git a/src/matchers/__tests__/toBeAccessible.spec.ts b/src/matchers/__tests__/toBeAccessible.spec.ts
diff --git a/src/matchers/toBeAccessible.ts b/src/matchers/toBeAccessible.ts
diff --git a/src/matchers/toBeAccessible/index.spec.ts b/src/matchers/toBeAccessible/index.spec.ts
@@ -0,0 +1,80 @@
+import { expect, test } from '@playwright/test'
+import { readFile } from '../../utils/file'
+
+test.describe('toBeAccessible', () => {
+  test.describe('page', () => {
+    test('positive', async ({ page }) => {
+      const content = await readFile('accessible.html')
+      await page.setContent(content)
+      await expect(page).toBeAccessible()
+    })
+
+    test('negative', async ({ page }) => {
+      test.fail()
+      const content = await readFile('inaccessible.html')
+      await page.setContent(content)
+      await expect(page).toBeAccessible()
+    })
+  })
+
+  test.describe('selector', () => {
+    test('positive', async ({ page }) => {
+      await page.setContent('<button id="foo">Hello</button>')
+      await expect(page).toBeAccessible('#foo')
+    })
+
+    test('negative', async ({ page }) => {
+      test.fail()
+      await page.setContent('<button id="foo"></button>')
+      await expect(page).toBeAccessible('#foo')
+    })
+  })
+
+  test.describe('element', () => {
+    test('positive', async ({ page }) => {
+      await page.setContent('<button id="foo">Hello</button>')
+      const button = page.$('#foo')
+
+      await expect(button).toBeAccessible()
+      await expect(await button).toBeAccessible()
+    })
+
+    test('negative', async ({ page }) => {
+      test.fail()
+      await page.setContent('<button id="foo"></button>')
+      const button = page.$('#foo')
+
+      await expect(button).toBeAccessible()
+      await expect(await button).toBeAccessible()
+    })
+  })
+
+  test.describe('iframe', () => {
+    test('positive', async ({ page }) => {
+      const content = `<iframe src="http://localhost:${process.env.SERVER_PORT}/accessible.html">`
+      await page.setContent(content)
+
+      const handle = page.$('iframe')
+      await expect(handle).toBeAccessible()
+      await expect(await handle).toBeAccessible()
+
+      const iframe = (await handle)?.contentFrame()
+      await expect(iframe).toBeAccessible()
+      await expect(await iframe).toBeAccessible()
+    })
+
+    test('negative', async ({ page }) => {
+      test.fail()
+      const content = `<iframe src="http://localhost:${process.env.SERVER_PORT}/inaccessible.html">`
+      await page.setContent(content)
+
+      const handle = page.$('iframe')
+      await expect(handle).toBeAccessible()
+      await expect(await handle).toBeAccessible()
+
+      const iframe = (await handle)?.contentFrame()
+      await expect(iframe).toBeAccessible()
+      await expect(await iframe).toBeAccessible()
+    })
+  })
+})
diff --git a/src/matchers/toBeAccessible/index.ts b/src/matchers/toBeAccessible/index.ts
@@ -0,0 +1,41 @@
+import type { Result } from 'axe-core'
+import type { MatcherState, SyncExpectationResult } from 'expect/build/types'
+import { injectAxe, runAxe } from '../../utils/axe'
+import { getElementHandle, InputArguments } from '../../utils/matcher'
+
+const collectViolations = (violations: Result[]) =>
+  violations
+    .map((violation) => `${violation.id}(${violation.nodes.length})`)
+    .join(', ')
+
+export async function toBeAccessible(
+  this: MatcherState,
+  ...args: InputArguments
+): Promise<SyncExpectationResult> {
+  try {
+    const [elementHandle] = await getElementHandle(args)
+    const frame = (await elementHandle.ownerFrame())!
+
+    await injectAxe(frame)
+    const results = await runAxe(elementHandle, {})
+    const count = results.violations.length
+
+    return {
+      pass: count === 0,
+      message: () => {
+        return (
+          this.utils.matcherHint('toBeAccessible', undefined, undefined, this) +
+          '\n\n' +
+          'Expected: No violations\n' +
+          `Received: ${count} violations\n\n` +
+          `Violations: ${collectViolations(results.violations)}`
+        )
+      },
+    }
+  } catch (err) {
+    return {
+      pass: false,
+      message: () => err.message,
+    }
+  }
+}
diff --git a/src/utils/axe.ts b/src/utils/axe.ts
@@ -1,6 +1,6 @@
 import fs from 'fs'
-import type { Page } from '@playwright/test'
-import { AxePlugin, AxeResults, RunOptions } from 'axe-core'
+import type { ElementHandle, Frame, Page } from '@playwright/test'
+import type { AxePlugin, AxeResults, RunOptions } from 'axe-core'
 
 declare global {
   interface Window {
@@ -11,9 +11,9 @@ declare global {
 /**
  * Injects the axe-core script into the page if it hasn't already been injected.
  */
-export async function injectAxe(page: Page): Promise<void> {
+export async function injectAxe(frame: Page | Frame) {
   // Exit early if Axe has already been injected.
-  if (await page.evaluate(() => !!window.axe)) {
+  if (await frame.evaluate(() => !!window.axe)) {
     return
   }
 
@@ -22,18 +22,16 @@ export async function injectAxe(page: Page): Promise<void> {
   const axe = await fs.promises.readFile(filePath, 'utf-8')
 
   // Inject the script into the page
-  await page.evaluate((axe) => window.eval(axe), axe)
+  await frame.evaluate((axe) => window.eval(axe), axe)
 }
 
 /**
- * Runs axe on the page. The script must already be injected using `injectAxe`.
+ * Runs axe on an element handle. The script must already be injected
+ * using `injectAxe`.
  */
-export function runAxe(
-  page: Page,
-  options: RunOptions = {}
-): Promise<AxeResults> {
-  return page.evaluate<AxeResults>(
-    (options) => window.axe.run(window.document, options),
+export function runAxe(element: ElementHandle, options: RunOptions = {}) {
+  return element.evaluate<AxeResults>(
+    (el, options) => window.axe.run(el, options),
     options
   )
 }
diff --git a/src/utils/file.ts b/src/utils/file.ts
@@ -0,0 +1,7 @@
+import path from 'path'
+import fs from 'fs'
+
+export async function readFile(filename: string) {
+  const filePath = path.join(__dirname, '../config/templates', filename)
+  return fs.promises.readFile(filePath, { encoding: 'utf-8' })
+}
diff --git a/src/utils/matcher.ts b/src/utils/matcher.ts
@@ -0,0 +1,38 @@
+import type { Page, Frame, ElementHandle } from '@playwright/test'
+
+type Handle = Page | Frame | ElementHandle
+export type InputType = Handle | Promise<Handle>
+
+function isElementHandle(value: Handle): value is ElementHandle {
+  return value.constructor.name === 'ElementHandle'
+}
+
+async function getFrame(value: InputType) {
+  const resolved = await value
+  return isElementHandle(resolved) ? resolved.contentFrame() : resolved
+}
+
+export type InputArguments = [InputType, string?]
+
+const isObject = (value: unknown) =>
+  typeof value === 'object' && !(value instanceof RegExp)
+
+export async function getElementHandle(args: InputArguments) {
+  // Finally, we can find the element handle
+  const handle = await args[0]
+  let elementHandle = (await getFrame(handle)) ?? handle
+
+  // If the user provided a page or iframe, we need to locate the provided
+  // selector or the `html` element if none was provided.
+  if (!isElementHandle(elementHandle)) {
+    const selector = args[1] ?? 'html'
+
+    try {
+      elementHandle = (await elementHandle.waitForSelector(selector))!
+    } catch (err) {
+      throw new Error(`Timeout exceed for element "${selector}"`)
+    }
+  }
+
+  return [elementHandle, {}] as const
+}

Original file line number	Diff line number	Diff line change
`@@ -1,8 +1,11 @@`
`1`	`1`	`{`
`2`	`2`	`"parser": "@typescript-eslint/parser",`
`3`		`- "plugins": ["@typescript-eslint"],`
`4`	`3`	`"extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],`
`5`	`4`	`"env": {`
`6`	`5`	`"node": true`
	`6`	`+ },`
	`7`	`+ "rules": {`
	`8`	`+ "@typescript-eslint/no-non-null-assertion": "off",`
	`9`	`+ "@typescript-eslint/explicit-module-boundary-types": "off"`
`7`	`10`	`}`
`8`	`11`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,6 @@`
`1`	`1`	`interface AxePlaywrightMatchers<R> {`
`2`	`2`	`toBeAccessible(): Promise<R>`
	`3`	`+ toBeAccessible(selector: string): Promise<R>`
`3`	`4`	`}`
`4`	`5`
`5`	`6`	`declare global {`