chore: Merge pull request #1719 from dequelabs/release-3.3.1

chore(release-3.3.1)
dequelabs · Jul 24, 2019 · 597304b · 597304b
2 parents 070f58a + 2b648e8
commit 597304b
Show file tree

Hide file tree

Showing 50 changed files with 499 additions and 213 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -65,6 +65,24 @@ jobs:
       - <<: *restore_dependency_cache
       - run: npm run test:examples
 
+  # Test locale files
+  test_locales:
+    <<: *defaults
+    steps:
+      - checkout
+      - <<: *restore_dependency_cache
+      - run: npm run build
+      - run: npm run test:locales
+
+  # Test newest axe-core version rule help docs are active (only on
+  # master prs)
+  test_rule_help_version:
+    <<: *defaults
+    steps:
+      - checkout
+      - <<: *restore_dependency_cache
+      - run: npm run test:rule-help-version
+
   # Release a "next" version
   next_release:
     <<: *defaults
@@ -117,12 +135,20 @@ workflows:
       - test_examples:
           requires:
             - test
+      - test_locales:
+          requires:
+            - test
+      - test_rule_help_version:
+          requires:
+            - test
       # Hold for approval
       - hold:
           type: approval
           requires:
             - test
             - test_examples
+            - test_locales
+            - test_rule_help_version
           filters:
             branches:
               only:
@@ -133,6 +159,7 @@ workflows:
             - dependencies
             - test
             - test_examples
+            - test_locales
           filters:
             branches:
               only: develop
@@ -142,6 +169,8 @@ workflows:
             - dependencies
             - test
             - test_examples
+            - test_locales
+            - test_rule_help_version
             - hold
           filters:
             branches:

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,7 +2,29 @@
 
 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.
 
