Merge pull request #993 from dequelabs/autocomplete

feat: Add WCAG 2.1 autocomplete-valid rule

doc/rule-descriptions.md

@@ -12,6 +12,7 @@
 | aria-valid-attr-value | Ensures all ARIA attributes have valid values | Critical | cat.aria, wcag2a, wcag412 | true |
 | aria-valid-attr | Ensures attributes that begin with aria- are valid ARIA attributes | Critical | cat.aria, wcag2a, wcag412 | true |
 | audio-caption | Ensures <audio> elements have captions | Critical | cat.time-and-media, wcag2a, wcag121, section508, section508.22.a | true |
+| autocomplete-valid | Ensure the autocomplete attribute is correct and suitable for the form field | Serious | cat.forms, wcag21aa, wcag135 | true |
 | blink | Ensures <blink> elements are not used | Serious | cat.time-and-media, wcag2a, wcag222, section508, section508.22.j | true |
 | button-name | Ensures buttons have discernible text | Serious, Critical | cat.name-role-value, wcag2a, wcag412, section508, section508.22.a | true |
 | bypass | Ensures each page has at least one mechanism for a user to bypass navigation and jump straight to the content | Serious | cat.keyboard, wcag2a, wcag241, section508, section508.22.o | true |

lib/checks/forms/autocomplete-appropriate.js

@@ -0,0 +1,48 @@
+// Select and textarea is always allowed
+if (node.nodeName.toUpperCase() !== 'INPUT') {
+	return true;
+}
+
+const number = ['text', 'search', 'number'];
+const url = ['text', 'search', 'url'];
+const allowedTypesMap = {
+	bday: ['text', 'search', 'date'],
+	email: ['text', 'search', 'email'],
+	'cc-exp': ['text', 'search', 'month'],
+	'street-address': [], // Not even the default
+	tel: ['text', 'search', 'tel'],
+	'cc-exp-month': number,
+	'cc-exp-year': number,
+	'transaction-amount': number,
+	'bday-day': number,
+	'bday-month': number,
+	'bday-year': number,
+	'new-password': ['text', 'search', 'password'],
+	'current-password': ['text', 'search', 'password'],
+	url: url,
+	photo: url,
+	impp: url
+};
+
+if (typeof options === 'object') {
+	// Merge in options
+	Object.keys(options).forEach(key => {
+		if (!allowedTypesMap[key]) {
+			allowedTypesMap[key] = [];
+		}
+		allowedTypesMap[key] = allowedTypesMap[key].concat(options[key]);
+	});
+}
+
+const autocomplete = node.getAttribute('autocomplete');
+const autocompleteTerms = autocomplete
+	.split(/\s+/g)
+	.map(term => term.toLowerCase());
+const purposeTerm = autocompleteTerms[autocompleteTerms.length - 1];
+const allowedTypes = allowedTypesMap[purposeTerm];
+
+if (typeof allowedTypes === 'undefined') {
+	return node.type === 'text';
+}
+
+return allowedTypes.includes(node.type);

lib/checks/forms/autocomplete-appropriate.json

@@ -0,0 +1,11 @@
+{
+  "id": "autocomplete-appropriate",
+  "evaluate": "autocomplete-appropriate.js",
+  "metadata": {
+    "impact": "serious",
+    "messages": {
+      "pass": "the autocomplete value is on an appropriate element",
+      "fail": "the autocomplete value is inappropriate for this type of input"
+    }
+  }
+}

lib/checks/forms/autocomplete-valid.js

@@ -0,0 +1,2 @@
+const autocomplete = node.getAttribute('autocomplete') || '';
+return axe.commons.text.isValidAutocomplete(autocomplete, options);

lib/checks/forms/autocomplete-valid.json

@@ -0,0 +1,11 @@
+{
+  "id": "autocomplete-valid",
+  "evaluate": "autocomplete-valid.js",
+  "metadata": {
+    "impact": "serious",
+    "messages": {
+      "pass": "the autocomplete attribute is correctly formatted",
+      "fail": "the autocomplete attribute is incorrectly formatted"
+    }
+  }
+}

lib/commons/text/is-valid-autocomplete.js

