fix: Do not require media captions / descriptions (#1075)

Do not require media captions / descriptions
Closes #816 

## 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: @JKODU

build/tasks/validate.js

@@ -27,6 +27,27 @@ function hasUniqueId() {
 	};
 }
 
+function hasMultipleOutcomes(messages) {
+	const keys = Object.keys(messages);
+	if (keys.length < 2) {
+		return false;
+	}
+
+	return keys.every(key => {
+		switch (key) {
+			case 'pass':
+			case 'fail':
+				return typeof messages[key] === 'string';
+
+			case 'incomplete':
+				return ['string', 'object'].includes(typeof messages[key]);
+
+			default:
+				return false;
+		}
+	});
+}
+
 function createSchemas() {
 	var schemas = {};
 
@@ -84,15 +105,9 @@ function createSchemas() {
 					messages: {
 						required: true,
 						type: 'object',
-						properties: {
-							fail: {
-								required: true,
-								type: 'string'
-							},
-							pass: {
-								required: true,
-								type: 'string'
-							}
+						conform: hasMultipleOutcomes,
+						messages: {
+							conform: 'Must have at least two valid messages'
 						}
 					},
 					impact: {

lib/checks/media/caption.js

@@ -1,11 +1,8 @@
-var tracks = axe.utils.querySelectorAll(virtualNode, 'track');
+const tracks = axe.utils.querySelectorAll(virtualNode, 'track');
+const hasCaptions = tracks.some(
+	({ actualNode }) =>
+		(actualNode.getAttribute('kind') || '').toLowerCase() === 'captions'
+);
 
-if (tracks.length) {
-	// return false if any track has kind === 'caption'
-	return !tracks.some(
-		({ actualNode }) =>
-			(actualNode.getAttribute('kind') || '').toLowerCase() === 'captions'
-	);
-}
-// Undefined if there are no tracks - media may be decorative
-return undefined;
+// Undefined if there are no tracks - media may use another caption method
+return hasCaptions ? false : undefined;

lib/checks/media/caption.json

@@ -5,8 +5,7 @@
     "impact": "critical",
     "messages": {
       "pass": "The multimedia element has a captions track",
-      "fail": "The multimedia element does not have a captions track",
-      "incomplete": "A captions track for this element could not be found"
+      "incomplete": "Check that captions is available for the element"
     }
   }
 }

lib/checks/media/description.js

@@ -1,12 +1,8 @@
-var tracks = axe.utils.querySelectorAll(virtualNode, 'track');
+const tracks = axe.utils.querySelectorAll(virtualNode, 'track');
+const hasDescriptions = tracks.some(
+	({ actualNode }) =>
+		(actualNode.getAttribute('kind') || '').toLowerCase() === 'descriptions'
+);
 
-if (tracks.length) {
-	// return false if any track has kind === 'description'
-	var out = !tracks.some(
-		({ actualNode }) =>
-			(actualNode.getAttribute('kind') || '').toLowerCase() === 'descriptions'
-	);
-	return out;
-}
-// Undefined if there are no tracks - media may be decorative
-return undefined;
+// Undefined if there are no tracks - media may have another description method
+return hasDescriptions ? false : undefined;

lib/checks/media/description.json

@@ -5,8 +5,7 @@
     "impact": "critical",
     "messages": {
       "pass": "The multimedia element has an audio description track",
-      "fail": "The multimedia element does not have an audio description track",
-      "incomplete": "An audio description track for this element could not be found"
+      "incomplete": "Check that audio description is available for the element"
     }
   }
 }

test/checks/media/caption.js

@@ -14,17 +14,17 @@ describe('caption', function() {
 		assert.isUndefined(checks.caption.evaluate.apply(null, checkArgs));
 	});
 
