@sa11y/jest 4.0.0 → 4.1.0

package/dist/automatic.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Options for Automatic checks to be passed to {@link registerSa11yAutomaticChecks}
+ */
+export type AutoCheckOpts = {
+    runAfterEach?: boolean;
+    cleanupAfterEach?: boolean;
+    consolidateResults?: boolean;
+    filesFilter?: string[];
+};
+/**
+ * Check if current test file needs to be skipped based on any provided filter
+ */
+export declare function skipTest(testPath: string | undefined, filesFilter?: string[]): boolean;
+/**
+ * Run accessibility check on each element node in the body using {@link toBeAccessible}
+ * @param opts - Options for automatic checks {@link AutoCheckOpts}
+ */
+export declare function automaticCheck(opts?: AutoCheckOpts): Promise<void>;
+/**
+ * Register accessibility checks to be run automatically after each test
+ * @param opts - Options for automatic checks {@link AutoCheckOpts}
+ */
+export declare function registerSa11yAutomaticChecks(opts?: AutoCheckOpts): void;
+//# sourceMappingURL=automatic.d.ts.map

package/dist/automatic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automatic.d.ts","sourceRoot":"","sources":["../src/automatic.ts"],"names":[],"mappings":"AAaA;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAI7B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AAYF;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAUtF;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,IAAI,GAAE,aAAoC,GAAG,OAAO,CAAC,IAAI,CAAC,CA+B9F;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,GAAE,aAAoC,GAAG,IAAI,CAM7F"}

package/dist/automatic.js

