feat(utils): add support for complex CSS selectors (#1494)

Updates the CSS Selector Parser to allow more complex selectors: `:not`, `^=`, `$=`, and `*=`. Also update docs to describe what selectors we support.

Closes: #1493 

## Reviewer checks

**Required fields, to be filled out by PR reviewer(s)**
- [x] Follows the commit message policy, appropriate for next version
- [x] Has documentation updated, a DU ticket, or requires no documentation change
- [x] Includes new tests, or was unnecessary
- [x] Code is reviewed for security by: @WilcoFiers

Author: straker

doc/API.md

@@ -176,15 +176,15 @@ axe.configure({
     - The rules attribute is an Array of rule objects
     - each rule object can contain the following attributes
       - `id` - string(required). This uniquely identifies the rule. If the rule already exists, it will be overridden with any of the attributes supplied. The attributes below that are marked required, are only required for new rules.
-      - `selector` - string(optional, default `*`). A CSS selector used to identify the elements that are passed into the rule for evaluation.
+      - `selector` - string(optional, default `*`). A [CSS selector](./developer-guide.md#supported-css-selectors) used to identify the elements that are passed into the rule for evaluation.
       - `excludeHidden` - boolean(optional, default `true`). This indicates whether elements that are hidden from all users are to be passed into the rule for evaluation.
       - `enabled` - boolean(optional, default `true`). Whether the rule is turned on. This is a common attribute for overriding.
       - `pageLevel` - boolean(optional, default `false`). When set to true, this rule is only applied when the entire page is tested. Results from nodes on different frames are combined into a single result. See [page level rules](#page-level-rules).
       - `any` - array(optional, default `[]`). This is a list of checks that, if none "pass", will generate a violation.
       - `all` - array(optional, default `[]`). This is a list of checks that, if any "fails", will generate a violation.
       - `none` - array(optional, default `[]`). This is a list of checks that, if any "pass", will generate a violation.
       - `tags` - array(optional, default `[]`). A list if the tags that "classify" the rule. In practice, you must supply some valid tags or the default evaluation will not invoke the rule. The convention is to include the standard (WCAG 2 and/or section 508), the WCAG 2 level, Section 508 paragraph, and the WCAG 2 success criteria. Tags are constructed by converting all letters to lower case, removing spaces and periods and concatinating the result. E.g. WCAG 2 A success criteria 1.1.1 would become ["wcag2a", "wcag111"]
-      - `matches` - string(optional, default `*`). A filtering CSS selector that will exclude elements that do not match the CSS selector.
+      - `matches` - string(optional, default `*`). A filtering [CSS selector](./developer-guide.md#supported-css-selectors) that will exclude elements that do not match the CSS selector.
   - `disableOtherRules` - Disables all rules not included in the `rules` property.
   - `locale` - A locale object to apply (at runtime) to all rules and checks, in the same shape as `/locales/*.json`.
 
@@ -251,11 +251,7 @@ By default, `axe.run` will test the entire document. The context object is an op
 - Example: To limit analysis to the `<div id="content">` element: `document.getElementById("content")`
 
 2. A NodeList such as returned by `document.querySelectorAll`.
-3. A CSS selector that selects the portion(s) of the document that must be analyzed. This includes:
-
-- A CSS selector as a class name (e.g. `.classname`)
-- A CSS selector as a node name (e.g. `div`)
-- A CSS selector of an element id (e.g. `#tag`)
+3. A [CSS selector](./developer-guide.md#supported-css-selectors) that selects the portion(s) of the document that must be analyzed.
 
 4. An include-exclude object (see below)
 
@@ -264,7 +260,7 @@ By default, `axe.run` will test the entire document. The context object is an op
 The include exclude object is a JSON object with two attributes: include and exclude. Either include or exclude is required. If only `exclude` is specified; include will default to the entire `document`.
 
 - A node, or
-- An array of arrays of CSS selectors
+- An array of arrays of [CSS selectors](./developer-guide.md#supported-css-selectors)
   - If the nested array contains a single string, that string is the CSS selector
   - If the nested array contains multiple strings
     - The last string is the final CSS selector
@@ -703,7 +699,7 @@ axe.utils.querySelectorAll(virtualNode, 'a[href]');
 ##### Parameters
 
 - `virtualNode` – object, the flattened DOM tree to query against. `axe._tree` is available for this purpose during an audit; see below.
-- `selector` – string, the CSS selector to use as a filter. For the most part, this should work seamlessly with `document.querySelectorAll`.
+- `selector` – string, the [CSS selector](./developer-guide.md#supported-css-selectors) to use as a filter. For the most part, this should work seamlessly with `document.querySelectorAll`.
 
 ##### Returns
 

doc/developer-guide.md

@@ -5,6 +5,11 @@ Axe runs a series of tests to check for accessibility of content and functionali
 Axe 3.0 supports open Shadow DOM: see our virtual DOM APIs and test utilities for developing axe-core moving forward. Note: we do not and cannot support closed Shadow DOM.
 
 1. [Getting Started](#getting-started)
+   1. [Environment Pre-requisites](#environment-pre-requisites)
+   1. [Building axe.js](#building-axejs)
+   1. [Running Tests](#running-tests)
+   1. [API Reference](#api-reference)
+   1. [Supported CSS Selectors](#supported-css-selectors)
 1. [Architecture Overview](#architecture-overview)
    1. [Rules](#rules)
    1. [Checks](#checks)
@@ -49,6 +54,15 @@ You can also load tests in any supported browser, which is helpful for debugging
 
 [See API exposed on axe](./API.md#section-2-api-reference)
 
+### Supported CSS Selectors
+
+Axe supports the following CSS selectors:
+
+- Type, Class, ID, and Universal selectors. E.g `div.main, #main`
+- Pseudo selector `not`. E.g `th:not([scope])`
+- Descendant and Child combinators. E.g. `table td`, `ul > li`
+- Attribute selectors `=`, `^=`, `$=`, `*=`. E.g `a[href^="#"]`
+
 ## Architecture Overview
 
 Axe tests for accessibility using objects called Rules. Each Rule tests for a high-level aspect of accessibility, such as color contrast, button labels, and alternate text for images. Each rule is made up of a series of Checks. Depending on the rule; all, some, or none of these checks must pass in order for the rule to pass.
@@ -62,7 +76,7 @@ After execution, a Check will return `true` or `false` depending on whether or n
 Rules are defined by JSON files in the [lib/rules directory](../lib/rules). The JSON object is used to seed the [Rule object](../lib/core/base/rule.js#L30). A valid Rule JSON consists of the following:
 
 - `id` - `String` A unique name of the Rule.
-- `selector` - **optional** `String` which is a CSS selector that specifies the elements of the page on which the Rule runs. axe-core will look inside of the light DOM and _open_ [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Shadow_DOM) trees for elements matching the provided selector. If omitted, the rule will run against every node.
+- `selector` - **optional** `String` which is a [CSS selector](#supported-css-selectors) that specifies the elements of the page on which the Rule runs. axe-core will look inside of the light DOM and _open_ [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Shadow_DOM) trees for elements matching the provided selector. If omitted, the rule will run against every node.
 - `excludeHidden` - **optional** `Boolean` Whether the rule should exclude hidden elements. Defaults to `true`.
 - `enabled` - **optional** `Boolean` Whether the rule is enabled by default. Defaults to `true`.
 - `pageLevel` - **optional** `Boolean` Whether the rule is page level. Page level rules will only run if given an entire `document` as context.

lib/core/utils/css-parser.js

@@ -1,5 +1,7 @@
 (function(axe) {
 	var parser = new axe.imports.CssSelectorParser();
+	parser.registerSelectorPseudos('not');
 	parser.registerNestingOperators('>');
+	parser.registerAttrEqualityMods('^', '$', '*');
 	axe.utils.cssParser = parser;
 })(axe);

lib/core/utils/qsa.js

@@ -152,7 +152,7 @@ function convertPseudos(pseudos) {
 		var expressions;
 
 		if (p.name === 'not') {
-			expressions = axe.utils.cssParser.parse(p.value);
+			expressions = p.value;
 			expressions = expressions.selectors
 				? expressions.selectors
 				: [expressions];

test/core/utils/qsa.js

@@ -5,6 +5,15 @@ function Vnode(nodeName, className, attributes, id) {
 	this.attributes = attributes || [];
 	this.className = className;
 	this.nodeType = 1;
+
+	this.attributes.push({
+		key: 'id',
+		value: typeof id !== 'undefined' ? id : null
+	});
+	this.attributes.push({
+		key: 'class',
+		value: typeof className !== 'undefined' ? className : null
+	});
 }
 
 Vnode.prototype.getAttribute = function(att) {
@@ -217,6 +226,10 @@ describe('axe.utils.querySelectorAllFilter', function() {
 		var result = axe.utils.querySelectorAllFilter(dom, 'div:not(#thangy)');
 		assert.equal(result.length, 3);
 	});
+	it('should find nodes using :not selector with attribute', function() {
+		var result = axe.utils.querySelectorAllFilter(dom, 'div:not([id])');
+		assert.equal(result.length, 2);
+	});
 	it('should find nodes hierarchically using :not selector', function() {
 		var result = axe.utils.querySelectorAllFilter(dom, 'div:not(.first) li');
 		assert.equal(result.length, 2);
@@ -235,6 +248,18 @@ describe('axe.utils.querySelectorAllFilter', function() {
 		);
 		assert.equal(result.length, 0);
 	});
+	it('should find nodes using ^= attribute selector', function() {
+		var result = axe.utils.querySelectorAllFilter(dom, '[class^="sec"]');
+		assert.equal(result.length, 1);
+	});
+	it('should find nodes using $= attribute selector', function() {
+		var result = axe.utils.querySelectorAllFilter(dom, '[id$="ne"]');
+		assert.equal(result.length, 3);
+	});
+	it('should find nodes using *= attribute selector', function() {
+		var result = axe.utils.querySelectorAllFilter(dom, '[role*="t"]');
+		assert.equal(result.length, 2);
+	});
 	it('should put it all together', function() {
 		var result = axe.utils.querySelectorAllFilter(
 			dom,