Provide ability for WebUIBrowserTests to run asynchronous tests.

chrome/test/data/webui/test_api.js

 // Copyright (c) 2011 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|.
  * @type {Object}
  **/
 var testing = {};
 
 /**
  * Hold the currentTestCase across between PreLoad and Run.
  * @type {TestCase}
  **/
 var currentTestCase = null;
 
+/**
+ * @type {?string} The string representation of the currently running test
+ *     function.
+ */
+var currentTestFunction = null;
+
+/**
+ * @type {?Array} The arguments of the currently running test.
+ */
+var currentTestArguments = null;
+
 (function() {
   // Provide global objects for generation case.
   if (this['window'] === undefined)
     this['window'] = this;
   if (this['chrome'] === undefined) {
     this['chrome'] = {
       send: function() {},
     };
   }
   if (this['console'] === undefined) {
@@ skipping 169 matching lines @@
     }
   }
 
   /**
    * Overrides {@code chrome.send} for routing messages to javascript
    * functions. Also fallsback to sending with the original chrome object.
    * @param {string} messageName The message to route.
    **/
   function send(messageName) {
     var callback = sendCallbacks[messageName];
-    var args = Array.prototype.slice.call(arguments, 1);
     if (callback != undefined)
-      callback[1].apply(callback[0], args);
+      callback[1].apply(callback[0], Array.prototype.slice.call(arguments, 1));
     else
-      this.__proto__.send.apply(this.__proto__, args);
+      this.__proto__.send.apply(this.__proto__, arguments);
   }
 
   /**
    * Provides a mechanism for assert* and expect* methods to fetch the signature
    * of their caller. Assert* methods should |registerCall| and expect* methods
    * should set |isExpect| and |expectName| properties to indicate that the
    * interesting caller is one more level up the stack.
    **/
   function CallHelper() {
     this.__proto__ = CallHelper.prototype;
@@ skipping 77 matching lines @@
       return callMessage;
     },
   };
 
   /**
    * Help register calls for better error reporting.
    * @type {CallHelper}
    **/
   var helper = new CallHelper();
 
+  /**
+   * true when testDone has been called.
+   * @type {boolean}
+   */
+  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 = [];
+
+  /**
+   * 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;
+      chrome.send('testResult', result ? result : testResult());
+      errors.splice(0, errors.length);
+    } else {
+      console.warn('testIsDone already');
+    }
+  }
+
+  /**
+   * Returns [success, message] & clears |errors|.
+   * @return {Array.<boolean, string>}
+   **/
+  function testResult() {
+    var result = [true, ''];
+    if (errors.length) {
+      var message = '';
+      for (var i = 0; i < errors.length; ++i) {
+        message += 'Failed: ' + currentTestFunction + '(' +
+                   currentTestArguments.map(JSON.stringify) +
+                   ')\n' + errors[i].stack;
+      }
+      result = [false, message];
+    }
+    return result;
+  }
+
   // Asserts.
   // Use the following assertions to verify a condition within a test.
-  // If assertion fails, the C++ backend will be immediately notified.
-  // If assertion passes, no notification will be sent to the C++ backend.
+  // If assertion fails, throw an Error with information pertinent to the test.
 
   /**
    * When |test| !== true, aborts the current test.
    * @param {boolean} test The predicate to check against |expected|.
    * @param {string=} message The message to include in the Error thrown.
    * @throws {Error} upon failure.
    **/
   function assertTrue(test, message) {
     helper.registerCall();
     if (test !== true)
@@ skipping 112 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));
   }
 
   /**
-   * Holds the errors, if any, caught by expects so that the test case can fail.
-   * @type {Array.<Error>}
-   **/
-  var errors = [];
-
-  /**
    * 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 overal test if any errors occurrred.
+   * while failing the overall test if any errors occurrred.
    * @param {Function} assertFunc The function which may throw an Error.
    * @return {Function} A function that applies its arguments to |assertFunc|.
    * @see errors
    * @see runTest
    **/
   function createExpect(assertFunc) {
     var expectFunc = function() {
       try {
         assertFunc.apply(null, arguments);
       } catch (e) {
         errors.push(e);
       }
     };
     expectFunc.isExpect = true;
     expectFunc.expectName = assertFunc.name.replace(/^assert/, 'expect');
     return expectFunc;
   }
 
   /**
    * This is the starting point for tests run by WebUIBrowserTest.  If an error
    * occurs, it reports a failure and a message created by joining individual
-   * error messages.
+   * error messages. This supports sync tests and async tests by calling
+   * testDone() when |isAsync| is not true, relying on async tests to call
+   * testDone() when they complete.
+   * @param {boolean} isAsync When false, call testDone() with the test result.
    * @param {string} testFunction The function name to call.
    * @param {Array} testArguments The arguments to call |testFunction| with.
-   * @return {Array.<boolean, string>} [test-succeeded, message-if-failed]
+   * @return {boolean} true always to signal successful execution (but not
+   *     necessarily successful results) of this test.
    * @see errors
    * @see runTestFunction
    **/