@@ -0,0 +1,87 @@
+"use strict";
+/*
+ * Copyright (c) 2021, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSa11yAutomaticChecks = exports.automaticCheck = exports.skipTest = void 0;
+const common_1 = require("@sa11y/common");
+const assert_1 = require("@sa11y/assert");
+const format_1 = require("@sa11y/format");
+const matcher_1 = require("./matcher");
+const globals_1 = require("@jest/globals");
+/**
+ * Default options when {@link registerSa11yAutomaticChecks} is invoked
+ */
+const defaultAutoCheckOpts = {
+    runAfterEach: true,
+    cleanupAfterEach: true,
+    consolidateResults: true,
+    filesFilter: [],
+};
+/**
+ * Check if current test file needs to be skipped based on any provided filter
+ */
+function skipTest(testPath, filesFilter) {
+    if (!testPath || !filesFilter || !(filesFilter?.length > 0))
+        return false;
+    const skipTest = filesFilter.some((fileName) => testPath.toLowerCase().includes(fileName.toLowerCase()));
+    if (skipTest) {
+        (0, common_1.log)(`Skipping automatic accessibility check on ${testPath} as it matches given files filter: ${filesFilter.toString()}`);
+    }
+    return skipTest;
+}
+exports.skipTest = skipTest;
+/**
+ * Run accessibility check on each element node in the body using {@link toBeAccessible}
+ * @param opts - Options for automatic checks {@link AutoCheckOpts}
+ */
+async function automaticCheck(opts = defaultAutoCheckOpts) {
+    if (skipTest(globals_1.expect.getState().testPath, opts.filesFilter))
+        return;
+    // Skip automatic check if test is using fake timer as it would result in timeout
+    if ((0, matcher_1.isTestUsingFakeTimer)()) {
+        (0, common_1.log)('Skipping automatic accessibility check as Jest fake timer is in use.');
+        return;
+    }
+    const violations = [];
+    // Create a DOM walker filtering only elements (skipping text, comment nodes etc)
+    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT);
+    let currNode = walker.firstChild();
+    try {
+        while (currNode !== null) {
+            // TODO (spike): Use a logger lib with log levels selectable at runtime
+            // console.log(
+            //     `♿ [DEBUG] Automatically checking a11y of ${currNode.nodeName}
+            //      for test "${expect.getState().currentTestName}"
+            //      : ${testPath}`
+            // );
+            violations.push(...(await (0, assert_1.getViolationsJSDOM)(currNode)));
+            currNode = walker.nextSibling();
+        }
+    }
+    finally {
+        if (opts.cleanupAfterEach)
+            document.body.innerHTML = ''; // remove non-element nodes
+        // TODO (spike): Disable stack trace for automatic checks.
+        //  Will this affect all errors globally?
+        // Error.stackTraceLimit = 0;
+        format_1.A11yError.checkAndThrow(violations, { deduplicate: opts.consolidateResults });
+    }
+}
+exports.automaticCheck = automaticCheck;
+/**
+ * Register accessibility checks to be run automatically after each test
+ * @param opts - Options for automatic checks {@link AutoCheckOpts}
+ */
+function registerSa11yAutomaticChecks(opts = defaultAutoCheckOpts) {
+    if (opts.runAfterEach) {
+        // TODO (fix): Make registration idempotent
+        (0, common_1.log)('Registering sa11y checks to be run automatically after each test');
+        afterEach(() => automaticCheck(opts));
+    }
+}
+exports.registerSa11yAutomaticChecks = registerSa11yAutomaticChecks;
+//# sourceMappingURL=automatic.js.map

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import resultsProcessor from './resultsProcessor';
+export { toBeAccessible } from './matcher';
+export { registerSa11yMatcher, setup } from './setup';
+export { resultsProcessor };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,gBAAgB,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resultsProcessor = exports.setup = exports.registerSa11yMatcher = exports.toBeAccessible = void 0;
+/*
+ * Copyright (c) 2020, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+const resultsProcessor_1 = __importDefault(require("./resultsProcessor"));
+exports.resultsProcessor = resultsProcessor_1.default;
+var matcher_1 = require("./matcher");
+Object.defineProperty(exports, "toBeAccessible", { enumerable: true, get: function () { return matcher_1.toBeAccessible; } });
+var setup_1 = require("./setup");
+Object.defineProperty(exports, "registerSa11yMatcher", { enumerable: true, get: function () { return setup_1.registerSa11yMatcher; } });
+Object.defineProperty(exports, "setup", { enumerable: true, get: function () { return setup_1.setup; } });
+//# sourceMappingURL=index.js.map

package/dist/matcher.d.ts

@@ -0,0 +1,24 @@
+/// <reference types="jest" />
+import { A11yCheckableContext } from '@sa11y/assert';
+import { A11yConfig } from '@sa11y/common';
+declare global {
+    namespace jest {
+        interface Matchers<R> extends jest.CustomMatcher {
+            toBeAccessible(config?: A11yConfig): Promise<CustomMatcherResult>;
+        }
+    }
+}
+/**
+ * Jest expect matcher to check DOM for accessibility issues
+ * @param received - DOM or HTML Element to be tested for accessibility. Defaults to current DOM.
+ * @param config - A11yConfig to be used to test for accessibility. Defaults to `base` ruleset.
+ */
+export declare function toBeAccessible(received?: A11yCheckableContext, config?: A11yConfig): Promise<jest.CustomMatcherResult>;
+/**
+ * Detect if fake timer is being used in a jest test.
+ * Fake timers result in axe timeout https://github.com/dequelabs/axe-core/issues/3055
+ * Workaround until underlying issue can be fixed in axe.
+ * Ref: https://github.com/facebook/jest/issues/10555
+ */
+export declare function isTestUsingFakeTimer(): boolean;
+//# sourceMappingURL=matcher.d.ts.map

package/dist/matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matcher.d.ts","sourceRoot":"","sources":["../src/matcher.ts"],"names":[],"mappings":";AASA,OAAO,EAAE,oBAAoB,EAAoB,MAAM,eAAe,CAAC;AAGvE,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAI3C,OAAO,CAAC,MAAM,CAAC;IAEX,UAAU,IAAI,CAAC;QAEX,UAAU,QAAQ,CAAC,CAAC,CAAE,SAAQ,IAAI,CAAC,aAAa;YAC5C,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;SACrE;KACJ;CACJ;AAeD;;;;GAIG;AACH,wBAAsB,cAAc,CAChC,QAAQ,GAAE,oBAA+B,EACzC,MAAM,GAAE,UAA2B,GACpC,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CA8BnC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAO9C"}

package/dist/matcher.js

