axe-playwright 2.0.0 → 2.0.1

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { Page } from 'playwright';
+import { AxeResults, ElementContext, Result, RunOptions } from 'axe-core';
+import DefaultTerminalReporter from './reporter/defaultTerminalReporter';
+import Reporter, { ConfigOptions, AxeOptions } from './types';
+import { Options } from 'axe-html-reporter';
+declare global {
+    interface Window {
+        axe: any;
+    }
+}
+declare module 'axe-core' {
+    interface Node {
+    }
+}
+/**
+ * Injects axe executable commands in the active window
+ * @param page
+ */
+export declare const injectAxe: (page: Page) => Promise<void>;
+/**
+ * Configures axe runtime options
+ * @param page
+ * @param configurationOptions
+ */
+export declare const configureAxe: (page: Page, configurationOptions?: ConfigOptions) => Promise<void>;
+/**
+ * Runs axe-core tools on the relevant page and returns all results
+ * @param page
+ * @param context
+ * @param options
+ */
+export declare const 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 declare const getViolations: (page: Page, context?: ElementContext, options?: RunOptions) => Promise<Result[]>;
+/**
+ * Report violations given the reporter.
+ * @param violations
+ * @param reporter
+ */
+export declare const reportViolations: (violations: Result[], reporter: Reporter) => Promise<void>;
+/**
+ * Performs Axe validations
+ * @param page
+ * @param context
+ * @param axeOptions
+ * @param skipFailures
+ * @param reporter
+ * @param options
+ */
+export declare const checkA11y: (page: Page, context?: ElementContext | undefined, axeOptions?: AxeOptions | undefined, skipFailures?: boolean, reporter?: Reporter | 'default' | 'html' | 'junit' | 'v2', options?: Options | undefined) => Promise<void>;
+export { DefaultTerminalReporter };

package/dist/index.js