-  function runTest(testFunction, testArguments) {
+  function runTest(isAsync, testFunction, testArguments) {
     // Avoid eval() if at all possible, since it will not work on pages
     // that have enabled content-security-policy.
     var testBody = this[testFunction];    // global object -- not a method.
-    if (typeof testBody === "undefined")
+    var testName = testFunction;
+    if (typeof testBody === "undefined") {
       testBody = eval(testFunction);
+      testName = testBody.toString();
+    }
     if (testBody != RUN_TEST_F) {
-      var testName =
-          testFunction.name ? testFunction.name : testBody.toString();
       console.log('Running test ' + testName);
     }
-    return runTestFunction(testFunction, testBody, testArguments);
+    var result = runTestFunction(testFunction, testBody, testArguments);
+    if (!isAsync)
+      testDone(result);
+    return true;
   }
 
   /**
-   * This is the guts of WebUIBrowserTest. It clears |errors|, runs the
-   * test surrounded by an expect to catch Errors. If |errors| is
-   * non-empty, it reports a failure and a message by joining |errors|.
-   * Consumers can use this to use assert/expect functions asynchronously,
-   * but are then responsible for reporting errors to the browser themselves.
+   * This is the guts of WebUIBrowserTest. It runs the test surrounded by an
+   * expect to catch Errors. If |errors| is non-empty, it reports a failure and
+   * a message by joining |errors|. Consumers can use this to use assert/expect
+   * functions asynchronously, but are then responsible for reporting errors to
+   * the browser themselves through testDone().
    * @param {string} testFunction The function name to report on failure.
    * @param {Function} testBody The function to call.
    * @param {Array} testArguments The arguments to call |testBody| with.
    * @return {Array.<boolean, string>} [test-succeeded, message-if-failed]
-   * @see errors
    * @see createExpect
+   * @see testDone
    **/
   function runTestFunction(testFunction, testBody, testArguments) {
-    errors.splice(0, errors.length);
+    currentTestFunction = testFunction;
+    currentTestArguments = testArguments;
     createExpect(testBody).apply(null, testArguments);
-
-    var result = [true];
-    if (errors.length) {
-      var message = '';
-      for (var i = 0; i < errors.length; ++i) {
-        message += 'Failed: ' + testFunction + '(' +
-                   testArguments.map(JSON.stringify) +
-                   ')\n' + errors[i].stack;
-      }
-      errors.splice(0, errors.length);
-      result = [false, message];
-    }
-    return result;
+    return testResult();
   }
 
   /**
    * Creates a new test case for the given |testFixture| and |testName|. Assumes
    * |testFixture| describes a globally available subclass of type Test.
    * @param {string} testFixture The fixture for this test case.
    * @param {string} testName The name for this test case.
    * @return {TestCase} A newly created TestCase.
    **/
   function createTestCase(testFixture, testName) {
@@ skipping 164 matching lines @@
      * @return {string} description of the matcher for this argument.
      **/
     describe: function() {
       return 'SaveArguments(' +
           this.realMatcher_.describe.call(this.realMatcher_) + ')';
     },
   };
 
   // Exports.
   testing.Test = Test;
+  window.testDone = testDone;
   window.assertTrue = assertTrue;
   window.assertFalse = assertFalse;
   window.assertGE = assertGE;
   window.assertGT = assertGT;
   window.assertEquals = assertEquals;
   window.assertLE = assertLE;
   window.assertLT = assertLT;
   window.assertNotEquals = assertNotEquals;
   window.assertNotReached = assertNotReached;
   window.callFunction = callFunction;
   window.expectTrue = createExpect(assertTrue);
   window.expectFalse = createExpect(assertFalse);
   window.expectGE = createExpect(assertGE);
   window.expectGT = createExpect(assertGT);
   window.expectEquals = createExpect(assertEquals);
   window.expectLE = createExpect(assertLE);
   window.expectLT = createExpect(assertLT);
   window.expectNotEquals = createExpect(assertNotEquals);
   window.expectNotReached = createExpect(assertNotReached);
   window.preloadJavascriptLibraries = preloadJavascriptLibraries;
   window.registerMessageCallback = registerMessageCallback;
   window.registerMockMessageCallbacks = registerMockMessageCallbacks;
+  window.resetTestState = resetTestState;
   window.runTest = runTest;
   window.runTestFunction = runTestFunction;
   window.SaveArgumentsMatcher = SaveArgumentsMatcher;
   window.TEST = TEST;
   window.TEST_F = TEST_F;
   window.GEN = GEN;
 
   // Import the Mock4JS helpers.
   Mock4JS.addMockSupport(window);
 })();