@@ -0,0 +1,71 @@
+"use strict";
+/*
+ * Copyright (c) 2020, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTestUsingFakeTimer = exports.toBeAccessible = void 0;
+const jest_matcher_utils_1 = require("jest-matcher-utils");
+const setup_1 = require("./setup");
+const assert_1 = require("@sa11y/assert");
+const format_1 = require("@sa11y/format");
+const preset_rules_1 = require("@sa11y/preset-rules");
+const fakeTimerErrMsg = 'Cannot run accessibility check when Jest fake timer is in use. ' +
+    'Switch to real timer before invoking accessibility check. ' +
+    'Ref: https://jestjs.io/docs/timer-mocks';
+const matcherHintMsg = `expected document to have no accessibility violations but found`;
+const expectedMsg = `0 issues`;
+const formatOptions = {
+    a11yViolationIndicator: '⭕',
+    helpUrlIndicator: '🔗',
+    highlighter: jest_matcher_utils_1.printReceived,
+    deduplicate: false,
+};
+/**
+ * Jest expect matcher to check DOM for accessibility issues
+ * @param received - DOM or HTML Element to be tested for accessibility. Defaults to current DOM.
+ * @param config - A11yConfig to be used to test for accessibility. Defaults to `base` ruleset.
+ */
+async function toBeAccessible(received = document, config = preset_rules_1.defaultRuleset) {
+    let isAccessible = true;
+    // a11yError can be 'undefined' when used with `not` matcher and there is no error
+    let a11yError = new format_1.A11yError([], []);
+    let receivedMsg = expectedMsg;
+    if (isTestUsingFakeTimer())
+        throw new Error(fakeTimerErrMsg);
+    // TODO (Improvement): Can we detect if this is invoked async and error if not ?
+    try {
+        await (0, assert_1.assertAccessible)(received, (0, setup_1.adaptA11yConfig)(config));
+    }
+    catch (e) {
+        if (e instanceof format_1.A11yError) {
+            a11yError = e;
+            isAccessible = false;
+            receivedMsg = `${a11yError.length} issues`;
+        }
+        else {
+            throw e;
+        }
+    }
+    return {
+        pass: isAccessible,
+        message: () => (0, jest_matcher_utils_1.matcherHint)(`${toBeAccessible.name}: ${matcherHintMsg} ${receivedMsg}: \n\n ${a11yError.format(formatOptions)}`, `${a11yError.length} issues`, expectedMsg),
+    };
+}
+exports.toBeAccessible = toBeAccessible;
+/**
+ * Detect if fake timer is being used in a jest test.
+ * Fake timers result in axe timeout https://github.com/dequelabs/axe-core/issues/3055
+ * Workaround until underlying issue can be fixed in axe.
+ * Ref: https://github.com/facebook/jest/issues/10555
+ */
+function isTestUsingFakeTimer() {
+    return (typeof jest !== 'undefined' &&
+        typeof setTimeout !== 'undefined' &&
+        // eslint-disable-next-line no-prototype-builtins
+        (setTimeout.hasOwnProperty('_isMockFunction') || setTimeout.hasOwnProperty('clock')));
+}
+exports.isTestUsingFakeTimer = isTestUsingFakeTimer;
+//# sourceMappingURL=matcher.js.map

package/dist/resultsProcessor.d.ts

@@ -0,0 +1,10 @@
+import { AggregatedResult } from '@jest/test-result';
+/**
+ * Custom results processor for a11y results. Only affects JSON results file output.
+ * To be used with jest cli options --json --outputFile
+ *  e.g. jest --json --outputFile jestResults.json --testResultsProcessor `node_modules/@sa11y/jest/dist/resultsProcessor.js`
+ * Ref: https://jestjs.io/docs/configuration#testresultsprocessor-string
+ *  - Mapping of AggregatedResult to JSON format to https://github.com/facebook/jest/blob/master/packages/jest-test-result/src/formatTestResults.ts
+ */
+export default function resultsProcessor(results: AggregatedResult): AggregatedResult;
+//# sourceMappingURL=resultsProcessor.d.ts.map

package/dist/resultsProcessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resultsProcessor.d.ts","sourceRoot":"","sources":["../src/resultsProcessor.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,gBAAgB,EAAiE,MAAM,mBAAmB,CAAC;AAuFpH;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CAyBpF"}