@@ -0,0 +1,142 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+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());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultTerminalReporter = exports.checkA11y = exports.reportViolations = exports.getViolations = exports.getAxeResults = exports.configureAxe = exports.injectAxe = void 0;
+const fs = __importStar(require("fs"));
+const utils_1 = require("./utils");
+const defaultTerminalReporter_1 = __importDefault(require("./reporter/defaultTerminalReporter"));
+exports.DefaultTerminalReporter = defaultTerminalReporter_1.default;
+const terminalReporterV2_1 = __importDefault(require("./reporter/terminalReporterV2"));
+const axe_html_reporter_1 = require("axe-html-reporter");
+const junitReporter_1 = __importDefault(require("./reporter/junitReporter"));
+const path = __importStar(require("path"));
+/**
+ * Injects axe executable commands in the active window
+ * @param page
+ */
+const injectAxe = (page) => __awaiter(void 0, void 0, void 0, function* () {
+    const axe = fs.readFileSync(require.resolve('axe-core/axe.min.js'), 'utf8');
+    yield page.evaluate((axe) => window.eval(axe), axe);
+});
+exports.injectAxe = injectAxe;
+/**
+ * Configures axe runtime options
+ * @param page
+ * @param configurationOptions
+ */
+const configureAxe = (page, configurationOptions = {}) => __awaiter(void 0, void 0, void 0, function* () {
+    yield page.evaluate((configOptions) => window.axe.configure(configOptions), configurationOptions);
+});
+exports.configureAxe = configureAxe;
+/**
+ * Runs axe-core tools on the relevant page and returns all results
+ * @param page
+ * @param context
+ * @param options
+ */
+const getAxeResults = (page, context, options) => __awaiter(void 0, void 0, void 0, function* () {
+    const result = yield page.evaluate(([context, options]) => {
+        return window.axe.run(context || window.document, options);
+    }, [context, options]);
+    return result;
+});
+exports.getAxeResults = getAxeResults;
+/**
+ * Runs axe-core tools on the relevant page and returns all accessibility violations detected on the page
+ * @param page
+ * @param context
+ * @param options
+ */
+const getViolations = (page, context, options) => __awaiter(void 0, void 0, void 0, function* () {
+    const result = yield (0, exports.getAxeResults)(page, context, options);
+    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 axeOptions
+ * @param skipFailures
+ * @param reporter
+ * @param options
+ */
+const checkA11y = (page, context = undefined, axeOptions = undefined, skipFailures = false, reporter = 'default', options = undefined) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b, _c;
+    const violations = yield (0, exports.getViolations)(page, context, axeOptions === null || axeOptions === void 0 ? void 0 : axeOptions.axeOptions);
+    const impactedViolations = (0, utils_1.getImpactedViolations)(violations, axeOptions === null || axeOptions === void 0 ? void 0 : axeOptions.includedImpacts);
+    let reporterWithOptions;
+    if (reporter === 'default') {
+        reporterWithOptions = new defaultTerminalReporter_1.default(axeOptions === null || axeOptions === void 0 ? void 0 : axeOptions.detailedReport, (_a = axeOptions === null || axeOptions === void 0 ? void 0 : axeOptions.detailedReportOptions) === null || _a === void 0 ? void 0 : _a.html, (_b = axeOptions === null || axeOptions === void 0 ? void 0 : axeOptions.verbose) !== null && _b !== void 0 ? _b : true);
+    }
+    else if (reporter === 'v2') {
+        reporterWithOptions = new terminalReporterV2_1.default((_c = axeOptions === null || axeOptions === void 0 ? void 0 : axeOptions.verbose) !== null && _c !== void 0 ? _c : false);
+    }
+    else if (reporter === 'html') {
+        if (violations.length > 0) {
+            yield (0, axe_html_reporter_1.createHtmlReport)({
+                results: { violations },
+                options,
+            });
+        }
+        else
+            console.log('There were no violations to save in report');
+    }
+    else if (reporter === 'junit') {
+        // Get the system root directory
+        // Construct the file path
+        const outputFilePath = path.join(process.cwd(), options === null || options === void 0 ? void 0 : options.outputDirPath, options === null || options === void 0 ? void 0 : options.outputDir, options === null || options === void 0 ? void 0 : options.reportFileName);
+        reporterWithOptions = new junitReporter_1.default(axeOptions === null || axeOptions === void 0 ? void 0 : axeOptions.detailedReport, page, outputFilePath);
+    }
+    else {
+        reporterWithOptions = reporter;
+    }
+    if (reporter !== 'html')
+        yield (0, exports.reportViolations)(impactedViolations, reporterWithOptions);
+    if (reporter === 'v2' || (reporter !== 'html' && reporter !== 'junit'))
+        (0, utils_1.testResultDependsOnViolations)(impactedViolations, skipFailures);
+});
+exports.checkA11y = checkA11y;

package/dist/reporter/defaultTerminalReporter.d.ts

@@ -0,0 +1,9 @@
+import Reporter from '../types';
+import { Result } from 'axe-core';
+export default class DefaultTerminalReporter implements Reporter {
+    protected detailedReport: boolean | undefined;
+    protected includeHtml: boolean | undefined;
+    protected verbose: boolean | undefined;
+    constructor(detailedReport: boolean | undefined, includeHtml: boolean | undefined, verbose: boolean | undefined);
+    report(violations: Result[]): Promise<void>;
+}

package/dist/reporter/defaultTerminalReporter.js

@@ -0,0 +1,52 @@
+"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, verbose) {
+        this.detailedReport = detailedReport;
+        this.includeHtml = includeHtml;
+        this.verbose = verbose;
+    }
+    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 = (0, utils_1.describeViolations)(violations).map(({ target, html, violations }) => {
+                        if (!this.includeHtml) {
+                            return {
+                                target,
+                                violations,
+                            };
+                        }
+                        return { target, html, violations };
+                    });
+                    // per node
+                    console.table(nodeViolations);
+                }
+            }
+            else {
+                this.verbose && console.log(`No accessibility violations detected!`);
+            }
+        });
+    }
+}
+exports.default = DefaultTerminalReporter;

package/dist/reporter/junitReporter.d.ts

@@ -0,0 +1,10 @@
+import Reporter from '../types';
+import { Result } from 'axe-core';
+import { Page } from 'playwright';
+export default class JUnitReporter implements Reporter {
+    protected verbose: boolean | undefined;
+    protected page: Page | undefined;
+    protected outputFilename: string | undefined;
+    constructor(verbose: boolean | undefined, page: Page | undefined, outputFilename: string | undefined);
+    report(violations: Result[]): Promise<void>;
+}

