Merge pull request #3025 from dequelabs/release-4.2.3

chore(release): 4.2.3

.circleci/config.yml

@@ -135,11 +135,13 @@ jobs:
       - checkout
       - <<: *restore_dependency_cache_unix
       - run: npm run build
-      # install Chrome Canary
+      # install Chrome Beta
       - run: |
-          wget https://dl.google.com/linux/direct/google-chrome-unstable_current_amd64.deb
-          sudo apt install ./google-chrome-unstable_current_amd64.deb
-      - run: npm run test -- --browsers ChromeCanary,FirefoxNightly
+          wget https://dl.google.com/linux/direct/google-chrome-beta_current_amd64.deb
+          sudo apt install ./google-chrome-beta_current_amd64.deb
+      - run: |
+          CHROME_BIN="$(which google-chrome-beta)" && echo "CHROME_BIN: $CHROME_BIN"
+          npm run test -- --browsers Chrome,FirefoxNightly
 
   # Test api docs can be built
   build_api_docs:

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 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.2.3](https://github.com/dequelabs/axe-core/compare/v4.2.2...v4.2.3) (2021-06-22)
+
+### Bug Fixes
+
+- **accText:** ignore text in embedded content elements ([#3022](https://github.com/dequelabs/axe-core/issues/3022)) ([8fb4635](https://github.com/dequelabs/axe-core/commit/8fb4635e01c82b80ff23994edad180dd73730a98)), closes [#3017](https://github.com/dequelabs/axe-core/issues/3017)
+- **color-contrast:** add special case for new sr-only technique ([#2985](https://github.com/dequelabs/axe-core/issues/2985)) ([79cbf01](https://github.com/dequelabs/axe-core/commit/79cbf0168bdb9311db2e31043ad36c20b77e39fe))
+- **color-contrast:** check for pseudo elements on element itself, not just parents ([#2980](https://github.com/dequelabs/axe-core/issues/2980)) ([3122550](https://github.com/dequelabs/axe-core/commit/3122550b1beaeafaac62c81fb47bcd4290ba266a))
+- **frame-tested:** run without respondable ([#2942](https://github.com/dequelabs/axe-core/issues/2942)) ([a1d725d](https://github.com/dequelabs/axe-core/commit/a1d725d5cdedc4bfd6ba69bb25aa0a1213fd63cf))
+- **publish-metadata:** use fail message for rules with reviewOnFail:true ([#2987](https://github.com/dequelabs/axe-core/issues/2987)) ([00fefa9](https://github.com/dequelabs/axe-core/commit/00fefa9bfb9479279afc89b2da45e748bace77d2))
+- **sri-history:** add backported releases ([#3004](https://github.com/dequelabs/axe-core/issues/3004)) ([0332e80](https://github.com/dequelabs/axe-core/commit/0332e806524ca9ca78512423a70eb80d623795eb))
+
 ### [4.2.2](https://github.com/dequelabs/axe-core/compare/v4.2.1...v4.2.2) (2021-06-03)
 
 ### Bug Fixes

README.md

@@ -16,7 +16,9 @@ Axe is an accessibility testing engine for websites and other HTML-based user in
 
 Axe-core has different types of rules, for WCAG 2.0 and 2.1 on level A and AA, as well as a number of best practices that help you identify common accessibility practices like ensuring every page has an `h1` heading, and to help you avoid "gotchas" in ARIA like where an ARIA attribute you used will get ignored.
 
-With axe-core, you can find **on average 57% of WCAG issues automatically**. Additionally, axe-core will return elements as "incomplete" where axe-core could not be certain, and manual review is needed. To further improve test coverage we recommend the [intelligent guided tests](https://www.youtube.com/watch?v=AtsX0dPCG_4&feature=youtu.be&ab_channel=DequeSystems) in the [axe Extension](https://www.deque.com/axe/browser-extensions/).
+With axe-core, you can find **on average 57% of WCAG issues automatically**. Additionally, axe-core will return elements as "incomplete" where axe-core could not be certain, and manual review is needed. 
+
+To catch bugs earlier in the development cycle we recommend using the [axe-linter vscode extension](https://marketplace.visualstudio.com/items?itemName=deque-systems.vscode-axe-linter). To improve test coverage even further we recommend the [intelligent guided tests](https://www.youtube.com/watch?v=AtsX0dPCG_4&feature=youtu.be&ab_channel=DequeSystems) in the [axe Extension](https://www.deque.com/axe/browser-extensions/).
 
 The complete list of rules, grouped WCAG level and best practice, can found in [doc/rule-descriptions.md](./doc/rule-descriptions.md).
 

axe.d.ts

@@ -318,20 +318,20 @@ declare namespace axe {
     open: (topicHandler: TopicHandler) => Close | void;
     post: (
       frameWindow: Window,
-      data: TopicData | ReplyData,
+      data: TopicData,
       replyHandler: ReplyHandler
-    ) => void;
+    ) => boolean | void;
   };
   type Close = Function;
-  type TopicHandler = (data: TopicData, responder?: Responder) => void;
-  type ReplyHandler = (data: ReplyData, responder?: Responder) => void;
+  type TopicHandler = (data: TopicData, responder: Responder) => void;
+  type ReplyHandler = (message: any | Error, keepalive: boolean, responder: Responder) => void;
   type Responder = (
-    message: any,
-    keepalive: boolean,
-    replyHandler: ReplyHandler
+    message: any | Error,
+    keepalive?: boolean,
+    replyHandler?: ReplyHandler
   ) => void;
-  type TopicData = { topic: String } & ReplyData;
-  type ReplyData = { channelId: String; message: any; keepAlive: Boolean };
+  type TopicData = { topic: string } & ReplyData;
+  type ReplyData = { channelId: string; message: any; keepalive: boolean };
 }
 
 export = axe;

bower.json

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

build/configure.js

@@ -273,7 +273,12 @@ function buildRules(grunt, options, commons, callback) {
 
     function parseFailureForRule(rule) {
       function hasFailure(definition, out) {
-        if (definition && definition.metadata && definition.metadata.impact) {
+        if (
+          !rule.reviewOnFail &&
+          definition &&
+          definition.metadata &&
+          definition.metadata.impact
+        ) {
           out = out || !!definition.metadata.messages.fail;
         }
         return out;
@@ -289,7 +294,10 @@ function buildRules(grunt, options, commons, callback) {
     function parseIncompleteForRule(rule) {
       function hasIncomplete(definition, out) {
         if (definition && definition.metadata && definition.metadata.impact) {
-          out = out || !!definition.metadata.messages.incomplete;
+          out =
+            out ||
+            !!definition.metadata.messages.incomplete ||
+            rule.reviewOnFail;
         }
         return out;
       }

doc/API.md

@@ -307,7 +307,7 @@ axe.run(context, options, (err, results) => {
 #### Parameters axe.run
 
 - [`context`](#context-parameter): (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`](#options-parameter): (optional) Set of options passed into rules or checks, temporarily modifying them. This contrasts with `axe.configure`, which is more permanent.
+- [`options`](#options-parameter): (optional) Set of options that change how `axe.run` works, including what rules will run. To pass options to specific checks, use `axe.configure`.
 - [`callback`](#callback-parameter): (optional) The callback function which receives either null or an [error result](#error-result) as the first parameter, and the [results object](#results-object) when analysis is completed successfully, or undefined if it did not.
 
 ##### Context Parameter

doc/frame-messenger.md

@@ -8,10 +8,13 @@ Tools like browser extensions and testing environments often have different chan
 axe.frameMessenger({
   // Called to initialize message handling
   open(topicHandler) {
+    // Map data from the bridge to topicHandler
+    function subscriber(frameWin, data, response) {
+      // Data deserializations / validation / etc. here
+      topicHandler(data, response);
+    }
     // Start listening for "axe-core" events
-    const unsubscribe = bridge.subscribe('axe-core', data => {
-      topicHandler(data);
-    });
+    const unsubscribe = bridge.subscribe('axe-core', subscriber);
     // Tell axe how to close the connection if it needs to
     return unsubscribe;
   },
@@ -34,10 +37,71 @@ axe.frameMessenger({
 
 The `topicHandler` function takes two arguments: the `data` object and a callback function that is called when the subscribed listener completes. The `data` object is exclusively passed data that can be serialized with `JSON.stringify()`, which depending on the system may need to be used.
 
-The `open` function can `return` an optional cleanup function, which is called when another frameMessenger is registered.
+The `open` function can `return` an optional `close` function. Axe-core will only ever have one frameMessenger open at a time. The `close` function is called when another frameMessenger is registered.
 
 ## axe.frameMessenger({ post })
 
-`post` is a function that dictates how axe-core communicates with frames. It is passed three arguments: `frameWindow`, which is the frames `contentWindow`, the `data` object, and a `replyHandler` that must be called when responses are received.
+`post` is a function that dictates how axe-core communicates with frames. It is passed three arguments: `frameWindow`, which is the frame's `contentWindow`, the `data` object, and a `replyHandler` that must be called when responses are received. To inform axe-core that no message was sent, return `false`. This informs axe-core not to await for the ping to time out.
+
+Currently, axe-core will only require `replyHandler` to be called once, so promises can also be used here. This may change in the future, so it is preferable to make it possible for `replyHandler` to be called multiple times. Some axe-core [plugins](plugins.md) may rely on this feature.
+
+A second frameMessenger feature available to plugins, but not used in axe-core by default is to reply to a reply. This works by passing `replyHandler` a `responder` callback as a second argument. This requires a different setup, in which callbacks are stored based on their `channelId` property.
+
+```js
+// store handlers based on channelId
+const channels = {};
+
+axe.frameMessenger({
+  post(frameWindow, data, replyHandler) {
+    // Store the handler so it can be called later
+    channels[data.channelId] = replyHandler;
+    // Send a message to the frame
+    bridge.send(frameWindow, data);
+  },
+
+  open(topicHandler) {
+    function subscriber(frameWin, data) {
+      const { channelId, message, keepalive } = data;
+      // Create a callback to invoke on a reply.
+      const responder = createResponder(frameWin, channelId);
+
+      // If there is a topic, pass it to the axe supplied topic-handler
+      if (data.topic) {
+        topicHandler(data, responder);
+
+        // If there is a replyHandler stored, invoke it
+      } else if (channels[channelId]) {
+        const replyHandler = channels[channelId];
+        replyHandler(message, keepalive, responder);
+
+        // Clean up replyHandler, as no further messages are expected
+        if (!keepalive) delete channels[channelId];
+      }
+    }
+
+    // Start listening for "axe-core" events
+    const unsubscribe = bridge.subscribe('axe-core', subscriber);
+    // Tell axe how to close the connection if it needs to
+    return unsubscribe;
+  }
+});
+
+// Return a function to be called when a reply is received
+function createResponder(frameWin, channelId) {
+  return function responder(message, keepalive, replyHandler) {
+    // Store the new reply handler, possibly replacing a previous one
+    //   to avoid receiving a message twice.
+    channels[channelId] = replyHandler;
+    // Send a message to the frame
+    bridge.send(frameWin, { channelId, message, keepalive });
+  };
+}
+```
+
+## Error handling & Timeouts
+
+If for some reason the frameMessenger fails to open, post, or close you should not throw an error. Axe-core will handle missing results by reporting on them in the `frame-tested` rule. It should not be possible for the `topicHandler` and `replyHandler` callbacks to throw an error. If this happens, please file an issue.
+
+Axe-core has a timeout mechanism built in, which pings frames to see if they respond before instructing them to run. There is no retry behavior in axe-core, which assumes that whatever channel is used is stable. If this isn't the case, this will need to be built into frameMessenger.
 
-**note**: Currently, axe-core will only call `replyHandler` once, so promises can also be used here. This may change in the future, so it is preferable to make it possible for `replyHandler` to be called multiple times.
+The `message` passed to responder may be an `Error`. If axe-core passes an `Error`, this should be propagated "as is". If this is not possible because the message needs to be serialized, a new `Error` object must be constructed as part of deserialization.

doc/projects.md

@@ -12,6 +12,8 @@ Add your project/integration to this file and submit a pull request.
 1. [axe-core/react](https://www.npmjs.com/package/@axe-core/react)
 1. [axe-core/cli](https://www.npmjs.com/package/@axe-core/cli)
 1. [axe-core/webdriverjs](https://www.npmjs.com/package/@axe-core/webdriverjs)
+1. [axe-core/webdriverio](https://www.npmjs.com/package/@axe-core/webdriverio)
+1. [axe-core/playwright](https://www.npmjs.com/package/@axe-core/playwright)
 1. [axe-core/puppeteer](https://www.npmjs.com/package/@axe-core/puppeteer)
 1. [axe-core-selenium (Java)](https://search.maven.org/artifact/com.deque.html.axe-core/selenium)
 1. [axe-core-capybara (Ruby)](https://rubygems.org/gems/axe-core-capybara/)