package/dist/resultsProcessor.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/*
+ * Copyright (c) 2021, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+const test_result_1 = require("@jest/test-result");
+const common_1 = require("@sa11y/common");
+const format_1 = require("@sa11y/format");
+// Used by downstream CI workflows to separate file/classname from attached WCAG metadata
+const metadataSeparator = '::';
+// Map of test suite name to test results
+const consolidatedErrors = new Map();
+/**
+ * Create a test failure result with a11y meta-data at forefront from given test failure
+ * with a11y error.
+ */
+function createA11yTestResult(testResult, a11yResult) {
+    return {
+        ...testResult,
+        // TODO (refactor): extract formatting into its own function.
+        //  - Can this satisfy Formatter interface?
+        //  - Be part of format? (FileFormatter vs ConsoleFormatter)?
+        fullName: `${a11yResult.description}${metadataSeparator}${a11yResult.selectors}`,
+        failureMessages: [
+            `${common_1.errMsgHeader}: ${a11yResult.description}
+Help: ${a11yResult.helpUrl}
+CSS Selectors: ${a11yResult.selectors}
+HTML element: ${a11yResult.html}
+Tests: "${testResult.fullName}"
+Summary: ${a11yResult.summary}`, // TODO (refactor): replace with array of tests when consolidating? But we reach here after de-duping a11y results?
+        ],
+        // We don't need the error objects anymore as they have been processed
+        failureDetails: [],
+        // Add all test's having the same a11y issue
+        ancestorTitles: [...new Set(testResult.ancestorTitles).add(testResult.fullName)],
+    };
+}
+/**
+ * Convert any a11y errors from test failures into their own test suite, results
+ */
+function processA11yErrors(testSuite, testResult) {
+    const suiteName = testSuite.testFilePath;
+    testResult.failureDetails.forEach((failure) => {
+        let error = failure.error;
+        // If using circus test runner https://github.com/facebook/jest/issues/11405#issuecomment-843549606
+        // TODO (code cov): Add test data covering the case for circus test runner
+        /* istanbul ignore next */
+        if (error === undefined)
+            error = failure;
+        if (error.name === format_1.A11yError.name) {
+            // TODO (spike) : What happens if there are ever multiple failureDetails?
+            //  Ideally there shouldn't be as test execution should be stopped on failure
+            format_1.A11yResults.add(error.a11yResults, suiteName).forEach((a11yResult) => {
+                const className = `${suiteName}${metadataSeparator}${a11yResult.wcag}`;
+                // TODO (code cov): Fix - should be covered by existing tests
+                /* istanbul ignore next */
+                if (!Array.isArray(consolidatedErrors.get(className)))
+                    consolidatedErrors.set(className, []);
+                consolidatedErrors.get(className)?.push(createA11yTestResult(testResult, a11yResult));
+            });
+        }
+    });
+}
+/**
+ * Modify existing test result containing a11y error after a11y error
+ *  is extracted into its own test result using {@link createA11yTestResult}.
+ */
+function modifyOriginalTestResult(results, testSuite, testResult) {
+    // Don't report the failure twice
+    testResult.status = 'disabled';
+    // TODO (fix): Remove sa11y msg from test suite message.
+    //  ANSI codes and test names in suite message makes it difficult.
+    //  Removing error from test result doesn't affect test suite error msg.
+    // testResult.failureMessages = [];
+    // testResult.failureDetails = [];
+    // testSuite.failureMessage = '';
+    // Suites with only a11y errors should be marked as passed
+    testSuite.numFailingTests -= 1;
+    results.numFailedTests -= 1;
+    if (testSuite.numFailingTests === 0)
+        results.numFailedTestSuites -= 1;
+    // TODO(debug): Does 'success' represent only failed tests?
+    //  Or errored tests as well e.g.?
+    // if (results.numFailedTestSuites === 0) results.success = true;
+}
+/**
+ * Custom results processor for a11y results. Only affects JSON results file output.
+ * To be used with jest cli options --json --outputFile
+ *  e.g. jest --json --outputFile jestResults.json --testResultsProcessor `node_modules/@sa11y/jest/dist/resultsProcessor.js`
+ * Ref: https://jestjs.io/docs/configuration#testresultsprocessor-string
+ *  - Mapping of AggregatedResult to JSON format to https://github.com/facebook/jest/blob/master/packages/jest-test-result/src/formatTestResults.ts
+ */
+function resultsProcessor(results) {
+    // TODO (refactor): Use map/filter to get results directly without global var for consolidated errors
+    (0, common_1.log)(`Processing ${results.numTotalTests} tests ..`);
+    results.testResults // suite results
+        .filter((testSuite) => testSuite.numFailingTests > 0)
+        .forEach((testSuite) => {
+        testSuite.testResults // individual test results
+            .filter((testResult) => testResult.status === 'failed')
+            .forEach((testResult) => {
+            processA11yErrors(testSuite, testResult);
+            modifyOriginalTestResult(results, testSuite, testResult);
+        });
+    });
+    (0, common_1.log)(`Transforming a11y failures from ${consolidatedErrors.size} suites ..`);
+    consolidatedErrors.forEach((testResults, suiteKey) => {
+        const sa11ySuite = (0, test_result_1.createEmptyTestResult)();
+        // "testFilePath" gets output as suite "name" in formatted JSON result
+        sa11ySuite.testFilePath = suiteKey;
+        sa11ySuite.testResults = testResults;
+        sa11ySuite.numFailingTests = testResults.length;
+        (0, test_result_1.addResult)(results, sa11ySuite);
+    });
+    return results;
+}
+exports.default = resultsProcessor;
+// The processor must be a node module that exports a function
+module.exports = resultsProcessor;
+//# sourceMappingURL=resultsProcessor.js.map

