feat(playwright): add playwright integration (#245)

.circleci/config.yml

@@ -30,6 +30,9 @@ jobs:
       - restore_cache:
           keys:
             - v1-cli-npm-{{ checksum "packages/cli/package-lock.json" }}
+      - restore_cache:
+          keys:
+            - v1-playwright-npm-{{ checksum "packages/playwright/package-lock.json" }}
       - restore_cache:
           keys:
             - v1-puppeteer-npm-{{ checksum "packages/puppeteer/package-lock.json" }}
@@ -61,6 +64,10 @@ jobs:
           key: v1-cli-npm-{{ checksum "packages/cli/package-lock.json" }}
           paths:
             - packages/cli/node_modules
+      - save_cache:
+          key: v1-playwright-npm-{{ checksum "packages/playwright/package-lock.json" }}
+          paths:
+            - packages/playwright/node_modules
       - save_cache:
           key: v1-puppeteer-npm-{{ checksum "packages/puppeteer/package-lock.json" }}
           paths:
@@ -90,6 +97,7 @@ jobs:
           paths:
             - node_modules
             - packages/cli/node_modules
+            - packages/playwright/node_modules
             - packages/puppeteer/node_modules
             - packages/webdriverjs/node_modules
             - packages/webdriverio/node_modules
@@ -153,6 +161,20 @@ jobs:
       - run: npm run build --prefix=packages/react
       - run: npm run test --prefix=packages/react
 
+  playwright:
+    docker:
+      - image: mcr.microsoft.com/playwright:bionic
+    environment:
+      NODE_ENV: development
+    working_directory: ~/axe-core-npm
+    steps:
+      - checkout
+      - restore_dependency_cache
+      - run: npm install
+      - run: npm run bootstrap -- --ci
+      - run: npm run build --prefix=packages/playwright
+      - run: npm run coverage --prefix=packages/playwright
+
   axe-core-test:
     <<: *defaults
     steps:
@@ -203,6 +225,9 @@ workflows:
       - cli:
           requires:
             - lint
+      - playwright:
+          requires:
+            - lint
       - puppeteer:
           requires:
             - lint

.github/axe-linter.yml

@@ -9,3 +9,4 @@ exclude:
   - packages/cli/testutils/**/*
   - packages/webdriverio/fixtures/**
   - packages/webdriverjs/src/test/fixtures/**
+  - packages/playwright/fixtures/**

packages/playwright/.npmrc

@@ -0,0 +1 @@
+registry=https://registry.npmjs.org/

packages/playwright/README.md

@@ -0,0 +1,140 @@
+# @axe-core/playwright
+
+> Provides a chainable axe API for playwright and automatically injects into all frames
+
+## Getting Started
+
+Install [Node.js](https://docs.npmjs.com/getting-started/installing-node) if you haven't already.
+
+Install Playwright:
+
+NPM:
+
+```console
+npm install playwright
+```
+
+Yarn:
+
+```console
+yarn add playwright
+```
+
+Install `@axe-core/playwright` and its dependencies:
+
+NPM:
+
+```console
+npm install @axe-core/playwright
+```
+
+Yarn:
+
+```console
+yarn add @axe-core/playwright
+```
+
+## Usage
+
+This module uses a chainable API to assist in injecting, configuring, and analyzing axe with [Playwright](https://playwright.dev/). As such, it is required to pass an instance of Playwright.
+
+Here is an example of a script that will drive Playwright to a page, perform an analysis, and then log results to the console.
+
+```js
+const AxeBuilder = require('@axe-core/playwright').default;
+const playwright = require('playwright');
+
+(async () => {
+  const browser = await playwright.chromium.launch();
+  const context = await browser.newContext();
+  const page = await context.newPage();
+  await page.goto('https://dequeuniversity.com/demo/mars/');
+
+  try {
+    const results = await new AxeBuilder({ page }).analyze();
+    console.log(results);
+  } catch (e) {
+    // do something with the error
+  }
+  await browser.close();
+})();
+```
+
+## AxeBuilder({ page: Playwright.Page })
+
+Constructor for the AxeBuilder helper. You must pass an instance of Playwright as the first argument.
+
+```js
+const builder = new AxeBuilder({ page });
+```
+
+### AxeBuilder#include(selector: String)
+
+Adds a CSS selector to the list of elements to include in analysis
+
+```js
+new AxeBuilder({ page }).include('.results-panel');
+```
+
+### AxeBuilder#exclude(selector: String)
+
+Add a CSS selector to the list of elements to exclude from analysis
+
+```js
+new AxeBuilder({ page }).exclude('.another-element');
+```
+
+### AxeBuilder#options(options: [axe.RunOptions](https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter))
+
+Specifies options to be used by `axe.run`. Will override any other configured options. including calls to `AxeBuilder#withRules()` and `AxeBuilder#withTags()`. See [axe-core API documentation](https://github.com/dequelabs/axe-core/blob/master/doc/API.md) for information on its structure.
+
+```js
+new AxeBuilder({ page }).options({ checks: { 'valid-lang': ['orcish'] } });
+```
+
+### AxeBuilder#withRules(rules: String|Array)
+
+Limits analysis to only those with the specified rule IDs. Accepts a String of a single rule ID or an Array of multiple rule IDs. Subsequent calls to `AxeBuilder#options`, `AxeBuilder#withRules` or `AxeBuilder#withRules` will override specified options.
+
+```js
+new AxeBuilder({ page }).withRules('html-lang');
+```
+
+```js
+new AxeBuilder({ page }).withRules(['html-lang', 'image-alt']);
+```
+
+### AxeBuilder#withTags(tags: String|Array)
+
+Limits analysis to only those with the specified rule IDs. Accepts a String of a single tag or an Array of multiple tags. Subsequent calls to `AxeBuilder#options`, `AxeBuilder#withRules` or `AxeBuilder#withRules` will override specified options.
+
+```js
+new AxeBuilder({ page }).withTags('wcag2a');
+```
+
+```js
+new AxeBuilder({ page }).withTags(['wcag2a', 'wcag2aa']);
+```
+
+### AxeBuilder#disableRules(rules: String|Array)
+
+Skips verification of the rules provided. Accepts a String of a single rule ID or an Array of multiple rule IDs. Subsequent calls to `AxeBuilder#options`, `AxeBuilder#disableRules` will override specified options.
+
+```js
+new AxeBuilder({ page }).disableRules('color-contrast');
+```
+
+### AxeBuilder#analyze(): Promise<axe.Results | Error>
+
+Performs analysis and passes any encountered error and/or the result object.
+
+```js
+new AxeBuilder({ page })
+  .analyze()
+  .then(results => {
+    console.log(results);
+  })
+  .catch(e => {
+    // Do something with error
+  });
+```

packages/playwright/example.js

@@ -0,0 +1,12 @@
+const AxeBuilder = require('@axe-core/playwright').default;
+const playwright = require('playwright');
+
+(async () => {
+  const browser = await playwright.chromium.launch();
+  const context = await browser.newContext();
+  const page = await context.newPage();
+  await page.goto('https://dequeuniversity.com/demo/mars/');
+  const results = await new AxeBuilder({ page }).analyze();
+  console.log(results);
+  await browser.close();
+})();

packages/playwright/fixtures/context.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Context Test</title>
+  </head>
+  <body>
+    <h1>Context Test</h1>
+    <div class="include">include me</div>
+    <div class="exclude">exclude me</div>
+  </body>
+</html>

packages/playwright/fixtures/frames/bar.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Bar</title>
+  </head>
+  <body>
+    <h1>Bar</h1>
+    <iframe src="/frames/baz.html"></iframe>
+  </body>
+</html>

packages/playwright/fixtures/frames/baz.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Baz</title>
+  </head>
+  <body>
+    <h1>Baz</h1>
+    <div id="myList">
+      <dt>Coffee</dt>
+      <dd>Black hot drink</dd>
+      <dt>Milk</dt>
+      <dd>White cold drink</dd>
+    </div>
+  </body>
+</html>

packages/playwright/fixtures/frames/foo.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Foo</title>
+  </head>
+  <body>
+    <h1>Foo</h1>
+    <iframe src="/frames/bar.html"></iframe>
+  </body>
+</html>

packages/playwright/fixtures/frames/recursive.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Recursive</title>
+  </head>
+  <body>
+    <h1>Recursive</h1>
+    <iframe src="/frames/recursive.html"></iframe>
+  </body>
+</html>

packages/playwright/fixtures/index.html

@@ -0,0 +1,6 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Test</title>
+  </head>
+</html>

packages/playwright/fixtures/nested-frames.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Nested Frames</title>
+  </head>
+  <body>
+    <h1>This page has nested frames!</h1>
+    <br /><br /><br />
+    <iframe src="/frames/foo.html"></iframe>
+  </body>
+</html>