@@ -0,0 +1,118 @@
+/* global text */
+const autocomplete = {
+	stateTerms: ['on', 'off'],
+	standaloneTerms: [
+		'name',
+		'honorific-prefix',
+		'given-name',
+		'additional-name',
+		'family-name',
+		'honorific-suffix',
+		'nickname',
+		'username',
+		'new-password',
+		'current-password',
+		'organization-title',
+		'organization',
+		'street-address',
+		'address-line1',
+		'address-line2',
+		'address-line3',
+		'address-level4',
+		'address-level3',
+		'address-level2',
+		'address-level1',
+		'country',
+		'country-name',
+		'postal-code',
+		'cc-name',
+		'cc-given-name',
+		'cc-additional-name',
+		'cc-family-name',
+		'cc-number',
+		'cc-exp',
+		'cc-exp-month',
+		'cc-exp-year',
+		'cc-csc',
+		'cc-type',
+		'transaction-currency',
+		'transaction-amount',
+		'language',
+		'bday',
+		'bday-day',
+		'bday-month',
+		'bday-year',
+		'sex',
+		'url',
+		'photo'
+	],
+	qualifiers: ['home', 'work', 'mobile', 'fax', 'pager'],
+	qualifiedTerms: [
+		'tel',
+		'tel-country-code',
+		'tel-national',
+		'tel-area-code',
+		'tel-local',
+		'tel-local-prefix',
+		'tel-local-suffix',
+		'tel-extension',
+		'email',
+		'impp'
+	],
+	locations: ['billing', 'shipping']
+};
+text.autocomplete = autocomplete;
+
+text.isValidAutocomplete = function isValidAutocomplete(
+	autocomplete,
+	{
+		looseTyped = false,
+		stateTerms = [],
+		locations = [],
+		qualifiers = [],
+		standaloneTerms = [],
+		qualifiedTerms = []
+	} = {}
+) {
+	/*eslint max-statements: ["error", 23] */
+	autocomplete = autocomplete.toLowerCase().trim();
+	stateTerms = stateTerms.concat(text.autocomplete.stateTerms);
+	if (stateTerms.includes(autocomplete) || autocomplete === '') {
+		return true;
+	}
+
+	qualifiers = qualifiers.concat(text.autocomplete.qualifiers);
+	locations = locations.concat(text.autocomplete.locations);
+	standaloneTerms = standaloneTerms.concat(text.autocomplete.standaloneTerms);
+	qualifiedTerms = qualifiedTerms.concat(text.autocomplete.qualifiedTerms);
+
+	const autocompleteTerms = autocomplete.split(/\s+/g);
+	if (!looseTyped) {
+		if (
+			autocompleteTerms[0].length > 8 &&
+			autocompleteTerms[0].substr(0, 8) === 'section-'
+		) {
+			autocompleteTerms.shift();
+		}
+
+		if (locations.includes(autocompleteTerms[0])) {
+			autocompleteTerms.shift();
+		}
+
+		if (qualifiers.includes(autocompleteTerms[0])) {
+			autocompleteTerms.shift();
+			// only quantifiers allowed at this point
+			standaloneTerms = [];
+		}
+
+		if (autocompleteTerms.length !== 1) {
+			return false;
+		}
+	}
+
+	const purposeTerm = autocompleteTerms[autocompleteTerms.length - 1];
+	return (
+		standaloneTerms.includes(purposeTerm) ||
+		qualifiedTerms.includes(purposeTerm)
+	);
+};

lib/rules/autocomplete-matches.js

@@ -0,0 +1,45 @@
+const { text, aria, dom } = axe.commons;
+
+const autocomplete = node.getAttribute('autocomplete');
+if (!autocomplete || text.sanitize(autocomplete) === '') {
+	return false;
+}
+
+const nodeName = node.nodeName.toUpperCase();
+if (['TEXTAREA', 'INPUT', 'SELECT'].includes(nodeName) === false) {
+	return false;
+}
+
+// The element is an `input` element a `type` of `hidden`, `button`, `submit` or `reset`
+const excludedInputTypes = ['submit', 'reset', 'button', 'hidden'];
+if (nodeName === 'INPUT' && excludedInputTypes.includes(node.type)) {
+	return false;
+}
+
+// The element has a `disabled` or `aria-disabled="true"` attribute
+const ariaDisabled = node.getAttribute('aria-disabled') || 'false';
+if (node.disabled || ariaDisabled.toLowerCase() === 'true') {
+	return false;
+}
+
+// The element has `tabindex="-1"` and has a [[semantic role]] that is
+//   not a [widget](https://www.w3.org/TR/wai-aria-1.1/#widget_roles)
+const role = node.getAttribute('role');
+const tabIndex = node.getAttribute('tabindex');
+if (tabIndex === '-1' && role) {
+	const roleDef = aria.lookupTable.role[role];
+	if (roleDef === undefined || roleDef.type !== 'widget') {
+		return false;
+	}
+}
+
+// The element is **not** visible on the page or exposed to assistive technologies
+if (
+	tabIndex === '-1' &&
+	!dom.isVisible(node, false) &&
+	!dom.isVisible(node, true)
+) {
+	return false;
+}
+
+return true;

lib/rules/autocomplete-valid.json

@@ -0,0 +1,19 @@
+{
+  "id": "autocomplete-valid",
+  "matches": "autocomplete-matches.js",
+  "tags": [
+    "cat.forms",
+    "wcag21aa",
+    "wcag135"
+  ],
+  "metadata": {
+    "description": "Ensure the autocomplete attribute is correct and suitable for the form field",
+    "help": "autocomplete attribute must be used correctly"
+  },
+  "all": [
+    "autocomplete-valid",
+    "autocomplete-appropriate"
+  ],
+  "any": [],
+  "none": []
+}