package/dist/setup.d.ts

@@ -0,0 +1,23 @@
+import { A11yConfig } from '@sa11y/common';
+import { AutoCheckOpts } from './automatic';
+export declare const disabledRules: string[];
+/**
+ * Options to be passed on to {@link setup}
+ */
+export type Sa11yOpts = {
+    autoCheckOpts: AutoCheckOpts;
+};
+/**
+ * Register Sa11y Jest API and automatic checks depending on {@link Sa11yOpts}
+ * @param opts - {@link Sa11yOpts} to opt-in to automatic checks
+ */
+export declare function setup(opts?: Sa11yOpts): void;
+/**
+ * Register accessibility helpers toBeAccessible as jest matchers
+ */
+export declare function registerSa11yMatcher(): void;
+/**
+ * Customize sa11y preset rules specific to JSDOM
+ */
+export declare function adaptA11yConfig(config: A11yConfig, filterRules?: string[]): A11yConfig;
+//# sourceMappingURL=setup.d.ts.map

package/dist/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAgC,MAAM,aAAa,CAAC;AAG1E,eAAO,MAAM,aAAa,UAiBzB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACpB,aAAa,EAAE,aAAa,CAAC;CAKhC,CAAC;AAaF;;;GAGG;AACH,wBAAgB,KAAK,CAAC,IAAI,GAAE,SAA4B,GAAG,IAAI,CAW9D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAU3C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,WAAgB,GAAG,UAAU,CAK3F"}

package/dist/setup.js