package/dist/reporter/junitReporter.js

@@ -0,0 +1,104 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+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());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const junit_report_builder_1 = __importDefault(require("junit-report-builder"));
+const assert_1 = __importDefault(require("assert"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+class JUnitReporter {
+    constructor(verbose, page, outputFilename) {
+        this.verbose = verbose;
+        this.page = page;
+        this.outputFilename = outputFilename;
+    }
+    report(violations) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            let lineBreak = '\n';
+            let pageUrl = ((_a = this.page) === null || _a === void 0 ? void 0 : _a.url()) || 'Page';
+            let suite = junit_report_builder_1.default.testSuite().name(pageUrl);
+            const message = violations.length === 0
+                ? 'No accessibility violations detected!'
+                : `Found ${violations.length} accessibility violations`;
+            violations.map((violation) => {
+                const errorBody = violation.nodes
+                    .map((node) => {
+                    const selector = node.target.join(', ');
+                    const expectedText = `Expected the HTML found at $('${selector}') to have no violations:` +
+                        '\n';
+                    return (expectedText +
+                        node.html +
+                        lineBreak +
+                        `Received:\n` +
+                        `${violation.help} (${violation.id})` +
+                        lineBreak +
+                        node.failureSummary +
+                        lineBreak +
+                        (violation.helpUrl
+                            ? `You can find more information on this issue here: \n${violation.helpUrl}`
+                            : '') +
+                        '\n');
+                })
+                    .join(lineBreak);
+                suite
+                    .testCase()
+                    .className(violation.id)
+                    .name(violation.description)
+                    .failure(errorBody);
+            });
+            const pass = violations.length === 0;
+            if (pass) {
+                junit_report_builder_1.default.testCase().name('Accesibility testing - A11Y');
+                this.verbose && console.log(`No accessibility violations detected!`);
+            }
+            let location = this.outputFilename || 'a11y-tests.xml';
+            const dir = path.dirname(location);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            // Check if the file exists, if not create it
+            if (!fs.existsSync(location)) {
+                fs.writeFileSync(location, ''); // Create an empty file
+            }
+            junit_report_builder_1.default.writeTo(location);
+            if (!pass) {
+                assert_1.default.fail(message);
+            }
+        });
+    }
+}
+exports.default = JUnitReporter;

package/dist/reporter/terminalReporterV2.d.ts

@@ -0,0 +1,7 @@
+import Reporter from '../types';
+import { Result } from 'axe-core';
+export default class TerminalReporterV2 implements Reporter {
+    protected verbose: boolean | undefined;
+    constructor(verbose: boolean | undefined);
+    report(violations: Result[]): Promise<void>;
+}

package/dist/reporter/terminalReporterV2.js

