axe-playwright 1.1.7 → 1.1.10

package/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+- package-ecosystem: npm
+  directory: "/"
+  schedule:
+    interval: daily
+    time: "23:30"
+  open-pull-requests-limit: 10
+  ignore:
+  - dependency-name: "@types/node"
+    versions:
+    - 15.0.0

package/README.md

@@ -4,6 +4,7 @@
 
 [![Build Status](https://circleci.com/gh/abhinaba-ghosh/axe-playwright.svg?style=shield&branch-=master)](https://app.circleci.com/pipelines/github/abhinaba-ghosh/axe-playwright)
 [![NPM release](https://img.shields.io/npm/v/axe-playwright.svg 'NPM release')](https://www.npmjs.com/package/axe-playwright)
+[![NPM Downloads](https://img.shields.io/npm/dt/axe-playwright.svg?style=flat-square)](https://www.npmjs.com/package/axe-playwright)
 
 [Axe](https://www.deque.com/axe/) is an accessibility testing engine for websites and other HTML-based user interfaces. This package provides simple axe analyser commands which you can incorporate in your [Playwright](https://www.npmjs.com/package/playwright) tests.The idea is highly inspired by [Andy Van Slaars](https://github.com/avanslaars) cypress-axe project.
 
@@ -115,17 +116,63 @@ The `detailedReport` key is a boolean whether to print the more detailed report
 }
 ```
 
+##### reporter (optional)
+
+A class instance that implements the `Reporter` interface. Custom reporter instances can be supplied to override default reporting behaviour dictated by `DefaultTerminalReporter`.
+
 ##### skipFailures (optional, defaults to false)
 
 Disables assertions based on violations and only logs violations to the console output. If you set `skipFailures` as `true`, although accessibility check is not passed, your test will not fail. It will simply print the violations in the console, but will not make the test fail.
 
+### getAxeResults
+
+This will run axe against the document at the point in which it is called, then returns the full set of results as reported by `axe.run`.
+
+#### Parameters on getAxeResults
+
+##### page (mandatory)
+
+The `page` instance of `playwright`.
+
+##### context (optional)
+
+Defines the scope of the analysis - the part of the DOM that you would like to analyze. This will typically be the document or a specific selector such as class name, ID, selector, etc.
+
+##### options (optional)
+
+Set of options passed into rules or checks, temporarily modifying them. This contrasts with axe.configure, which is more permanent.
+
+The object is of the same type which is [accepted by `axe.run`'s options argument](https://www.deque.com/axe/documentation/api-documentation/#parameters-axerun) and directly forwarded to it.
+
+### getViolations
+
+This will run axe against the document at the point in which it is called, then return you an array of accessibility violations (i.e. the `violations` array included in the `getAxeResults` result).
+
+#### Parameters on getViolations (axe.run)
+
+Identical to [parameters of getAxeResults](#parameters-on-getAxeResults).
+
+### reportViolations
+
+Reports violations based on the `Reporter` concrete implementation behaviour. 
+
+#### Parameters on reportViolations
+
+##### violations (mandatory)
+
+An array of Axe violations to be printed.
+
+##### reporter (mandatory)
+
+A class instance that implements the `Reporter` interface. Custom reporter instances can be supplied to override default reporting behaviour dictated by `DefaultTerminalReporter`.
+
 ### Examples
 
 #### Basic usage
 
-```js
+```ts
 import { chromium, Browser, Page } from 'playwright'
-import { injectAxe, checkA11y } from 'axe-playwright'
+import { injectAxe, checkA11y, getViolations, reportViolations } from 'axe-playwright'
 
 let browser: Browser
 let page: Page
@@ -164,6 +211,21 @@ describe('Playwright web page accessibility test', () => {
     })
   })
 
+  it('gets and reports a11y for the specific element', async () => {
+    const violations = await getViolations(page, 'input[name="password"]', {
+      axeOptions: {
+        runOnly: {
+          type: 'tag',
+          values: ['wcag2a'],
+        },
+      },
+    })
+
+    reportViolations(violations, new YourAwesomeCsvReporter('accessibility-report.csv'))
+
+    expect(violations.length).toBe(0)
+  })
+
   afterAll(async () => {
     await browser.close()
   })
@@ -178,7 +240,7 @@ This custom logging behavior results in terminal output like this:
 
 The detailed report is disabled by default, but can be enabled by including the `detailedReport` property in the `checkAlly` options.
 
-```js
+```ts
 import { chromium, Browser, Page } from 'playwright'
 import { injectAxe, checkA11y } from 'axe-playwright'
 

package/dist/index.js

@@ -27,10 +27,14 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.checkA11y = exports.configureAxe = exports.injectAxe = void 0;
+exports.checkA11y = exports.reportViolations = exports.getViolations = exports.configureAxe = exports.injectAxe = void 0;
 const fs = __importStar(require("fs"));
 const utils_1 = require("./utils");
+const defaultTerminalReporter_1 = __importDefault(require("./reporter/defaultTerminalReporter"));
 /**
  * Injects axe executable commands in the active window
  * @param page
@@ -50,20 +54,45 @@ const configureAxe = (page, configurationOptions = {}) => __awaiter(void 0, void
 });
 exports.configureAxe = configureAxe;
 /**
- * Performs Axe validations
+ * Runs axe-core tools on the relevant page and returns all accessibility violations detected on the page
  * @param page
  * @param context
  * @param options
- * @param skipFailures
  */
-const checkA11y = (page, context = undefined, options = undefined, skipFailures = false) => __awaiter(void 0, void 0, void 0, function* () {
-    let axeResults = yield page.evaluate(([context, options]) => {
+const getViolations = (page, context, options) => __awaiter(void 0, void 0, void 0, function* () {
+    const result = yield page.evaluate(([context, options]) => {
         const axeOptions = options ? options['axeOptions'] : {};
         return window.axe.run(context || window.document, axeOptions);
     }, [context, options]);
-    const { includedImpacts, detailedReport = false, detailedReportOptions = { html: false }, } = options || {};
-    const violations = utils_1.getImpactedViolations(axeResults.violations, includedImpacts);
-    utils_1.printViolationTerminal(violations, detailedReport, !!detailedReportOptions.html);
-    utils_1.testResultDependsOnViolations(violations, skipFailures);
+    return result.violations;
+});
+exports.getViolations = getViolations;
+/**
+ * Report violations given the reporter.
+ * @param violations
+ * @param reporter
+ */
+const reportViolations = (violations, reporter) => __awaiter(void 0, void 0, void 0, function* () {
+    yield reporter.report(violations);
+});
+exports.reportViolations = reportViolations;
+/**
+ * Performs Axe validations
+ * @param page
+ * @param context
+ * @param options
+ * @param skipFailures
+ * @param reporter
+ */
+const checkA11y = (page, context, options, skipFailures, reporter) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    if (context === void 0) { context = undefined; }
+    if (options === void 0) { options = undefined; }
+    if (skipFailures === void 0) { skipFailures = false; }
+    if (reporter === void 0) { reporter = new defaultTerminalReporter_1.default(options === null || options === void 0 ? void 0 : options.detailedReport, (_a = options === null || options === void 0 ? void 0 : options.detailedReportOptions) === null || _a === void 0 ? void 0 : _a.html); }
+    const violations = yield exports.getViolations(page, context, options);
+    const impactedViolations = utils_1.getImpactedViolations(violations, options === null || options === void 0 ? void 0 : options.includedImpacts);
+    yield exports.reportViolations(impactedViolations, reporter);
+    utils_1.testResultDependsOnViolations(impactedViolations, skipFailures);
 });
 exports.checkA11y = checkA11y;

package/dist/reporter/defaultTerminalReporter.js

@@ -0,0 +1,51 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("../utils");
+class DefaultTerminalReporter {
+    constructor(detailedReport, includeHtml) {
+        this.detailedReport = detailedReport;
+        this.includeHtml = includeHtml;
+    }
+    report(violations) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const violationData = violations.map(({ id, impact, description, nodes }) => {
+                return {
+                    id,
+                    impact,
+                    description,
+                    nodes: nodes.length,
+                };
+            });
+            if (violationData.length > 0) {
+                // summary
+                console.table(violationData);
+                if (this.detailedReport) {
+                    const nodeViolations = utils_1.describeViolations(violations).map(({ target, html, violations }) => {
+                        if (!this.includeHtml) {
+                            return {
+                                target,
+                                violations,
+                            };
+                        }
+                        return { target, html, violations };
+                    });
+                    // per node
+                    console.table(nodeViolations);
+                }
+            }
+            else {
+                console.log(`No accessibility violations detected!`);
+            }
+        });
+    }
+}
+exports.default = DefaultTerminalReporter;

package/dist/utils.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.printViolationTerminal = exports.describeViolations = exports.testResultDependsOnViolations = exports.getImpactedViolations = void 0;
+exports.describeViolations = exports.testResultDependsOnViolations = exports.getImpactedViolations = void 0;
 const assert_1 = __importDefault(require("assert"));
 const getImpactedViolations = (violations, includedImpacts = []) => {
     return Array.isArray(includedImpacts) && includedImpacts.length
@@ -47,34 +47,3 @@ const describeViolations = (violations) => {
     });
 };
 exports.describeViolations = describeViolations;
-const printViolationTerminal = (violations, detailedReport, includeHtml) => {
-    const violationData = violations.map(({ id, impact, description, nodes }) => {
-        return {
-            id,
-            impact,
-            description,
-            nodes: nodes.length,
-        };
-    });
-    if (violationData.length > 0) {
-        // summary
-        console.table(violationData);
-        if (detailedReport) {
-            const nodeViolations = exports.describeViolations(violations).map(({ target, html, violations }) => {
-                if (!includeHtml) {
-                    return {
-                        target,
-                        violations,
-                    };
-                }
-                return { target, html, violations };
-            });
-            // per node
-            console.table(nodeViolations);
-        }
-    }
-    else {
-        console.log(`No accessibility violations detected!`);
-    }
-};
-exports.printViolationTerminal = printViolationTerminal;

package/index.d.ts

@@ -1,11 +1,4 @@
-import {
-  Check,
-  ElementContext,
-  ImpactValue,
-  Locale,
-  Rule,
-  RunOptions,
-} from 'axe-core'
+import { AxeResults, Check, ElementContext, ImpactValue, Locale, Result, Rule, RunOptions } from 'axe-core'
 import { Page } from 'playwright'
 
 export interface axeOptionsConfig {
@@ -24,6 +17,22 @@ export interface ConfigOptions {
   axeVersion?: string
 }
 
+/**
+ * Implement this interface to be able to specific custom reporting behaviour for checkA11y method.
+ * @see checkA11y
+ */
+export default interface Reporter {
+  report(violations: Result[]): Promise<void>
+}
+
+/**
+ * Default implementation of a reporter which prints a summary to the console.
+ */
+export class DefaultTerminalReporter implements Reporter {
+  constructor(detailedReport: boolean | undefined, includeHtml: boolean | undefined)
+  report(violations: Result[]): Promise<void>
+}
+
 export type Options = {
   includedImpacts?: ImpactValue[]
   detailedReport?: boolean
@@ -59,3 +68,26 @@ export function checkA11y(
  * @param options
  */
 export function configureAxe(page: Page, options?: ConfigOptions): Promise<void>
+
+/**
+ * Runs axe-core tools on the relevant page and returns all results
+ * @param page
+ * @param context
+ * @param options
+ */
+ export function getAxeResults(page: Page, context?: ElementContext, options?: RunOptions): Promise<AxeResults[]>
+
+/**
+ * Runs axe-core tools on the relevant page and returns all accessibility violations detected on the page
+ * @param page
+ * @param context
+ * @param options
+ */
+export function getViolations(page: Page, context?: ElementContext, options?: RunOptions): Promise<Result[]>
+
+/**
+ * Report violations given the reporter.
+ * @param violations
+ * @param reporter
+ */
+export function reportViolations(violations: Result[], reporter: Reporter): Promise<void>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axe-playwright",
-  "version": "1.1.7",
+  "version": "1.1.10",
   "description": "Custom Playwright commands to inject axe-core and test for a11y",
   "main": "dist/index.js",
   "types": "index.d.ts",
@@ -25,11 +25,11 @@
   "author": "Abhinaba Ghosh",
   "license": "MIT",
   "devDependencies": {
-    "@types/is-ci": "^2.0.0",
-    "@types/jest": "^26.0.10",
-    "@types/node": "^14.14.25",
+    "@types/is-ci": "^3.0.0",
+    "@types/jest": "^27.0.3",
+    "@types/node": "^17.0.4",
     "jest": "^26.6.3",
-    "jest-each": "^26.6.2",
+    "jest-each": "^27.0.2",
     "jest-playwright-preset": "^1.3.1",
     "playwright": "^1.1.1",
     "prettier": "^2.0.5",

package/src/index.ts

@@ -2,11 +2,9 @@ import { Page } from 'playwright'
 import * as fs from 'fs'
 import { AxeResults, ElementContext, Result, RunOptions, Spec } from 'axe-core'
 import { ConfigOptions, Options } from '../index'
-import {
-  getImpactedViolations,
-  printViolationTerminal,
-  testResultDependsOnViolations,
-} from './utils'
+import { getImpactedViolations, testResultDependsOnViolations } from './utils'
+import DefaultTerminalReporter from './reporter/defaultTerminalReporter'
+import Reporter from './types'
 
 declare global {
   interface Window {
@@ -41,41 +39,77 @@ export const configureAxe = async (
   )
 }
 
+/**
+ * Runs axe-core tools on the relevant page and returns all results
+ * @param page
+ * @param context
+ * @param options
+ */
+export const getAxeResults = async (
+  page: Page,
+  context?: ElementContext,
+  options?: RunOptions,
+): Promise<AxeResults> => {
+  const result = await page.evaluate(
+    ([context, options]) => {
+      return window.axe.run(context || window.document, options)
+    },
+    [context, options],
+  )
+
+  return result
+}
+
+/**
+ * Runs axe-core tools on the relevant page and returns all accessibility violations detected on the page
+ * @param page
+ * @param context
+ * @param options
+ */
+export const getViolations = async (
+  page: Page,
+  context?: ElementContext,
+  options?: RunOptions,
+): Promise<Result[]> => {
+  const result = await getAxeResults(page, context, options)
+  return result.violations
+}
+
+/**
+ * Report violations given the reporter.
+ * @param violations
+ * @param reporter
+ */
+export const reportViolations = async (violations: Result[], reporter: Reporter): Promise<void> => {
+  await reporter.report(violations)
+}
+
 /**
  * Performs Axe validations
  * @param page
  * @param context
  * @param options
  * @param skipFailures
+ * @param reporter
  */
 export const checkA11y = async (
   page: Page,
   context: ElementContext | undefined = undefined,
   options: Options | undefined = undefined,
   skipFailures: boolean = false,
+  reporter: Reporter = new DefaultTerminalReporter(options?.detailedReport, options?.detailedReportOptions?.html),
 ): Promise<void> => {
-  let axeResults: AxeResults = await page.evaluate(
-    ([context, options]) => {
-      const axeOptions: RunOptions = options ? options['axeOptions'] : {}
-      return window.axe.run(context || window.document, axeOptions)
-    },
-    [context, options],
-  )
+  const violations = await getViolations(page, context, options?.axeOptions)
 
-  const {
-    includedImpacts,
-    detailedReport = false,
-    detailedReportOptions = { html: false },
-  } = options || {}
-  const violations: Result[] = getImpactedViolations(
-    axeResults.violations,
-    includedImpacts,
+  const impactedViolations = getImpactedViolations(
+    violations,
+    options?.includedImpacts,
   )
 
-  printViolationTerminal(
-    violations,
-    detailedReport,
-    !!detailedReportOptions.html,
+  await reportViolations(
+    impactedViolations,
+    reporter,
   )
-  testResultDependsOnViolations(violations, skipFailures)
+
+  testResultDependsOnViolations(impactedViolations, skipFailures)
 }

package/src/reporter/defaultTerminalReporter.ts

@@ -0,0 +1,43 @@
+import Reporter from '../types'
+import { Result } from 'axe-core'
+import { describeViolations } from '../utils'
+
+export default class DefaultTerminalReporter implements Reporter {
+  constructor(
+    protected detailedReport: boolean | undefined,
+    protected includeHtml: boolean | undefined,
+  ) {}
+
+  async report(violations: Result[]): Promise<void> {
+    const violationData = violations.map(({ id, impact, description, nodes }) => {
+      return {
+        id,
+        impact,
+        description,
+        nodes: nodes.length,
+      }
+    })
+
+    if (violationData.length > 0) {
+      // summary
+      console.table(violationData)
+      if (this.detailedReport) {
+        const nodeViolations = describeViolations(violations).map(
+          ({ target, html, violations }) => {
+            if (!this.includeHtml) {
+              return {
+                target,
+                violations,
+              }
+            }
+            return { target, html, violations }
+          },
+        )
+        // per node
+        console.table(nodeViolations)
+      }
+    } else {
+      console.log(`No accessibility violations detected!`)
+    }
+  }
+}

package/src/types.ts

@@ -1,3 +1,5 @@
+import { Result } from 'axe-core'
+
 export interface NodeViolation {
   target: string
   html: string
@@ -11,3 +13,7 @@ export interface Aggregate {
     violations: number[]
   }
 }
+
+export default interface Reporter {
+  report(violations: Result[]): Promise<void>
+}

package/src/utils.ts

@@ -5,11 +5,11 @@ import assert from 'assert'
 export const getImpactedViolations = (
   violations: Result[],
   includedImpacts: ImpactValue[] = [],
-) => {
+): Result[] => {
   return Array.isArray(includedImpacts) && includedImpacts.length
     ? violations.filter(
-        (v: Result) => v.impact && includedImpacts.includes(v.impact),
-      )
+      (v: Result) => v.impact && includedImpacts.includes(v.impact),
+    )
     : violations
 }
 
@@ -59,40 +59,3 @@ export const describeViolations = (violations: Result[]): NodeViolation[] => {
     return { target, html, violations: JSON.stringify(violations) }
   })
 }
-
-export const printViolationTerminal = (
-  violations: Result[],
-  detailedReport: boolean,
-  includeHtml: boolean,
-) => {
-  const violationData = violations.map(({ id, impact, description, nodes }) => {
-    return {
-      id,
-      impact,
-      description,
-      nodes: nodes.length,
-    }
-  })
-
-  if (violationData.length > 0) {
-    // summary
-    console.table(violationData)
-    if (detailedReport) {
-      const nodeViolations = describeViolations(violations).map(
-        ({ target, html, violations }) => {
-          if (!includeHtml) {
-            return {
-              target,
-              violations,
-            }
-          }
-          return { target, html, violations }
-        },
-      )
-      // per node
-      console.table(nodeViolations)
-    }
-  } else {
-    console.log(`No accessibility violations detected!`)
-  }
-}