Merge branch 'dequelabs:develop' into develop

.eslintrc.js

@@ -1,4 +1,5 @@
 module.exports = {
+  root: true,
   extends: ['prettier'],
   parserOptions: {
     ecmaVersion: 2021
@@ -70,6 +71,10 @@ module.exports = {
   overrides: [
     {
       files: ['lib/**/*.js'],
+      excludedFiles: [
+        'lib/core/reporters/**/*.js',
+        'lib/**/*-after.js'
+      ],
       parserOptions: {
         sourceType: 'module'
       },
@@ -87,6 +92,23 @@ module.exports = {
         'no-use-before-define': 'off'
       }
     },
+    {
+      // after functions and reporters will not be run inside the same context as axe.run so should not access browser globals that require context specific information (window.location, window.getComputedStyles, etc.)
+      files: [
+        'lib/**/*-after.js',
+        'lib/core/reporters/**/*.js'
+      ],
+      parserOptions: {
+        sourceType: 'module'
+      },
+      env: {},
+      globals: {},
+      rules: {
+        'func-names': [2, 'as-needed'],
+        'prefer-const': 2,
+        'no-use-before-define': 'off'
+      }
+    },
     {
       files: ['test/**/*.js'],
       parserOptions: {

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [4.3.3](https://github.com/dequelabs/axe-core/compare/v4.3.2...v4.3.3) (2021-08-24)
+
+### Bug Fixes
+
+- **aria-allowed-role:** Update allowed roles based on ARIA spec updates ([#3124](https://github.com/dequelabs/axe-core/issues/3124)) ([a1f637f](https://github.com/dequelabs/axe-core/commit/a1f637f3f5ebf0e483fd21865bd2191c24ccb87a))
+- **d.ts:** Add PartialResults type ([#3126](https://github.com/dequelabs/axe-core/issues/3126)) ([5cdaf01](https://github.com/dequelabs/axe-core/commit/5cdaf012a2f09834d8b7e5f3a645a40e61d47ea9))
+- **reporter:** Run inside isolated contexts ([#3129](https://github.com/dequelabs/axe-core/issues/3129)) ([98066f8](https://github.com/dequelabs/axe-core/commit/98066f8864d4ef09b4b3de12456992d3ca3207b4))
+
 ### [4.3.2](https://github.com/dequelabs/axe-core/compare/v4.3.1...v4.3.2) (2021-07-27)
 
 ### Bug Fixes

axe.d.ts

@@ -96,13 +96,8 @@ declare namespace axe {
     preload?: boolean;
     performanceTimer?: boolean;
   }
-  interface AxeResults {
+  interface AxeResults extends EnvironmentData {
     toolOptions: RunOptions;
-    testEngine: TestEngine;
-    testRunner: TestRunner;
-    testEnvironment: TestEnvironment;
-    url: string;
-    timestamp: string;
     passes: Result[];
     violations: Result[];
     incomplete: Result[];
@@ -262,7 +257,9 @@ declare namespace axe {
   interface PartialResult {
     frames: SerialDqElement[];
     results: PartialRuleResult[];
+    environmentData?: EnvironmentData;
   }
+  type PartialResults = Array<PartialResult | null>
   interface FrameContext {
     frameSelector: CrossTreeSelector;
     frameContext: ContextObject;
@@ -271,6 +268,13 @@ declare namespace axe {
     getFrameContexts: (context?: ElementContext) => FrameContext[];
     shadowSelect: (selector: CrossTreeSelector) => Element | null;
   }
+  interface EnvironmentData {
+    testEngine: TestEngine;
+    testRunner: TestRunner;
+    testEnvironment: TestEnvironment;
+    url: string;
+    timestamp: string;
+  }
 
   let version: string;
   let plugins: any;
@@ -333,7 +337,7 @@ declare namespace axe {
    * @param   {RunOptions}     options  Optional Options passed into rules or checks, temporarily modifying them.
    */
   function finishRun(
-    partialResults: Array<PartialResult | null>,
+    partialResults: PartialResults,
     options: RunOptions
   ): Promise<AxeResults>;
 

bower.json

@@ -1,6 +1,6 @@
 {
   "name": "axe-core",
-  "version": "4.3.2",
+  "version": "4.3.3",
   "contributors": [
     {
       "name": "David Sturley",

doc/run-partial.md

@@ -81,6 +81,13 @@ The `axe.utils.getFrameContexts` method takes any valid context, and returns an
 
 - `frameSelector`: This is a CSS selector, or array of CSS selectors in case of nodes in a shadow DOM tree to locate the frame element to be tested.
 - `frameContext`: This is an object is a context object that should be tested in the particular frame.
+
+## Custom Rulesets and Reporters
+
+Because `axe.finishRun` does not run inside the page, the `reporter` and `after` methods do not have access to the top-level `window` and `document` objects, and might not have access to common browser APIs. Axe-core reporter use the `environmentData` property that is set on the partialResult object of the initiator.
+
+Because of this constraint, custom reporters, and custom rulesets that add `after` methods must not rely on browser APIs or globals. Any data needed for either should either be taken from the `environmentData` property, or collected in an `evaluate` method of a check, and stored using its `.data()` method.
+
 ## Recommendations
 
 When building integrations with browser drivers using axe-core, it is safer and more stable to use `axe.runPartial` and `axe.finishRun` then to use `axe.run`. These two methods ensure that no information from one frame is ever handed off to another. That way if any script in a frame interferes with the `axe` object, or with `window.postMessage`, other frames will not be affected.

lib/core/core.js

@@ -22,7 +22,12 @@ import frameMessenger from './public/frame-messenger';
 import getRules from './public/get-rules';
 import load from './public/load';
 import registerPlugin from './public/plugins';
-import { hasReporter, getReporter, addReporter } from './public/reporter';
+import {
+  reporters,
+  hasReporter,
+  getReporter,
+  addReporter
+} from './public/reporter';
 import reset from './public/reset';
 import runRules from './public/run-rules';
 import runVirtualRule from './public/run-virtual-rule';
@@ -62,6 +67,9 @@ axe._thisWillBeDeletedDoNotUse.base = {
   Rule,
   metadataFunctionMap
 };
+axe._thisWillBeDeletedDoNotUse.public = {
+  reporters
+};
 
 axe.imports = imports;
 

lib/core/public/finish-run.js

@@ -9,6 +9,7 @@ import {
 
 export default function finishRun(partialResults, options = {}) {
   options = clone(options);
+  const { environmentData } = partialResults.find(r => r.environmentData) || {}
 
   // normalize the runOnly option for the output of reporters toolOptions
   axe._audit.normalizeOptions(options);
@@ -20,7 +21,7 @@ export default function finishRun(partialResults, options = {}) {
   results.forEach(publishMetaData);
   results = results.map(finalizeRuleResult);
 
-  return createReport(results, options);
+  return createReport(results, { environmentData, ...options });
 }
 
 function setFrameSpec(partialResults) {

lib/core/public/reporter.js

@@ -1,4 +1,4 @@
-const reporters = {};
+export const reporters = {};
 let defaultReporter;
 
 export function hasReporter(reporterName) {

lib/core/public/run-partial.js

@@ -1,6 +1,6 @@
 import Context from '../base/context';
 import teardown from './teardown';
-import { DqElement, getSelectorData, assert } from '../utils';
+import { DqElement, getSelectorData, assert, getEnvironmentData } from '../utils';
 import normalizeRunParams from './run/normalize-run-params';
 
 export default function runPartial(...args) {
@@ -28,7 +28,12 @@ export default function runPartial(...args) {
       const frames = contextObj.frames.map(({ node }) => {
         return new DqElement(node, options).toJSON();
       });
-      return { results, frames };
+      let environmentData;
+      if (contextObj.initiator) {
+        environmentData = getEnvironmentData();
+      }
+
+      return { results, frames, environmentData };
     })
     .finally(() => {
       axe._running = false;

lib/core/public/run-virtual-rule.js

@@ -5,6 +5,7 @@ import {
   publishMetaData,
   finalizeRuleResult,
   aggregateResult,
+  getEnvironmentData,
   getRule
 } from '../utils';
 
@@ -54,7 +55,7 @@ function runVirtualRule(ruleId, vNode, options = {}) {
   );
 
   return {
-    ...helpers.getEnvironmentData(),
+    ...getEnvironmentData(),
     ...results,
     toolOptions: options
   };

lib/core/reporters/helpers/index.js

@@ -1,5 +1,4 @@
 import failureSummary from './failure-summary';
-import getEnvironmentData from './get-environment-data';
 import incompleteFallbackMessage from './incomplete-fallback-msg';
 import processAggregate from './process-aggregate';
 
@@ -8,14 +7,12 @@ import processAggregate from './process-aggregate';
 axe._thisWillBeDeletedDoNotUse = axe._thisWillBeDeletedDoNotUse || {};
 axe._thisWillBeDeletedDoNotUse.helpers = {
   failureSummary,
-  getEnvironmentData,
   incompleteFallbackMessage,
   processAggregate
 };
 
 export {
   failureSummary,
-  getEnvironmentData,
   incompleteFallbackMessage,
   processAggregate
 };

lib/core/reporters/na.js

@@ -1,23 +1,20 @@
-import { processAggregate, getEnvironmentData } from './helpers';
+import { processAggregate } from './helpers';
+import { getEnvironmentData } from '../utils';
 
 const naReporter = (results, options, callback) => {
   console.warn(
     '"na" reporter will be deprecated in axe v4.0. Use the "v2" reporter instead.'
   );
-
   if (typeof options === 'function') {
     callback = options;
     options = {};
   }
 
-  var out = processAggregate(results, options);
+  const { environmentData, ...toolOptions } = options;
   callback({
-    ...getEnvironmentData(),
-    toolOptions: options,
-    violations: out.violations,
-    passes: out.passes,
-    incomplete: out.incomplete,
-    inapplicable: out.inapplicable
+    ...getEnvironmentData(environmentData),
+    toolOptions,
+    ...processAggregate(results, options)
   });
 };
 

lib/core/reporters/no-passes.js

@@ -1,19 +1,21 @@
-import { processAggregate, getEnvironmentData } from './helpers';
+import { processAggregate } from './helpers';
+import { getEnvironmentData } from '../utils';
 
 const noPassesReporter = (results, options, callback) => {
   if (typeof options === 'function') {
     callback = options;
     options = {};
   }
+  const { environmentData, ...toolOptions } = options;
   // limit result processing to types we want to include in the output
   options.resultTypes = ['violations'];
 
-  var out = processAggregate(results, options);
+  var { violations } = processAggregate(results, options);
 
   callback({
-    ...getEnvironmentData(),
-    toolOptions: options,
-    violations: out.violations
+    ...getEnvironmentData(environmentData),
+    toolOptions,
+    violations
   });
 };
 

lib/core/reporters/raw-env.js

@@ -1,17 +1,16 @@
-import { getEnvironmentData } from './helpers';
+import { getEnvironmentData } from '../utils';
 import rawReporter from './raw';
 
 const rawEnvReporter = (results, options, callback) => {
   if (typeof options === 'function') {
     callback = options;
     options = {};
   }
-  function rawCallback(raw) {
-    const env = getEnvironmentData();
+  const { environmentData, ...toolOptions } = options;
+  rawReporter(results, toolOptions, (raw) => {
+    const env = getEnvironmentData(environmentData);
     callback({ raw, env });
-  }
-
-  rawReporter(results, options, rawCallback);
+  });
 };
 
 export default rawEnvReporter;

lib/core/reporters/v1.js

@@ -1,15 +1,13 @@
-import {
-  processAggregate,
-  failureSummary,
-  getEnvironmentData
-} from './helpers';
+import { processAggregate, failureSummary } from './helpers';
+import { getEnvironmentData } from '../utils'
 
 const v1Reporter = (results, options, callback) => {
   if (typeof options === 'function') {
     callback = options;
     options = {};
-  }
-  var out = processAggregate(results, options);
+  };
+  const { environmentData, ...toolOptions } = options;
+  const out = processAggregate(results, options);
 
   const addFailureSummaries = result => {
     result.nodes.forEach(nodeResult => {
@@ -21,12 +19,9 @@ const v1Reporter = (results, options, callback) => {
   out.violations.forEach(addFailureSummaries);
 
   callback({
-    ...getEnvironmentData(),
-    toolOptions: options,
-    violations: out.violations,
-    passes: out.passes,
-    incomplete: out.incomplete,
-    inapplicable: out.inapplicable
+    ...getEnvironmentData(environmentData),
+    toolOptions,
+    ...out
   });
 };