fix: Make empty role=lisbox elements as incomplete (#927)

lib/checks/aria/required-children.js

@@ -1,7 +1,8 @@
-var requiredOwned = axe.commons.aria.requiredOwned,
-	implicitNodes = axe.commons.aria.implicitNodes,
-	matchesSelector = axe.commons.utils.matchesSelector,
-	idrefs = axe.commons.dom.idrefs;
+const requiredOwned = axe.commons.aria.requiredOwned;
+const implicitNodes = axe.commons.aria.implicitNodes;
+const matchesSelector = axe.commons.utils.matchesSelector;
+const idrefs = axe.commons.dom.idrefs;
+const reviewEmpty = options && Array.isArray(options.reviewEmpty) ? options.reviewEmpty : [];
 
 function owns(node, virtualTree, role, ariaOwned) {
 	if (node === null) { return false; }
@@ -86,4 +87,9 @@ var missing = missingRequiredChildren(node, childRoles, all, role);
 if (!missing) { return true; }
 
 this.data(missing);
-return false;
+
+if (reviewEmpty.includes(role)) {
+	return undefined;
+} else {
+	return false;
+}

lib/checks/aria/required-children.json

@@ -1,11 +1,15 @@
 {
   "id": "aria-required-children",
   "evaluate": "required-children.js",
+  "options": {
+    "reviewEmpty": ["listbox"]
+  },
   "metadata": {
     "impact": "critical",
     "messages": {
       "pass": "Required ARIA children are present",
-      "fail": "Required ARIA {{=it.data && it.data.length > 1 ? 'children' : 'child'}} role not present:{{~it.data:value}} {{=value}}{{~}}"
+      "fail": "Required ARIA {{=it.data && it.data.length > 1 ? 'children' : 'child'}} role not present:{{~it.data:value}} {{=value}}{{~}}",
+      "incomplete": "Expecting ARIA {{=it.data && it.data.length > 1 ? 'children' : 'child'}} role to be added:{{~it.data:value}} {{=value}}{{~}}"
     }
   }
 }

test/checks/aria/required-children.js

@@ -165,4 +165,32 @@ describe('aria-required-children', function () {
 		assert.isTrue(checks['aria-required-children'].evaluate.apply(checkContext, params));
 	});
 
+	describe('options', function () {
+		it('should return undefined instead of false when the role is in options.reviewEmpty', function () {
+			var params = checkSetup('<div role="grid" id="target"></div>');
+			assert.isFalse(checks['aria-required-children'].evaluate.apply(checkContext, params));
+
+			// Options:
+			params[1] = {
+				reviewEmpty: ['grid']
+			}
+			assert.isUndefined(checks['aria-required-children'].evaluate.apply(checkContext, params));
+		});
+
+		it('should not throw when options is incorrect', function () {
+			var params = checkSetup('<div role="grid" id="target"></div>');
+
+			// Options: (incorrect)
+			params[1] = ['grid']
+			assert.isFalse(checks['aria-required-children'].evaluate.apply(checkContext, params));
+
+			// Options: (incorrect)
+			params[1] = null
+			assert.isFalse(checks['aria-required-children'].evaluate.apply(checkContext, params));
+
+			// Options: (incorrect)
+			params[1] = 'grid'
+			assert.isFalse(checks['aria-required-children'].evaluate.apply(checkContext, params));
+		});
+	});
 });

test/integration/rules/aria-required-children/aria-required-children.html

@@ -8,3 +8,5 @@
 <div role="menuitem" id="pass6"></div>
 <div role="list" id="pass7" aria-owns="parent"></div>
 <div id="parent"><div role="listitem" id="pass8"></div></div>
+<div role="listbox" id="incomplete1"></div>
+

test/integration/rules/aria-required-children/aria-required-children.json

@@ -15,5 +15,8 @@
 		["#pass6"],
 		["#pass7"],
 		["#pass8"]
+	],
+	"incomplete": [
+		["#incomplete1"]
 	]
 }