fix(valid-attr-value): Return incomplete when aria-describedby reference a missing element

lib/checks/aria/valid-attr-value.js

@@ -1,15 +1,16 @@
 options = Array.isArray(options) ? options : [];
 
+const needsReview = [];
 const invalid = [];
 const aria = /^aria-/;
 const attrs = axe.utils.getNodeAttributes(node);
 
 const skipAttrs = ['aria-errormessage'];
 
-// aria-controls should only check if element exists if the element
-// doesn't have aria-expanded=false or aria-selected=false (tabs)
-// @see https://github.com/dequelabs/axe-core/issues/1463
 const preChecks = {
+	// aria-controls should only check if element exists if the element
+	// doesn't have aria-expanded=false or aria-selected=false (tabs)
+	// @see https://github.com/dequelabs/axe-core/issues/1463
 	'aria-controls': function() {
 		return (
 			node.getAttribute('aria-expanded') !== 'false' &&
@@ -21,6 +22,18 @@ const preChecks = {
 	// @see https://github.com/dequelabs/axe-core/issues/1524
 	'aria-owns': function() {
 		return node.getAttribute('aria-expanded') !== 'false';
+	},
+	// aria-describedby should not mark missing element as violation but
+	// instead as needs review
+	// @see https://github.com/dequelabs/axe-core/issues/1151
+	'aria-describedby': function() {
+		if (!axe.commons.aria.validateAttrValue(node, 'aria-describedby')) {
+			needsReview.push(
+				`aria-describedby="${node.getAttribute('aria-describedby')}"`
+			);
+		}
+
+		return;
 	}
 };
 
@@ -39,6 +52,11 @@ for (let i = 0, l = attrs.length; i < l; i++) {
 	}
 }
 
+if (needsReview.length) {
+	this.data(needsReview);
+	return undefined;
+}
+
 if (invalid.length) {
 	this.data(invalid);
 	return false;

lib/checks/aria/valid-attr-value.json

@@ -6,7 +6,8 @@
 		"impact": "critical",
 		"messages": {
 			"pass": "ARIA attribute values are valid",
-			"fail": "Invalid ARIA attribute value{{=it.data && it.data.length > 1 ? 's' : ''}}:{{~it.data:value}} {{=value}}{{~}}"
+			"fail": "Invalid ARIA attribute value{{=it.data && it.data.length > 1 ? 's' : ''}}:{{~it.data:value}} {{=value}}{{~}}",
+			"incomplete": "ARIA attribute{=it.data && it.data.length > 1 ? 's' : ''}} element ID does not exist on the page:{{~it.data:value}} {{=value}}{{~}}"
 		}
 	}
 }

test/checks/aria/valid-attr-value.js

@@ -205,6 +205,14 @@ describe('aria-valid-attr-value', function() {
 		);
 	});
 
+	it('should return undefined on aria-describedby when the element is not in the DOM', function() {
+		fixtureSetup('<button aria-describedby="test">Button</button>');
+		var undefined1 = fixture.querySelector('button');
+		assert.isUndefined(
+			checks['aria-valid-attr-value'].evaluate.call(checkContext, undefined1)
+		);
+	});
+
 	describe('options', function() {
 		it('should exclude supplied attributes', function() {
 			fixture.innerHTML =

test/integration/rules/aria-valid-attr-value/aria-valid-attr-value.html

@@ -12,7 +12,6 @@ <h2>Violations</h2>
 	<div aria-checked="stuff" id="violation6">hi</div>
 	<div aria-controls="stuff" id="violation7">hi</div>
 	<div aria-current="stage" id="violation8">hi</div>
-	<div aria-describedby="stuff" id="violation9">hi</div>
 	<div aria-disabled="stuff" id="violation10">hi</div>
 	<div aria-dropeffect="stuff" id="violation11">hi</div>
 	<div aria-expanded="stuff" id="violation12">hi</div>
@@ -269,4 +268,6 @@ <h2>Possible False Positives</h2>
 
 	<div id="ref">Hi</div>
 	<div id="ref2">Hi2</div>
+
+	<div aria-describedby="stuff" id="incomplete1">hi</div>
 </div>

test/integration/rules/aria-valid-attr-value/aria-valid-attr-value.json

@@ -10,7 +10,6 @@
 		["#violation6"],
 		["#violation7"],
 		["#violation8"],
-		["#violation9"],
 		["#violation10"],
 		["#violation11"],
 		["#violation12"],
@@ -224,5 +223,6 @@
 		["#pass182"],
 		["#pass183"],
 		["#pass184"]
-	]
+	],
+	"incomplete": [["#incomplete1"]]
 }