@@ -0,0 +1,69 @@
+"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());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const assert_1 = __importDefault(require("assert"));
+const picocolors_1 = __importDefault(require("picocolors"));
+class TerminalReporterV2 {
+    constructor(verbose) {
+        this.verbose = verbose;
+    }
+    report(violations) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const lineBreak = '\n\n';
+            const message = violations.length === 0
+                ? 'No accessibility violations detected!'
+                : `Found ${violations.length} accessibility violations: \n`;
+            const horizontalLine = picocolors_1.default.bold('-'.repeat(message.length));
+            const reporter = (violations) => {
+                if (violations.length === 0) {
+                    return [];
+                }
+                return violations
+                    .map((violation) => {
+                    const errorBody = violation.nodes
+                        .map((node) => {
+                        const selector = node.target.join(', ');
+                        const expectedText = `Expected the HTML found at $('${selector}') to have no violations:` +
+                            '\n';
+                        return (picocolors_1.default.bold(expectedText) +
+                            picocolors_1.default.gray(node.html) +
+                            lineBreak +
+                            `Received:\n` +
+                            picocolors_1.default.red(`${violation.help} (${violation.id})`) +
+                            lineBreak +
+                            picocolors_1.default.bold(picocolors_1.default.yellow(node.failureSummary)) +
+                            lineBreak +
+                            (violation.helpUrl
+                                ? `You can find more information on this issue here: \n${picocolors_1.default.bold(picocolors_1.default.blue(violation.helpUrl))}`
+                                : '') +
+                            '\n' +
+                            horizontalLine);
+                    })
+                        .join(lineBreak);
+                    return errorBody;
+                })
+                    .join(lineBreak);
+            };
+            const formatedViolations = reporter(violations);
+            const pass = formatedViolations.length === 0;
+            if (pass) {
+                this.verbose && console.log(message);
+            }
+            else {
+                assert_1.default.fail(message + horizontalLine + '\n' + formatedViolations);
+            }
+        });
+    }
+}
+exports.default = TerminalReporterV2;

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+import { Result, Check, ImpactValue, Locale, Rule, RunOptions } from 'axe-core';
+export interface NodeViolation {
+    target: string;
+    html: string;
+    violations: string;
+}
+export interface Aggregate {
+    [key: string]: {
+        target: string;
+        html: string;
+        violations: number[];
+    };
+}
+export default interface Reporter {
+    report(violations: Result[]): Promise<void>;
+}
+export interface axeOptionsConfig {
+    axeOptions?: RunOptions;
+}
+export interface ConfigOptions {
+    branding?: {
+        brand?: string;
+        application?: string;
+    };
+    reporter?: 'v1' | 'v2' | 'no-passes';
+    checks?: Check[];
+    rules?: Rule[];
+    locale?: Locale;
+    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>;
+}
+export type AxeOptions = {
+    includedImpacts?: ImpactValue[];
+    detailedReport?: boolean;
+    detailedReportOptions?: {
+        html?: boolean;
+    };
+    verbose?: boolean;
+} & axeOptionsConfig;

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils.d.ts

@@ -0,0 +1,5 @@
+import { NodeViolation } from './types';
+import { ImpactValue, Result } from 'axe-core';
+export declare const getImpactedViolations: (violations: Result[], includedImpacts?: ImpactValue[]) => Result[];
+export declare const testResultDependsOnViolations: (violations: Result[], skipFailures: boolean) => void;
+export declare const describeViolations: (violations: Result[]) => NodeViolation[];

package/dist/utils.js

@@ -0,0 +1,49 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeViolations = exports.testResultDependsOnViolations = exports.getImpactedViolations = void 0;
+const assert_1 = __importDefault(require("assert"));
+const getImpactedViolations = (violations, includedImpacts = []) => {
+    return Array.isArray(includedImpacts) && includedImpacts.length
+        ? violations.filter((v) => v.impact && includedImpacts.includes(v.impact))
+        : violations;
+};
+exports.getImpactedViolations = getImpactedViolations;
+const testResultDependsOnViolations = (violations, skipFailures) => {
+    if (!skipFailures) {
+        assert_1.default.strictEqual(violations.length, 0, `${violations.length} accessibility violation${violations.length === 1 ? '' : 's'} ${violations.length === 1 ? 'was' : 'were'} detected`);
+    }
+    else {
+        if (violations.length) {
+            console.warn({
+                name: 'a11y violation summary',
+                message: `${violations.length} accessibility violation${violations.length === 1 ? '' : 's'} ${violations.length === 1 ? 'was' : 'were'} detected`,
+            });
+        }
+    }
+};
+exports.testResultDependsOnViolations = testResultDependsOnViolations;
+const describeViolations = (violations) => {
+    const aggregate = {};
+    violations.map(({ nodes }, index) => {
+        nodes.forEach(({ target, html }) => {
+            const key = JSON.stringify(target) + html;
+            if (aggregate[key]) {
+                aggregate[key].violations.push(index);
+            }
+            else {
+                aggregate[key] = {
+                    target: JSON.stringify(target),
+                    html,
+                    violations: [index],
+                };
+            }
+        });
+    });
+    return Object.values(aggregate).map(({ target, html, violations }) => {
+        return { target, html, violations: JSON.stringify(violations) };
+    });
+};
+exports.describeViolations = describeViolations;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axe-playwright",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Custom Playwright commands to inject axe-core and test for a11y",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",