-	it('should fail if there is no kind=captions attribute', function() {
+	it('should return undefined if there is no kind=captions attribute', function() {
 		var checkArgs = checkSetup(
 			'<audio><track kind=descriptions></audio>',
 			'audio'
 		);
-		assert.isTrue(checks.caption.evaluate.apply(null, checkArgs));
+		assert.isUndefined(checks.caption.evaluate.apply(null, checkArgs));
 	});
 
-	it('should fail if there is no kind attribute', function() {
+	it('should return undefined if there is no kind attribute', function() {
 		var checkArgs = checkSetup('<video><track></video>', 'video');
-		assert.isTrue(checks.description.evaluate.apply(null, checkArgs));
+		assert.isUndefined(checks.description.evaluate.apply(null, checkArgs));
 	});
 
 	it('should pass if there is a kind=captions attribute', function() {
@@ -36,12 +36,12 @@ describe('caption', function() {
 		'should get track from composed tree',
 		function() {
 			var node = document.createElement('div');
-			node.innerHTML = '<track kind=descriptions>';
+			node.innerHTML = '<track kind=captions>';
 			var shadow = node.attachShadow({ mode: 'open' });
 			shadow.innerHTML = '<audio><slot></slot></audio>';
 
 			var checkArgs = checkSetup(node, {}, 'audio');
-			assert.isTrue(checks.caption.evaluate.apply(null, checkArgs));
+			assert.isFalse(checks.caption.evaluate.apply(null, checkArgs));
 		}
 	);
 });

test/checks/media/description.js

@@ -13,14 +13,14 @@ describe('description', function() {
 		assert.isUndefined(checks.description.evaluate.apply(null, checkArgs));
 	});
 
-	it('should fail if there is no kind=captions attribute', function() {
+	it('should return undefined if there is no kind=captions attribute', function() {
 		var checkArgs = checkSetup('<video><track kind=captions></video>', 'video');
-		assert.isTrue(checks.description.evaluate.apply(null, checkArgs));
+		assert.isUndefined(checks.description.evaluate.apply(null, checkArgs));
 	});
 
-	it('should fail if there is no kind attribute', function() {
+	it('should return undefined if there is no kind attribute', function() {
 		var checkArgs = checkSetup('<video><track></video>', 'video');
-		assert.isTrue(checks.description.evaluate.apply(null, checkArgs));
+		assert.isUndefined(checks.description.evaluate.apply(null, checkArgs));
 	});
 
 	it('should pass if there is a kind=descriptions attribute', function() {

test/integration/rules/video-caption/video-caption.html

@@ -1,4 +1,4 @@
 <video id="incomplete1"></video>
-<video id="fail1"><track kind="descriptions"></video>
+<video id="incomplete2"><track kind="descriptions"></video>
 <video id="pass1"><track kind="captions"></video>
 <video id="pass2"><track kind="descriptions"><track kind="captions"></video>

test/integration/rules/video-caption/video-caption.json

@@ -1,7 +1,6 @@
 {
 	"description": "video-caption test",
 	"rule": "video-caption",
-	"incomplete": [["#incomplete1"]],
-	"violations": [["#fail1"]],
+	"incomplete": [["#incomplete1"], ["#incomplete2"]],
 	"passes": [["#pass1"], ["#pass2"]]
 }

test/integration/rules/video-description/video-description.html

@@ -1,5 +1,5 @@
 
 <video id="incomplete1"></video>
-<video id="fail1"><track kind="captions"></video>
+<video id="incomplete2"><track kind="captions"></video>
 <video id="pass1"><track kind="descriptions"></video>
 <video id="pass2"><track kind="descriptions"><track kind="captions"></video>

test/integration/rules/video-description/video-description.json

@@ -1,7 +1,6 @@
 {
 	"description": "video-description test",
 	"rule": "video-description",
-	"incomplete": [["#incomplete1"]],
-	"violations": [["#fail1"]],
+	"incomplete": [["#incomplete1"], ["#incomplete2"]],
 	"passes": [["#pass1"], ["#pass2"]]
 }