test/checks/forms/autocomplete-appropriate.js

@@ -0,0 +1,62 @@
+describe('autocomplete-appropriate', function() {
+	'use strict';
+
+	var fixture = document.getElementById('fixture');
+	var checkSetup = axe.testUtils.checkSetup;
+	var checkContext = axe.testUtils.MockCheckContext();
+	var evaluate = checks['autocomplete-appropriate'].evaluate;
+
+	beforeEach(function() {
+		axe._tree = undefined;
+	});
+
+	afterEach(function() {
+		fixture.innerHTML = '';
+		checkContext.reset();
+	});
+
+	function autocompleteCheckParams(term, type, options) {
+		return checkSetup(
+			'<input autocomplete="' + term + '" type=' + type + ' id="target" />',
+			options
+		);
+	}
+
+	it('returns true for non-select elements', function() {
+		['div', 'button', 'select', 'textarea'].forEach(function(tagName) {
+			var elm = document.createElement(tagName);
+			elm.setAttribute('autocomplete', 'foo');
+			elm.setAttribute('type', 'email');
+			var params = checkSetup(elm);
+
+			assert.isTrue(
+				evaluate.apply(checkContext, params),
+				'failed for ' + tagName
+			);
+		});
+	});
+
+	it('returns true if the input type is in the map', function() {
+		var options = { foo: ['url'] };
+		var params = autocompleteCheckParams('foo', 'url', options);
+		assert.isTrue(evaluate.apply(checkContext, params));
+	});
+
+	it('returns false if the input type is not in the map', function() {
+		var options = { foo: ['url'] };
+		var params = autocompleteCheckParams('foo', 'email', options);
+		assert.isFalse(evaluate.apply(checkContext, params));
+	});
+
+	it('returns true if the input type is text and the term is undefined', function() {
+		var options = {};
+		var params = autocompleteCheckParams('foo', 'text', options);
+		assert.isTrue(evaluate.apply(checkContext, params));
+	});
+
+	it('returns false if the input type is text and the term maps to an empty array', function() {
+		var options = { foo: [] };
+		var params = autocompleteCheckParams('foo', 'text', options);
+		assert.isFalse(evaluate.apply(checkContext, params));
+	});
+});

test/checks/forms/autocomplete-valid.js

@@ -0,0 +1,67 @@
+describe('autocomplete-valid', function() {
+	'use strict';
+
+	var fixture = document.getElementById('fixture');
+	var checkSetup = axe.testUtils.checkSetup;
+	var checkContext = axe.testUtils.MockCheckContext();
+	var evaluate = checks['autocomplete-valid'].evaluate;
+
+	var options = {
+		standaloneTerms: ['standalone-term'],
+		qualifiedTerms: ['qualified-term']
+	};
+
+	var _isValidAutocomplete;
+	beforeEach(function() {
+		axe._tree = undefined;
+		_isValidAutocomplete = axe.commons.text.isValidAutocomplete;
+	});
+
+	afterEach(function() {
+		axe.commons.text.isValidAutocomplete = _isValidAutocomplete;
+		fixture.innerHTML = '';
+		checkContext.reset();
+	});
+
+	it('passes autocomplete attribute to text.isValidAutocomplete', function() {
+		var params = checkSetup('<input autocomplete="foo" id="target" />');
+		var called = false;
+		axe.commons.text.isValidAutocomplete = function(arg1) {
+			assert.equal(arg1, 'foo');
+			called = true;
+		};
+		evaluate.apply(checkContext, params);
+		assert.isTrue(called);
+	});
+
+	it('passes options to text.isValidAutocomplete', function() {
+		var options = { foo: 'bar' };
+		var params = checkSetup(
+			'<input autocomplete="foo" id="target" />',
+			options
+		);
+		var called = false;
+		axe.commons.text.isValidAutocomplete = function(_, arg2) {
+			assert.equal(arg2, options);
+			called = true;
+		};
+		evaluate.apply(checkContext, params);
+		assert.isTrue(called);
+	});
+
+	it('returns the outcome of text.isValidAutocomplete', function() {
+		var params1 = checkSetup(
+			'<input autocomplete="badvalue" id="target" />',
+			options
+		);
+		assert.isFalse(_isValidAutocomplete('badvalue'));
+		assert.isFalse(evaluate.apply(checkContext, params1));
+
+		var params2 = checkSetup(
+			'<input autocomplete="email" id="target" />',
+			options
+		);
+		assert.isTrue(_isValidAutocomplete('email'));
+		assert.isTrue(evaluate.apply(checkContext, params2));
+	});
+});