-## [3.3.0](https://github.com/dequelabs/axe-core/compare/v3.2.2...v3.3.0) (2019-06-12)
+## [3.3.1](https://github.com/dequelabs/axe-core/compare/v3.3.0...v3.3.1) (2019-07-23)
+
+### Bug Fixes
+
+- **accessible-text-virtual:** sanitize attributes on start node ([#1694](https://github.com/dequelabs/axe-core/issues/1694)) ([c0bb08c](https://github.com/dequelabs/axe-core/commit/c0bb08c))
+- **axe.d.ts:** add optional xpath property to NodeResult ([#1642](https://github.com/dequelabs/axe-core/issues/1642)) ([287ef9c](https://github.com/dequelabs/axe-core/commit/287ef9c))
+- **get-background-color:** No longer calculate color from non-opaque overlapping element ([#1644](https://github.com/dequelabs/axe-core/issues/1644)) ([d45f81e](https://github.com/dequelabs/axe-core/commit/d45f81e))
+- **get-background-color:** No longer calculate color from non-opaque overlapping elm ([f1c2310](https://github.com/dequelabs/axe-core/commit/f1c2310))
+- **get-background-color:** process tbody, thead, and tfoot when getting background color ([#1653](https://github.com/dequelabs/axe-core/issues/1653)) ([e114bfd](https://github.com/dequelabs/axe-core/commit/e114bfd))
+- enable running axe-core in strict CSPs ([#1707](https://github.com/dequelabs/axe-core/issues/1707)) ([cc5bd59](https://github.com/dequelabs/axe-core/commit/cc5bd59))
+- **image-redundant-alt:** check for parent before calculating text ([#1705](https://github.com/dequelabs/axe-core/issues/1705)) ([1adbd02](https://github.com/dequelabs/axe-core/commit/1adbd02))
+- **th-has-data-cells:** empty cells will now pass ([#1659](https://github.com/dequelabs/axe-core/issues/1659)) ([c7489ab](https://github.com/dequelabs/axe-core/commit/c7489ab))
+- **types:** add new properties to RunOptions ([#1697](https://github.com/dequelabs/axe-core/issues/1697)) ([02aa36c](https://github.com/dequelabs/axe-core/commit/02aa36c)), closes [#1696](https://github.com/dequelabs/axe-core/issues/1696)
+- **valid-attr-value:** allow aria-describedby to return needs review ([#1671](https://github.com/dequelabs/axe-core/issues/1671)) ([2390925](https://github.com/dequelabs/axe-core/commit/2390925))
+- **color-contrast:** add px unit to error messages ([#1634](https://github.com/dequelabs/axe-core/issues/1634)) ([1712e46](https://github.com/dequelabs/axe-core/commit/1712e46))
+
+### Tests
+
+- **examples:** do not fail tests if deque.com has violations ([#1686](https://github.com/dequelabs/axe-core/issues/1686)) ([2118360](https://github.com/dequelabs/axe-core/commit/2118360))
+- ensure locale files are valid ([#1673](https://github.com/dequelabs/axe-core/issues/1673)) ([588f9b5](https://github.com/dequelabs/axe-core/commit/588f9b5))
+- require new release rule help docs to be active before creating release ([#1700](https://github.com/dequelabs/axe-core/issues/1700)) ([e9f9c18](https://github.com/dequelabs/axe-core/commit/e9f9c18))
+
+## [3.3.0](https://github.com/dequelabs/axe-core/compare/v3.2.2...v3.3.0) (2019-07-08)
 
 ### Bug Fixes
 

diff --git a/axe.d.ts b/axe.d.ts
@@ -7,7 +7,7 @@ declare namespace axe {
 
 	type TagValue = 'wcag2a' | 'wcag2aa' | 'section508' | 'best-practice';
 
-	type ReporterVersion = 'v1' | 'v2';
+	type ReporterVersion = 'v1' | 'v2' | 'raw' | 'raw-env' | 'no-passes';
 
 	type RunOnlyType = 'rule' | 'rules' | 'tag' | 'tags';
 
@@ -47,6 +47,13 @@ declare namespace axe {
 		elementRef?: boolean;
 		selectors?: boolean;
 		resultTypes?: resultGroups[];
+		reporter?: ReporterVersion;
+		xpath?: boolean;
+		absolutePaths?: boolean;
+		restoreScroll?: boolean;
+		frameWaitTime?: number;
+		preload?: boolean;
+		performanceTimer?: boolean;
 	}
 	interface AxeResults {
 		toolOptions: RunOptions;
@@ -73,6 +80,7 @@ declare namespace axe {
 		html: string;
 		impact?: ImpactValue;
 		target: string[];
+		xpath?: string[];
 		any: CheckResult[];
 		all: CheckResult[];
 		none: CheckResult[];

diff --git a/bower.json b/bower.json
@@ -1,6 +1,6 @@
 {
 	"name": "axe-core",
-	"version": "3.3.0",
+	"version": "3.3.1",
 	"contributors": [
 		{
 			"name": "David Sturley",

diff --git a/build/configure.js b/build/configure.js
@@ -3,7 +3,7 @@
 'use strict';
 
 var clone = require('clone');
-var dot = require('dot');
+var dot = require('@deque/dot');
 var templates = require('./templates');
 var buildManual = require('./build-manual');
 var entities = new (require('html-entities')).AllHtmlEntities();

diff --git a/build/rule-generator.js b/build/rule-generator.js
@@ -28,7 +28,7 @@ async function run() {
 				`Axe does not exist. Triggering build using - 'npm run build'. Rule generation will continue after build.`
 			)
 		);
-		await execa.shell('npm run build');
+		await execa('npm run build', { shell: true });
 	}
 
 	// rule-generator banner

diff --git a/doc/API.md b/doc/API.md
@@ -6,6 +6,7 @@
    1. [Get Started](#getting-started)
 1. [Section 2: API Reference](#section-2-api-reference)
    1. [Overview](#overview)
+   1. [Required Globals](#required-globals)
    1. [API Notes](#api-notes)
    1. [API Name: axe.getRules](#api-name-axegetrules)
    1. [API Name: axe.configure](#api-name-axeconfigure)
@@ -476,17 +477,19 @@ This example first includes all `wcag2a` and `wcag2aa` rules. All rules that are
 
 6. Only process certain types of results
 
-The `resultTypes` option can be used to limit the result types that axe will process, aggregate, and send to the reporter. This can be useful for improving performance on very large or complicated pages when you are only interested in certain types of results.
+The `resultTypes` option can be used to limit the number of nodes for a rule to a maximum of one. This can be useful for improving performance on very large or complicated pages when you are only interested in certain types of results.
 
-Types listed in this option are processed normally and report all of their results. Types _not_ listed process a maximum of one result. The caller can use this information to inform the user of the existence of that type of result if appropriate.
+After axe has processed all rules normally, it generates a unique selector for all nodes in all rules. This process can be time consuming, especially for pages with lots of nodes. By limiting the nodes to a maximum of one for result types you are not interested in, you can greatly speed up the tail end performance of axe.
+
+Types listed in this option will cause rules that fall under those types to show all nodes. Types _not_ listed will causes rules that fall under one of the missing types to show a maximum of one node. This allows you to still see those results and inform the user of them if appropriate.
 
 ```js
 {
 	resultTypes: ['violations', 'incomplete', 'inapplicable'];
 }
 ```
 
-This example will process all of the "violations", "incomplete", and "inapplicable" result types. Since "passes" was not specified, it will only process the first pass for each rule, if one exists. As a result, the results object's `passes` array will have a length of either `0` or `1`. On a series of extremely large pages, this would improve performance considerably.
+This example will return all the nodes for all rules that fall under the "violations", "incomplete", and "inapplicable" result types. Since the "passes" type was not specified, it will return at most one node for each rule that passes.
 
 ###### <a id='preload-configuration-details'></a> Preload Configuration in Options Parameter
 

diff --git a/doc/backwards-compatibility-doc.md b/doc/backwards-compatibility-doc.md
@@ -0,0 +1,92 @@
+# Backwards Compatibility in axe-core
+
+## What is part of the public axe-core API?
+
+The axe-core API includes:
+
+- Any APIs documented here: [https://github.com/dequelabs/axe-core/blob/develop/doc/API.md](https://github.com/dequelabs/axe-core/blob/develop/doc/API.md)
+- The selectors generated and included in the node information in the results arrays for any given HTML page
+- The JSON structures passed into and out of any API functions
+- Any functions in the `axe.utils` and `axe.commons` collections that are used by one of our standard rules (this document refers to these as the “Public Utils”). This includes use in any of the “matches”, “eval” and “after” functions.
+- The implicit function signature of the matches, eval and after functions (the names of the parameters that are passed-to the functions and the values returned by them)
+
+## What is not included in the public axe-core API?
+
+Any other function or attribute on the axe object is not considered part of the public API and is therefore not covered by the guarantee in this document.
+
+## What do we guarantee for the public axe-core API?
+
+We guarantee that the API signatures and the return values of functions will not break in patch or minor release versions except that we may add items to JSON structures in minor releases or override parameters. We will not remove items from JSON structures.
+
+In a minor release, we may change the implementation of Public Utils to fix bugs or improve performance. This means that a call to a Public Util may return a different value across patch versions.
+
+We will not add or remove rules in a patch release. We will not add support for new technologies in a patch release. We will endeavour to return the exact same results across patch releases with the exception of changes that are due to bug fixes. This means that the likelihood of a patch release finding issues on a page that was clean in a previous release is very close to zero but not zero.
+
+In a minor release, we may add support for new technologies in the Public Utils or in existing rules and we may add or disable rules. We may also change an experimental rule to become a standard rule (essentially equivalent to adding rule). This means that pages that did not return violations in a particular minor release may return violations in a subsequent release.
+
+If the HTML page is unchanged, calls to the analysis function(s) when compared across minor or patch releases will return the same exact selector for the nodes in any of the result arrays. If the HTML page has changed, it is possible for the selector to be different but it is not guaranteed that the selector will be different.
+
+APIs may be deprecated in a major or minor release and deprecated APIs will be removed in the next major release after their deprecation.
+A major or a minor release may introduce new Public Utils.
+
+Major releases may remove rules.
+
+### Table: Summary of What Deque Guarantees with Public axe-core API
+
+|                                               | Major                                                   | Minor                 | Patch                      |
+| :-------------------------------------------- | :------------------------------------------------------ | :-------------------- | :------------------------- |
+| **New Technologies**                          |                                                         |                       |                            |
+| Support for new technologies\*                | May add support                                         | May add support       | Will not add support       |
+| **APIS**                                      |                                                         |                       |                            |
+| API signatures and return values of functions | May break                                               | Will not break        | Will not break             |
+| APIs deprecated                               | May be deprecated                                       | May be deprecated     | Will not be deprecated     |
+| APIs removed                                  | May be removed (will remove previously deprecated APIs) | Will not be removed   | Will not be removed        |
+| **Public Utils**                              |                                                         |                       |                            |
+| Implementation of Public Utils                | May change                                              | May change            | Will not change            |
+| New public Utils                              | May add                                                 | May add               | Will not add               |
+| **Rules**                                     |                                                         |                       |                            |
+| Add rules                                     | May add                                                 | May add               | Will not add               |
+| Disable or remove rules                       | May remove (will remove previously deprecated rules)    | May disable or remove | Will not disable or remove |
+| Deprecate rules                               | May deprecate                                           | May deprecate         | Will not deprecate         |
+
+\*_New OSes, Browsers, ATs, new standards (e.g. introduction of ARIA), new versions of standards (e.g. WCAG 2.1)_
+
+## Implications
+
+### Breaking Builds
+
+Patch release upgrades can be applied in CI environments with a high degree of certainty that breakages will not be due to changes in the release. The chance is, however, not zero.
+
+### Custom Rules
+
+A custom rule configuration (with-or-without custom rules) is guaranteed to run on any newer version that shares the same major version number as the version for which it was created. A custom rule configuration (with-or-without custom rules) is not guaranteed to work with an older version of axe-core than the version for which it was created.
+
+You can write custom rules that utilize the Public Utils and the parameters that are passed to a check function, secure in the knowledge that the API will not change unless a major version is released.
+
+However, because we can introduce new rules, it is possible that a custom rule configuration will return additional results when run against a new minor release and may return different results when run against a newer patch release.
+
+A custom rule configuration may return different results (more or fewer) when run on a newer patch release due to bug fixes.
+
+A major release may completely break a custom rule or even all custom rules because of a change to any of the APIs.
+
+### Table: Implication of axe-core Updates on Custom Rule Function
+
+| Axe-core Release Semantic Version              | Example | Simple Custom Rules    | Complex Custom Rules   |
+| :--------------------------------------------- | :------ | :--------------------- | :--------------------- |
+| Prior release (different major release number) | 1.3.4   | Not guaranteed to work | Not guaranteed to work |
+| Release used to create custom rules            | 2.0.0   | Guaranteed to work     | Guaranteed to work     |
+| Next release (minor release)                   | 2.1.0   | Guaranteed to work\*   | Guaranteed to work\*   |
+| Next +1 release (patch release)                | 2.1.1   | Guaranteed to work\*   | Guaranteed to work\*   |
+| Next +2 release (major release)                | 3.0.0   | Not guaranteed to work | Not guaranteed to work |
+
+\*_Minor and patch releases will not break custom rules, but testing results may vary from those tests performed with previous minor and patch releases of axe-core. There may be inconsistencies between what Attest reports and what Comply reports._
+
+Please note that with even small changes in versions for simple custom rules, there may be inconsistencies between what Attest reports and what Comply reports. For best results, in both cases, versions should match exactly.
+
+### Tracking Issues Over Time
+
+Many systems attempt to identify unique issues using a combination of the page and state, the rule-id and the selector to track an issue across time and across calls to the analysis functions. This will work reliably across patch releases. This could break if a rule is removed or split up across minor releases. In a major release, this could break for the additional reason of a possible change in the selector generation (this did happen in the changes between 2.6.x and 3.x).
+
+### Comply
+
+Comply has the ability to add labels and comments to issues and to mark issues as ignored. Comply will lose this information when it is not able to track issues across time. This means that historical issue information may be lost when upgrading to a newer major version of axe-core.
diff --git a/doc/examples/chrome-debugging-protocol/package.json b/doc/examples/chrome-debugging-protocol/package.json
@@ -5,7 +5,7 @@
 		"test": "echo 'No test specified.'"
 	},
 	"dependencies": {
-		"axe-core": "^3.2.2",
+		"axe-core": "^3.3.0",
 		"chrome-remote-interface": "^0.27.1"
 	}
 }
diff --git a/doc/examples/jasmine/README.md b/doc/examples/jasmine/README.md
@@ -10,15 +10,13 @@ result from HTML with a single error.
 
 - Node must be installed; please follow the directions at http://www.nodejs.org
   to install it.
-- `npm install -g grunt-cli` to install the Grunt task runner (may need to be
-  run with `sudo` on Unix or as Administrator on Windows)
 - Move to the `doc/examples/jasmine` directory
 - `npm install` to install dependencies
 
 ## To run the example
 
 - Move to the `doc/examples/jasmine` directory
-- `grunt jasmine` to run Jasmine
+- `npm test` to run Jasmine
 
 You should see output indicating that the tests ran successfully, with zero
 failures.

diff --git a/doc/examples/jasmine/package.json b/doc/examples/jasmine/package.json
@@ -13,9 +13,9 @@
 		"test": "karma start karma.conf.js"
 	},
 	"devDependencies": {
-		"axe-core": "^3.2.2",
+		"axe-core": "^3.3.0",
 		"karma": "^4.1.0",
-		"karma-chrome-launcher": "^2.2.0",
+		"karma-chrome-launcher": "^3.0.0",
 		"karma-jasmine": "^2.0.1"
 	}
 }
diff --git a/doc/examples/jest_react/package.json b/doc/examples/jest_react/package.json
@@ -13,7 +13,7 @@
 		"test": "jest"
 	},
 	"devDependencies": {
-		"axe-core": "^3.2.2",
+		"axe-core": "^3.3.0",
 		"babel-jest": "^23.0.0",
 		"babel-preset-es2015": "^6.24.1",
 		"babel-preset-react": "^6.24.1",

diff --git a/doc/examples/jsdom/package.json b/doc/examples/jsdom/package.json
@@ -8,7 +8,7 @@
 		"test": "mocha"
 	},
 	"devDependencies": {
-		"axe-core": "^3.2.2",
+		"axe-core": "^3.3.0",
 		"jsdom": "^15.0.0",
 		"mocha": "^6.1.4"
 	}

diff --git a/doc/examples/mocha/Gruntfile.js b/doc/examples/mocha/Gruntfile.js