feat(rule): optional impact on rules (#2393)

* feat(rule): optional impact on rules

* Update API.md

axe.d.ts

@@ -141,6 +141,7 @@ declare namespace axe {
 	interface Rule {
 		id: string;
 		selector?: string;
+		impact?: ImpactValue;
 		excludeHidden?: boolean;
 		enabled?: boolean;
 		pageLevel?: boolean;

build/configure.js

@@ -224,6 +224,9 @@ function buildRules(grunt, options, commons, callback) {
 			function capitalize(s) {
 				return s.charAt(0).toUpperCase() + s.slice(1);
 			}
+			if (rule.impact) {
+				return capitalize(rule.impact);
+			}
 
 			function getUniqueArr(arr) {
 				return arr.filter(function(value, index, self) {

build/tasks/validate.js

@@ -133,6 +133,10 @@ function createSchemas() {
 			selector: {
 				type: 'string'
 			},
+			impact: {
+				type: 'string',
+				enum: ['minor', 'moderate', 'serious', 'critical']
+			},
 			excludeHidden: {
 				type: 'boolean'
 			},

doc/API.md

@@ -205,6 +205,7 @@ 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.
+      - `impact` - string(optional). Override the impact defined by checks
       - `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.

doc/rule-descriptions.md

@@ -75,7 +75,7 @@ Rules that do not necessarily conform to WCAG success criterion but are industry
 | :----------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- | :----------------- | :----------------------------------------- | :------------------------- |
 | [accesskeys](https://dequeuniversity.com/rules/axe/3.5/accesskeys?application=RuleDescription)                                                   | Ensures every accesskey attribute value is unique                                                    | Serious            | best-practice, cat.keyboard                | failure                    |
 | [aria-allowed-role](https://dequeuniversity.com/rules/axe/3.5/aria-allowed-role?application=RuleDescription)                                     | Ensures role attribute has an appropriate value for the element                                      | Minor              | cat.aria, best-practice                    | failure, needs review |
-| [empty-heading](https://dequeuniversity.com/rules/axe/3.5/empty-heading?application=RuleDescription)                                             | Ensures headings have discernible text                                                               | Minor              | cat.name-role-value, best-practice         | failure                    |
+| [empty-heading](https://dequeuniversity.com/rules/axe/3.5/empty-heading?application=RuleDescription)                                             | Ensures headings have discernible text                                                               | Minor              | cat.name-role-value, best-practice         | failure, needs review |
 | [frame-tested](https://dequeuniversity.com/rules/axe/3.5/frame-tested?application=RuleDescription)                                               | Ensures <iframe> and <frame> elements contain the axe-core script                        | Critical           | cat.structure, review-item, best-practice  | failure, needs review |
 | [frame-title-unique](https://dequeuniversity.com/rules/axe/3.5/frame-title-unique?application=RuleDescription)                                   | Ensures <iframe> and <frame> elements contain a unique title attribute                   | Serious            | cat.text-alternatives, best-practice       | failure                    |
 | [heading-order](https://dequeuniversity.com/rules/axe/3.5/heading-order?application=RuleDescription)                                             | Ensures the order of headings is semantically correct                                                | Moderate           | cat.semantics, best-practice               | failure                    |

lib/core/base/metadata-function-map.js

@@ -66,7 +66,6 @@ import ariaLabelledbyEvaluate from '../../checks/shared/aria-labelledby-evaluate
 import avoidInlineSpacingEvaluate from '../../checks/shared/avoid-inline-spacing-evaluate';
 import docHasTitleEvaluate from '../../checks/shared/doc-has-title-evaluate';
 import existsEvaluate from '../../checks/shared/exists-evaluate';
-import hasAccessibleTextEvaluate from '../../checks/shared/has-accessible-text-evaluate';
 import hasAltEvaluate from '../../checks/shared/has-alt-evaluate';
 import isOnScreenEvaluate from '../../checks/shared/is-on-screen-evaluate';
 import nonEmptyIfPresentEvaluate from '../../checks/shared/non-empty-if-present-evaluate';
@@ -228,7 +227,6 @@ const metadataFunctionMap = {
 	'avoid-inline-spacing-evaluate': avoidInlineSpacingEvaluate,
 	'doc-has-title-evaluate': docHasTitleEvaluate,
 	'exists-evaluate': existsEvaluate,
-	'has-accessible-text-evaluate': hasAccessibleTextEvaluate,
 	'has-alt-evaluate': hasAltEvaluate,
 	'is-on-screen-evaluate': isOnScreenEvaluate,
 	'non-empty-if-present-evaluate': nonEmptyIfPresentEvaluate,

lib/core/base/rule.js

@@ -8,8 +8,10 @@ import {
 	queue,
 	DqElement,
 	select,
-	isHidden
+	isHidden,
+	assert
 } from '../utils';
+import constants from '../constants';
 
 function Rule(spec, parentAudit) {
 	this._audit = parentAudit;
@@ -26,6 +28,18 @@ function Rule(spec, parentAudit) {
 	 */
 	this.selector = spec.selector || '*';
 
+	/**
+	 * Impact of the rule (optional)
+	 * @type {"minor" | "moderate" | "serious" | "critical"}
+	 */
+	if (spec.impact) {
+		assert(
+			constants.impact.includes(spec.impact),
+			`Impact ${spec.impact} is not a valid impact`
+		);
+		this.impact = spec.impact;
+	}
+
 	/**
 	 * Whether to exclude hiddden elements form analysis.  Defaults to true.
 	 * @type {Boolean}

lib/core/utils/finalize-result.js

@@ -6,6 +6,17 @@ import aggregateNodeResults from './aggregate-node-results';
  * @return {object}
  */
 function finalizeRuleResult(ruleResult) {
+	const rule = axe._audit.rules.find(rule => rule.id === ruleResult.id);
+	if (rule && rule.impact) {
+		ruleResult.nodes.forEach(node => {
+			['any', 'all', 'none'].forEach(checkType => {
+				(node[checkType] || []).forEach(checkResult => {
+					checkResult.impact = rule.impact;
+				});
+			});
+		});
+	}
+
 	Object.assign(ruleResult, aggregateNodeResults(ruleResult.nodes));
 	delete ruleResult.nodes;
 

lib/rules/empty-heading.json

@@ -3,11 +3,17 @@
 	"selector": "h1, h2, h3, h4, h5, h6, [role=\"heading\"]",
 	"matches": "heading-matches",
 	"tags": ["cat.name-role-value", "best-practice"],
+	"impact": "minor",
 	"metadata": {
 		"description": "Ensures headings have discernible text",
 		"help": "Headings must not be empty"
 	},
 	"all": [],
-	"any": ["has-accessible-text"],
+	"any": [
+		"has-visible-text",
+		"aria-label",
+		"aria-labelledby",
+		"non-empty-title"
+	],
 	"none": []
 }

test/core/base/rule.js

@@ -1729,6 +1729,27 @@ describe('Rule', function() {
 			});
 		});
 
+		describe('.impact', function() {
+			it('should be set', function() {
+				var spec = {
+					impact: 'critical'
+				};
+				assert.equal(new Rule(spec).impact, spec.impact);
+			});
+
+			it('should have no default', function() {
+				var spec = {};
+				assert.isUndefined(new Rule(spec).impact);
+			});
+
+			it('throws if impact is invalid', function() {
+				assert.throws(function() {
+					// eslint-disable-next-line no-new
+					new Rule({ impact: 'hello' });
+				});
+			});
+		});
+
 		describe('.any', function() {
 			it('should be set', function() {
 				var spec = {

test/core/utils/finalize-result.js

@@ -1,5 +1,16 @@
 describe('axe.utils.finalizeRuleResult', function() {
 	'use strict';
+	var original = axe._audit;
+
+	beforeEach(function() {
+		axe._audit = {
+			rules: []
+		};
+	});
+
+	after(function() {
+		axe._audit = original;
+	});
 
 	it('should be a function', function() {
 		assert.isFunction(axe.utils.finalizeRuleResult);
@@ -13,4 +24,56 @@ describe('axe.utils.finalizeRuleResult', function() {
 
 		assert.equal(goingIn, comingOut);
 	});
+
+	it('assigns impact if rule.impact is defined', function() {
+		axe._audit = {
+			rules: [{ id: 'foo', impact: 'critical' }]
+		};
+
+		var output = axe.utils.finalizeRuleResult({
+			id: 'foo',
+			nodes: [
+				{
+					any: [
+						{
+							result: false,
+							impact: 'minor'
+						}
+					],
+					all: [],
+					none: []
+				}
+			]
+		});
+
+		assert.equal(output.impact, 'critical');
+		assert.equal(output.violations[0].impact, 'critical');
+		assert.equal(output.violations[0].any[0].impact, 'critical');
+	});
+
+	it('leaves impact as null when rule.impact is defined', function() {
+		axe._audit = {
+			rules: [{ id: 'foo', impact: 'critical' }]
+		};
+
+		var output = axe.utils.finalizeRuleResult({
+			id: 'foo',
+			nodes: [
+				{
+					any: [
+						{
+							result: true,
+							impact: 'minor'
+						}
+					],
+					all: [],
+					none: []
+				}
+			]
+		});
+
+		assert.isNull(output.impact);
+		assert.isNull(output.passes[0].impact);
+		assert.equal(output.passes[0].any[0].impact, 'critical');
+	});
 });