@@ -0,0 +1,82 @@
+"use strict";
+/*
+ * Copyright (c) 2020, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adaptA11yConfig = exports.registerSa11yMatcher = exports.setup = exports.disabledRules = void 0;
+const matcher_1 = require("./matcher");
+const automatic_1 = require("./automatic");
+const globals_1 = require("@jest/globals");
+exports.disabledRules = [
+    // Descendancy checks that would fail at unit/component level, but pass at page level
+    'aria-required-children',
+    'aria-required-parent',
+    'dlitem',
+    'definition-list',
+    'list',
+    'listitem',
+    'landmark-one-main',
+    // color-contrast doesn't work for JSDOM and might affect performance
+    //  https://github.com/dequelabs/axe-core/issues/595
+    //  https://github.com/dequelabs/axe-core/blob/develop/doc/examples/jsdom/test/a11y.js
+    'color-contrast',
+    // audio, video elements are stubbed out in JSDOM
+    //  https://github.com/jsdom/jsdom/issues/2155
+    'audio-caption',
+    'video-caption',
+];
+/**
+ * Default options for sa11y jest matcher
+ */
+const defaultSa11yOpts = {
+    autoCheckOpts: {
+        runAfterEach: false,
+        cleanupAfterEach: false,
+        consolidateResults: false,
+    },
+};
+/**
+ * Register Sa11y Jest API and automatic checks depending on {@link Sa11yOpts}
+ * @param opts - {@link Sa11yOpts} to opt-in to automatic checks
+ */
+function setup(opts = defaultSa11yOpts) {
+    registerSa11yMatcher();
+    // Set defaults from env vars
+    const autoCheckOpts = opts.autoCheckOpts;
+    autoCheckOpts.runAfterEach || (autoCheckOpts.runAfterEach = !!process.env.SA11Y_AUTO);
+    // Consolidate results if automatic checks is enabled
+    autoCheckOpts.consolidateResults || (autoCheckOpts.consolidateResults = autoCheckOpts.runAfterEach);
+    autoCheckOpts.cleanupAfterEach || (autoCheckOpts.cleanupAfterEach = !!process.env.SA11Y_CLEANUP);
+    if (process.env.SA11Y_AUTO_FILTER?.trim().length)
+        autoCheckOpts.filesFilter || (autoCheckOpts.filesFilter = process.env.SA11Y_AUTO_FILTER.split(','));
+    (0, automatic_1.registerSa11yAutomaticChecks)(autoCheckOpts);
+}
+exports.setup = setup;
+/**
+ * Register accessibility helpers toBeAccessible as jest matchers
+ */
+function registerSa11yMatcher() {
+    if (globals_1.expect !== undefined) {
+        globals_1.expect.extend({ toBeAccessible: matcher_1.toBeAccessible });
+    }
+    else {
+        throw new Error("Unable to find Jest's expect function." +
+            '\nPlease check your Jest installation and that you have added @sa11y/jest correctly to your jest configuration.' +
+            '\nSee https://github.com/salesforce/sa11y/tree/master/packages/jest#readme for help.');
+    }
+}
+exports.registerSa11yMatcher = registerSa11yMatcher;
+/**
+ * Customize sa11y preset rules specific to JSDOM
+ */
+function adaptA11yConfig(config, filterRules = exports.disabledRules) {
+    // TODO (refactor): Move into preset-rules pkg as a generic rules filter util
+    const adaptedConfig = JSON.parse(JSON.stringify(config));
+    adaptedConfig.runOnly.values = config.runOnly.values.filter((rule) => !filterRules.includes(rule));
+    return adaptedConfig;
+}
+exports.adaptA11yConfig = adaptA11yConfig;
+//# sourceMappingURL=setup.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sa11y/jest",
-    "version": "4.0.0",
+    "version": "4.1.0",
     "description": "Accessibility testing matcher for Jest",
     "license": "BSD-3-Clause",
     "homepage": "https://github.com/salesforce/sa11y/tree/master/packages/jest#readme",
@@ -24,9 +24,9 @@
     ],
     "dependencies": {
         "@jest/test-result": "^27",
-        "@sa11y/assert": "4.0.0",
-        "@sa11y/format": "4.0.0",
-        "@sa11y/preset-rules": "4.0.0",
+        "@sa11y/assert": "4.1.0",
+        "@sa11y/format": "4.1.0",
+        "@sa11y/preset-rules": "4.1.0",
         "jest-matcher-utils": "^27"
     },
     "peerDependencies": {
@@ -34,8 +34,8 @@
     },
     "devDependencies": {
         "@jest/globals": "28.1.3",
-        "@sa11y/common": "4.0.0",
-        "@sa11y/test-utils": "4.0.0"
+        "@sa11y/common": "4.1.0",
+        "@sa11y/test-utils": "4.1.0"
     },
     "publishConfig": {
         "access": "public"
@@ -43,5 +43,5 @@
     "engines": {
         "node": "^14 || ^16"
     },
-    "gitHead": "780b31a6d25fe42928d2fdd0d61b1e1e47f524e5"
+    "gitHead": "c2d36dc78a69b816b40d6c8af531786826115c13"
 }