Add an accessibility audit test for WebUI pages

chrome/test/data/webui/test_api.js

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 /**
  * @fileoverview Library providing basic test framework functionality.
  */
 
 /**
  * Namespace for |Test|.
@@ skipping 104 matching lines @@
      */
     testShouldFail: false,
 
     /**
      * Extra libraries to add before loading this test file.
      * @type {Array.<string>}
      */
     extraLibraries: [],
 
     /**
+     * FIXME(aboxhall)
+     */
+    runA11yChecks : true,
+
+    /**
+     * FIXME(aboxhall)
+     * Off by default to begin with; as we add the ability to suppress false
+     * positives, we will transition this to true.
+     */
+    a11yIssuesAreErrors: false,
+
+    /**
      * Create a new class to handle |messageNames|, assign it to
      * |this.mockHandler|, register its messages and return it.
      * @return {Mock} Mock handler class assigned to |this.mockHandler|.
      */
     makeAndRegisterMockHandler: function(messageNames) {
       var MockClass = makeMockClass(messageNames);
       this.mockHandler = mock(MockClass);
       registerMockMessageCallbacks(this.mockHandler, MockClass);
       return this.mockHandler;
     },
@@ skipping 92 matching lines @@
    * This class is not exported and is available to hold the state of the
    * |currentTestCase| throughout preload and test run.
    * @param {string} name The name of the test case.
    * @param {Test} fixture The fixture object for this test case.
    * @param {Function} body The code to run for the test.
    * @constructor
    */
   function TestCase(name, fixture, body) {
     this.name = name;
     this.fixture = fixture;
+    this.runA11yChecks = fixture.runA11yChecks;
+    this.a11yIssuesAreErrors = fixture.a11yIssuesAreErrors;
     this.body = body;
   }
 
   TestCase.prototype = {
     /**
      * The name of this test.
      * @type {string}
      */
     name: null,
 
     /**
      * The test fixture to set |this| to when running the test |body|.
      * @type {testing.Test}
      */
     fixture: null,
 
     /**
      * The test body to execute in runTest().
      * @type {Function}
      */
     body: null,
 
     /**
      * True when the test fixture will run the test later.
      * @type {boolean}
      * @private
      */
     deferred_: false,
 
+    runA11yChecks: true,
+
+    /**
+     * FIXME(aboxhall)
+     */
+    a11yIssuesAreErrors: true,
+
     /**
      * Called at preload time, proxies to the fixture.
      * @type {Function}
      */
     preLoad: function(name) {
       if (this.fixture)
         this.fixture.preLoad();
     },
 
     /**
@@ skipping 302 matching lines @@
   var testIsDone = false;
 
   /**
    * Holds the errors, if any, caught by expects so that the test case can
    * fail. Cleared when results are reported from runTest() or testDone().
    * @type {Array.<Error>}
    */
   var errors = [];
 
   /**
+   * Hold the accessibility warnings and errors, respectively.
+   * Like errors, cleared when results are reported.
+   */
+  var a11y_warnings = [];

[dmazzoni, 2012/12/14 18:45:41]

Use camelCase but make it a private variable with a trailing underscore -
accessibilityWarnings_ 

[aboxhall, 2012/12/14 23:26:44]

Done.

+  var a11y_errors = [];
+
+  function getA11yWarnings() {

[dmazzoni, 2012/12/14 18:45:41]

Should you use js getters?

http://stackoverflow.com/questions/812961/javascript-getters-and-setters-for-...

They seem to be used elsewhere within Chrome's JS codebase

[aboxhall, 2012/12/14 23:26:44]

It won't work in this case as it's not a property of an object.

+    return a11y_warnings;
+  };
+
+  function getA11yErrors() {
+    return a11y_errors;
+  };
+
+  /**
    * URL to dummy WebUI page for testing framework.
    * @type {string}
    */
   var DUMMY_URL = 'chrome://DummyURL';
 
   /**
    * Resets test state by clearing |errors| and |testIsDone| flags.
    */
   function resetTestState() {
     errors.splice(0, errors.length);
     testIsDone = false;
   }
 
   /**
    * Notifies the running browser test of the test results. Clears |errors|.
    * @param {Array.<boolean, string>=} result When passed, this is used for the
    *     testResult message.
    */
   function testDone(result) {
     if (!testIsDone) {
       testIsDone = true;
       if (currentTestCase) {
+        if (currentTestCase.runA11yChecks) {
+          var a11yOk = runAccessibilityAudit(a11y_errors, a11y_warnings);
+          if (!a11yOk) {
+            if (currentTestCase.a11yIssuesAreErrors && result) {
+              result = [false, a11yIssuesToMessage(a11y_errors,
+                                                   a11y_warnings,
+                                                   result[1])];
+            } else
+              console.warn(a11yIssuesToMessage(a11y_errors, a11y_warnings));
+          }
+        }
+
         try {
           currentTestCase.tearDown();
         } catch (e) {
           // Caught an exception in tearDown; Register the error and recreate
           // the result if it is passed in.
           errors.push(e);
           if (result)
             result = [false, errorsToMessage([e], result[1])];
         }
+        if (!result)
+          result = testResult();
         currentTestCase = null;
       }
-      chrome.send('testResult', result ? result : testResult());
+      if (!result)
+        result = testResult();
+      chrome.send('testResult', result);
       errors.splice(0, errors.length);
+      a11y_errors.splice(0, a11y_errors.length);
     } else {
       console.warn('testIsDone already');
     }
   }
 
   /**
    * Converts each Error in |errors| to a suitable message, adding them to
    * |message|, and returns the message string.
    * @param {Array.<Error>} errors Array of errors to add to |message|.
    * @param {string?} message When supplied, error messages are appended to it.
@@ skipping 12 matching lines @@
     return message;
   }
 
   /**
    * Returns [success, message] & clears |errors|.
    * @param {boolean} errorsOk When true, errors are ok.
    * @return {Array.<boolean, string>}
    */
   function testResult(errorsOk) {
     var result = [true, ''];
-    if (errors.length) {
+    if (errors.length)
       result = [!!errorsOk, errorsToMessage(errors)];
+
+    if (currentTestCase &&
+        currentTestCase.a11yIssuesAreErrors &&
+        (a11y_warnings.length || a11y_errors.length)) {
+      result = [!!errorsOk, a11yIssuesToMessage(a11y_errors,
+                                                a11y_warnings,
+                                                result[1])];
     }
     return result;
   }
 
   // Asserts.
   // Use the following assertions to verify a condition within a test.
   // If assertion fails, throw an Error with information pertinent to the test.
 
   /**
    * When |test| !== true, aborts the current test.
@@ skipping 119 matching lines @@
    * Always aborts the current test.
    * @param {string=} message The message to include in the Error thrown.
    * @throws {Error} always.
    */
   function assertNotReached(message) {
     helper.registerCall();
     throw new Error(helper.getCallMessage(message));
   }
 
   /**
+   * Run an accessibility audit on the current page state.
+   * FIXME(aboxhall) documentation
+   * @type {Function}
+   * @return {boolean} Whether there were any errors or warnings
+   * @private
+   */
+  function runAccessibilityAudit(a11yErrors, a11yWarnings) {
+    var auditResults = axs.Audit.run();
+    for (var i = 0; i < auditResults.length; i++) {
+      var result = auditResults[i];
+      if (result.result == axs.constants.AuditResult.FAIL) {

[dmazzoni, 2012/12/14 18:45:41]

result.result is confusing - i wonder if it should be something like "status" or
"resultCode" upstream

[aboxhall, 2012/12/14 23:26:44]

Or I could change result to auditResult?

Changing it upstream is probably a good idea at some point, I agree.

+        var auditRule = result.rule;
+        // TODO(aboxhall): more useful error messages (sadly non-trivial)
+        if (auditRule.severity == axs.constants.Severity.Severe)
+          a11yErrors.push(accessibilityErrorMessage(auditRule, result));
+        else
+          a11yWarnings.push(accessibilityErrorMessage(auditRule, result));
+      }
+    }
+
+    // TODO(aboxhall): have strict (no errors or warnings) vs non-strict
+    // (warnings ok)
+    // TODO(aboxhall): some kind of info logging for warnings only??
+    return (a11yErrors.length == 0 && a11yWarnings.length == 0);
+  }
+
+  function disableA11yChecks() {
+    if (!currentTestCase)
+      return;
+    currentTestCase.runA11yChecks = false;
+  }
+
+  function enableA11yChecks() {
+    if (!currentTestCase)
+      return;
+    currentTestCase.runA11yChecks = true;
+  }
+
+  function a11yIssuesAreErrors(flag) {
+    if (!currentTestCase)
+      return;
+    currentTestCase.a11yIssuesAreErrors = flag;
+  }
+
+  /**
+   * FIXME(aboxhall) documentation
+   */
+  function a11yIssuesToMessage(a11y_errors, a11y_warnings, message) {

[dmazzoni, 2012/12/14 18:45:41]

It might be cleaner here to just have this function return the message, then
create a tiny helper function to append a string with initial newlines because
they're multi-line log messages.

[aboxhall, 2012/12/14 23:26:44]

I collapsed it into one line; hopefully that's a bit less obtrusive. I couldn't
see anywhere else where the method might be used.

+    if (message)
+      message += '\n\n';
+    else
+      message = '\n';
+
+    message += 'An accessibility audit found ';
+
+    if (a11y_errors.length > 0) {
+      message += a11y_errors.length +
+        (a11y_errors.length == 1 ? ' error ' : ' errors ');
+      if (a11y_warnings.length > 0)
+        message += 'and ';
+    }
+    if (a11y_warnings.length > 0) {
+      message += a11y_warnings.length +
+        (a11y_warnings.length == 1 ? ' warning ' : ' warnings ');
+    }
+    message += 'on this page.\n';
+    message += 'For more information, please see ' +
+      'https://sites.google.com/a/chromium.org/dev/webui-accessibility-audit';

[dmazzoni, 2012/12/14 18:45:41]

This url is shorter and should be the same:

http://chromium.org/webui-accessibility-audit

Although, I think you should probably move it from the top level first - most
other accessibility documentation has a url more like this:

http://chromium.org/developers/accessibility/windows-accessibility

[aboxhall, 2012/12/14 23:26:44]

Done.

+
+    for (var i = 0; i < a11y_errors.length; i++)
+      message += '\n\n' + a11y_errors[i];
+
+    for (var i = 0; i < a11y_warnings.length; i++)
+      message += '\n\n' + a11y_warnings[i];
+    return message;
+  }
+
+  /**
+   * FIXME(aboxhall): documentation
+   */
+  function accessibilityErrorMessage(rule, result) {
+    if (rule.severity == axs.constants.Severity.Severe)
+      var message = 'Error: '
+    else
+      var message = 'Warning: '
+    message += rule.name + ' failed on the following ' +
+      (result.elements.length == 1 ? 'element' : 'elements');
+
+    if (result.elements.length == 1)
+      message += ':'
+    else
+      message += ' (1 - ' + Math.min(5, result.elements.length) +
+                 ' of ' + result.elements.length + '):';
+
+    for (var i = 0; i < Math.min(result.elements.length, 5); i++)

[dmazzoni, 2012/12/14 18:45:41]

Do the Math.min just once

[aboxhall, 2012/12/14 23:26:44]

Done.

+      message += '\n' + axs.utils.getQuerySelectorText(result.elements[i]);
+    return message;
+  }
+
+  /**
+   * FIXME(aboxhall) documentation
+   */
+  function assertAccessibilityOk() {
+    helper.registerCall();
+    var a11y_errors = [];

[dmazzoni, 2012/12/14 18:45:41]

var a11yErrors (no underscores in js variables normally)

[aboxhall, 2012/12/14 23:26:44]

Done.

+    var a11y_warnings = [];
+    if (!runAccessibilityAudit(a11y_errors, a11y_warnings))
+      throw new Error(a11yIssuesToMessage(a11y_errors, a11y_warnings));
+  }
+
+  /**
    * Creates a function based upon a function that thows an exception on
    * failure. The new function stuffs any errors into the |errors| array for
    * checking by runTest. This allows tests to continue running other checks,
    * while failing the overall test if any errors occurrred.
    * @param {Function} assertFunc The function which may throw an Error.
    * @return {function(...*):bool} A function that applies its arguments to
    *     |assertFunc| and returns true if |assertFunc| passes.
    * @see errors
    * @see runTestFunction
    */
@@ skipping 555 matching lines @@
    * @return {RunAllAction} Action for use in will.
    */
   function runAllActionsAsync(whenTestDone) {
     return new RunAllAction(true, whenTestDone,
                             Array.prototype.slice.call(arguments, 1));
   }
 
   // Exports.
   testing.Test = Test;
   exports.testDone = testDone;
+  exports.a11yIssuesAreErrors = a11yIssuesAreErrors;
   exports.assertTrue = assertTrue;
   exports.assertFalse = assertFalse;
   exports.assertGE = assertGE;
   exports.assertGT = assertGT;
   exports.assertEquals = assertEquals;
   exports.assertLE = assertLE;
   exports.assertLT = assertLT;
   exports.assertNotEquals = assertNotEquals;
   exports.assertNotReached = assertNotReached;
+  exports.assertAccessibilityOk = assertAccessibilityOk;
   exports.callFunction = callFunction;
   exports.callFunctionWithSavedArgs = callFunctionWithSavedArgs;
   exports.callGlobalWithSavedArgs = callGlobalWithSavedArgs;
+  exports.disableA11yChecks = disableA11yChecks;
+  exports.enableA11yChecks = enableA11yChecks;
   exports.expectTrue = createExpect(assertTrue);
   exports.expectFalse = createExpect(assertFalse);
   exports.expectGE = createExpect(assertGE);
   exports.expectGT = createExpect(assertGT);
   exports.expectEquals = createExpect(assertEquals);
   exports.expectLE = createExpect(assertLE);
   exports.expectLT = createExpect(assertLT);
   exports.expectNotEquals = createExpect(assertNotEquals);
   exports.expectNotReached = createExpect(assertNotReached);
+  exports.expectAccessibilityOk = createExpect(assertAccessibilityOk);
+  exports.getA11yErrors = getA11yErrors;
+  exports.getA11yWarnings = getA11yWarnings;
   exports.preloadJavascriptLibraries = preloadJavascriptLibraries;
   exports.registerMessageCallback = registerMessageCallback;
   exports.registerMockGlobals = registerMockGlobals;
   exports.registerMockMessageCallbacks = registerMockMessageCallbacks;
   exports.resetTestState = resetTestState;
+  exports.runAccessibilityAudit = runAccessibilityAudit;
   exports.runAllActions = runAllActions;
   exports.runAllActionsAsync = runAllActionsAsync;
   exports.runTest = runTest;
   exports.runTestFunction = runTestFunction;
   exports.SaveMockArguments = SaveMockArguments;
   exports.DUMMY_URL = DUMMY_URL;
   exports.TEST = TEST;
   exports.TEST_F = TEST_F;
+  exports.RUNTIME_TEST_F = TEST_F;
   exports.GEN = GEN;
   exports.GEN_INCLUDE = GEN_INCLUDE;
   exports.WhenTestDone = WhenTestDone;
 
   // Import the Mock4JS helpers.
   Mock4JS.addMockSupport(exports);
 })(this);