Debian Codegraph @

closure-library/closure/goog/testing/testcase.js

raw
1 // Copyright 2007 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview A class representing a set of test functions to be run.
17 *
18 * Testing code should not have dependencies outside of goog.testing so as to
19 * reduce the chance of masking missing dependencies.
20 *
21 * This file does not compile correctly with --collapse_properties. Use
22 * --property_renaming=ALL_UNQUOTED instead.
23 *
24 */
25
26 goog.setTestOnly('goog.testing.TestCase');
27 goog.provide('goog.testing.TestCase');
28 goog.provide('goog.testing.TestCase.Error');
29 goog.provide('goog.testing.TestCase.Order');
30 goog.provide('goog.testing.TestCase.Result');
31 goog.provide('goog.testing.TestCase.Test');
32
33
34 goog.require('goog.Promise');
35 goog.require('goog.Thenable');
36 goog.require('goog.array');
37 goog.require('goog.asserts');
38 goog.require('goog.dom');
39 goog.require('goog.dom.TagName');
40 goog.require('goog.json');
41 goog.require('goog.object');
42 goog.require('goog.testing.JsUnitException');
43 goog.require('goog.testing.asserts');
44
45
46
47 /**
48 * A class representing a JsUnit test case. A TestCase is made up of a number
49 * of test functions which can be run. Individual test cases can override the
50 * following functions to set up their test environment:
51 * - runTests - completely override the test's runner
52 * - setUpPage - called before any of the test functions are run
53 * - tearDownPage - called after all tests are finished
54 * - setUp - called before each of the test functions
55 * - tearDown - called after each of the test functions
56 * - shouldRunTests - called before a test run, all tests are skipped if it
57 * returns false. Can be used to disable tests on browsers
58 * where they aren't expected to pass.
59 * <p>
60 * TestCase objects are usually constructed by inspecting the global environment
61 * to discover functions that begin with the prefix <code>test</code>.
62 * (See {@link #autoDiscoverLifecycle} and {@link #autoDiscoverTests}.)
63 * </p>
64 *
65 * <h2>Testing asychronous code with promises</h2>
66 *
67 * <p>
68 * In the simplest cases, the behavior that the developer wants to test
69 * is synchronous, and the test functions exercising the behavior execute
70 * synchronously. But TestCase can also be used to exercise asynchronous code
71 * through the use of <a
72 * href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">
73 * promises</a>. If a test function returns an object that has a
74 * <code>then</code> method defined on it, the test framework switches to an
75 * asynchronous execution strategy: the next test function will not begin
76 * execution until the returned promise is resolved or rejected. Instead of
77 * writing test assertions at the top level inside a test function, the test
78 * author chains them on the end of the returned promise. For example:
79 * </p>
80 * <pre>
81 * function testPromiseBasedAPI() {
82 * return promiseBasedAPI().then(function(value) {
83 * // Will run when the promise resolves, and before the next
84 * // test function begins execution.
85 * assertEquals('foo', value.bar);
86 * });
87 * }
88 * </pre>
89 * <p>
90 * Synchronous and asynchronous tests can be mixed in the same TestCase.
91 * Test functions that return an object with a <code>then</code> method are
92 * executed asynchronously, and all other test functions are executed
93 * synchronously. While this is convenient for test authors (since it doesn't
94 * require any explicit configuration for asynchronous tests), it can lead to
95 * confusion if the test author forgets to return the promise from the test
96 * function. For example:
97 * </p>
98 * <pre>
99 * function testPromiseBasedAPI() {
100 * // This test should never succeed.
101 * promiseBasedAPI().then(fail, fail);
102 * // Oops! The promise isn't returned to the framework,
103 * // so this test actually does succeed.
104 * }
105 * </pre>
106 * <p>
107 * Since the test framework knows nothing about the promise created
108 * in the test function, it will run the function synchronously, record
109 * a success, and proceed immediately to the next test function.
110 * </p>
111 * <p>
112 * Promises returned from test functions can time out. If a returned promise
113 * is not resolved or rejected within {@link promiseTimeout} milliseconds,
114 * the test framework rejects the promise without a timeout error message.
115 * Test cases can configure the value of {@code promiseTimeout} by setting
116 * <pre>
117 * goog.testing.TestCase.getActiveTestCase().promiseTimeout = ...
118 * </pre>
119 * in their {@code setUpPage} methods.
120 * </p>
121 *
122 * @param {string=} opt_name The name of the test case, defaults to
123 * 'Untitled Test Case'.
124 * @constructor
125 */
126 goog.testing.TestCase = function(opt_name) {
127 /**
128 * A name for the test case.
129 * @type {string}
130 * @private
131 */
132 this.name_ = opt_name || 'Untitled Test Case';
133
134 /**
135 * Array of test functions that can be executed.
136 * @type {!Array<!goog.testing.TestCase.Test>}
137 * @private
138 */
139 this.tests_ = [];
140
141 /**
142 * Set of test names and/or indices to execute, or null if all tests should
143 * be executed.
144 *
145 * Indices are included to allow automation tools to run a subset of the
146 * tests without knowing the exact contents of the test file.
147 *
148 * Indices should only be used with SORTED ordering.
149 *
150 * Example valid values:
151 * <ul>
152 * <li>[testName]
153 * <li>[testName1, testName2]
154 * <li>[2] - will run the 3rd test in the order specified
155 * <li>[1,3,5]
156 * <li>[testName1, testName2, 3, 5] - will work
157 * <ul>
158 * @type {Object}
159 * @private
160 */
161 this.testsToRun_ = null;
162
163 /**
164 * A call back for each test.
165 * @private {?function(goog.testing.TestCase.Test, !Array<string>)}
166 */
167 this.testDone_ = null;
168
169 /**
170 * The order to run the auto-discovered tests in.
171 * @type {string}
172 */
173 this.order = goog.testing.TestCase.Order.SORTED;
174
175 /** @private {function(!goog.testing.TestCase.Result)} */
176 this.runNextTestCallback_ = goog.nullFunction;
177
178 /**
179 * The currently executing test case or null.
180 * @private {?goog.testing.TestCase.Test}
181 */
182 this.curTest_ = null;
183
184 /**
185 * Object used to encapsulate the test results.
186 * @type {!goog.testing.TestCase.Result}
187 * @protected
188 * @suppress {underscore|visibility}
189 */
190 this.result_ = new goog.testing.TestCase.Result(this);
191
192 /**
193 * An array of exceptions generated by {@code assert} statements.
194 * @private {!Array<!goog.testing.JsUnitException>}
195 */
196 this.thrownAssertionExceptions_ = [];
197
198 /**
199 * Whether the test should fail if exceptions arising from an assert statement
200 * never bubbled up to the testing framework.
201 * @type {boolean}
202 */
203 this.failOnUnreportedAsserts = true;
204
205 /**
206 * The maximum time in milliseconds a promise returned from a test function
207 * may remain pending before the test fails due to timeout.
208 * @type {number}
209 */
210 this.promiseTimeout = 1000; // 1s
211 };
212
213
214 /**
215 * The order to run the auto-discovered tests.
216 * @enum {string}
217 */
218 goog.testing.TestCase.Order = {
219 /**
220 * This is browser dependent and known to be different in FF and Safari
221 * compared to others.
222 */
223 NATURAL: 'natural',
224
225 /** Random order. */
226 RANDOM: 'random',
227
228 /** Sorted based on the name. */
229 SORTED: 'sorted'
230 };
231
232
233 /**
234 * @return {string} The name of the test.
235 */
236 goog.testing.TestCase.prototype.getName = function() {
237 return this.name_;
238 };
239
240 /**
241 * Returns the current test or null.
242 * @return {?goog.testing.TestCase.Test}
243 * @protected
244 */
245 goog.testing.TestCase.prototype.getCurrentTest = function() {
246 return this.curTest_;
247 };
248
249 /**
250 * The maximum amount of time in milliseconds that the test case can take
251 * before it is forced to yield and reschedule. This prevents the test runner
252 * from blocking the browser and potentially hurting the test harness.
253 * @type {number}
254 */
255 goog.testing.TestCase.maxRunTime = 200;
256
257
258 /**
259 * Save a reference to {@code window.setTimeout}, so any code that overrides the
260 * default behavior (the MockClock, for example) doesn't affect our runner.
261 * @type {function((Function|string), number=, *=): number}
262 * @private
263 */
264 goog.testing.TestCase.protectedSetTimeout_ = goog.global.setTimeout;
265
266
267 /**
268 * Save a reference to {@code window.clearTimeout}, so any code that overrides
269 * the default behavior (e.g. MockClock) doesn't affect our runner.
270 * @type {function((null|number|undefined)): void}
271 * @private
272 */
273 goog.testing.TestCase.protectedClearTimeout_ = goog.global.clearTimeout;
274
275
276 /**
277 * Save a reference to {@code window.Date}, so any code that overrides
278 * the default behavior doesn't affect our runner.
279 * @type {function(new: Date)}
280 * @private
281 */
282 goog.testing.TestCase.protectedDate_ = Date;
283
284 /**
285 * Save a reference to {@code window.performance}, so any code that overrides
286 * the default behavior doesn't affect our runner.
287 * @type {?Performance}
288 * @private
289 */
290 goog.testing.TestCase.protectedPerformance_ =
291 window.performance && window.performance.now ? performance : null;
292
293
294 /**
295 * Name of the current test that is running, or null if none is running.
296 * @type {?string}
297 */
298 goog.testing.TestCase.currentTestName = null;
299
300
301 /**
302 * Avoid a dependency on goog.userAgent and keep our own reference of whether
303 * the browser is IE.
304 * @type {boolean}
305 */
306 goog.testing.TestCase.IS_IE = typeof opera == 'undefined' &&
307 !!goog.global.navigator &&
308 goog.global.navigator.userAgent.indexOf('MSIE') != -1;
309
310
311 /**
312 * Exception object that was detected before a test runs.
313 * @type {*}
314 * @protected
315 */
316 goog.testing.TestCase.prototype.exceptionBeforeTest;
317
318
319 /**
320 * Whether the test case has ever tried to execute.
321 * @type {boolean}
322 */
323 goog.testing.TestCase.prototype.started = false;
324
325
326 /**
327 * Whether the test case is running.
328 * @type {boolean}
329 */
330 goog.testing.TestCase.prototype.running = false;
331
332
333 /**
334 * Timestamp for when the test was started.
335 * @type {number}
336 * @private
337 */
338 goog.testing.TestCase.prototype.startTime_ = 0;
339
340
341 /**
342 * Time since the last batch of tests was started, if batchTime exceeds
343 * {@link #maxRunTime} a timeout will be used to stop the tests blocking the
344 * browser and a new batch will be started.
345 * @type {number}
346 * @private
347 */
348 goog.testing.TestCase.prototype.batchTime_ = 0;
349
350
351 /**
352 * Pointer to the current test.
353 * @type {number}
354 * @private
355 */
356 goog.testing.TestCase.prototype.currentTestPointer_ = 0;
357
358
359 /**
360 * Optional callback that will be executed when the test has finalized.
361 * @type {Function}
362 * @private
363 */
364 goog.testing.TestCase.prototype.onCompleteCallback_ = null;
365
366
367 /**
368 * Adds a new test to the test case.
369 * @param {!goog.testing.TestCase.Test} test The test to add.
370 */
371 goog.testing.TestCase.prototype.add = function(test) {
372 goog.asserts.assert(test);
373 if (this.started) {
374 throw new Error(
375 'Tests cannot be added after execute() has been called. ' +
376 'Test: ' + test.name);
377 }
378
379 this.tests_.push(test);
380 };
381
382
383 /**
384 * Creates and adds a new test.
385 *
386 * Convenience function to make syntax less awkward when not using automatic
387 * test discovery.
388 *
389 * @param {string} name The test name.
390 * @param {function()} ref Reference to the test function.
391 * @param {!Object=} scope Optional scope that the test function should be
392 * called in.
393 * @param {!Array<!Object>=} objChain An array of Objects that may have
394 * additional set up/tear down logic for a particular test.
395 */
396 goog.testing.TestCase.prototype.addNewTest = function(
397 name, ref, scope, objChain) {
398 this.add(this.createTest(name, ref, scope || this, objChain));
399 };
400
401
402 /**
403 * Sets the tests.
404 * @param {!Array<goog.testing.TestCase.Test>} tests A new test array.
405 * @protected
406 */
407 goog.testing.TestCase.prototype.setTests = function(tests) {
408 this.tests_ = tests;
409 };
410
411
412 /**
413 * Gets the tests.
414 * @return {!Array<goog.testing.TestCase.Test>} The test array.
415 */
416 goog.testing.TestCase.prototype.getTests = function() {
417 return this.tests_;
418 };
419
420
421 /**
422 * Returns the number of tests contained in the test case.
423 * @return {number} The number of tests.
424 */
425 goog.testing.TestCase.prototype.getCount = function() {
426 return this.tests_.length;
427 };
428
429
430 /**
431 * Returns the number of tests actually run in the test case, i.e. subtracting
432 * any which are skipped.
433 * @return {number} The number of un-ignored tests.
434 */
435 goog.testing.TestCase.prototype.getActuallyRunCount = function() {
436 return this.testsToRun_ ? goog.object.getCount(this.testsToRun_) : 0;
437 };
438
439
440 /**
441 * Returns the current test and increments the pointer.
442 * @return {goog.testing.TestCase.Test} The current test case.
443 */
444 goog.testing.TestCase.prototype.next = function() {
445 var test;
446 while ((test = this.tests_[this.currentTestPointer_++])) {
447 if (!this.testsToRun_ || this.testsToRun_[test.name] ||
448 this.testsToRun_[this.currentTestPointer_ - 1]) {
449 return test;
450 }
451 }
452 return null;
453 };
454
455
456 /**
457 * Resets the test case pointer, so that next returns the first test.
458 */
459 goog.testing.TestCase.prototype.reset = function() {
460 this.currentTestPointer_ = 0;
461 this.result_ = new goog.testing.TestCase.Result(this);
462 };
463
464
465 /**
466 * Sets the callback function that should be executed when the tests have
467 * completed.
468 * @param {Function} fn The callback function.
469 */
470 goog.testing.TestCase.prototype.setCompletedCallback = function(fn) {
471 this.onCompleteCallback_ = fn;
472 };
473
474
475 /**
476 * @param {goog.testing.TestCase.Order} order The sort order for running tests.
477 */
478 goog.testing.TestCase.prototype.setOrder = function(order) {
479 this.order = order;
480 };
481
482
483 /**
484 * @param {Object<string, boolean>} testsToRun Set of tests to run. Entries in
485 * the set may be test names, like "testFoo", or numeric indicies. Only
486 * tests identified by name or by index will be executed.
487 */
488 goog.testing.TestCase.prototype.setTestsToRun = function(testsToRun) {
489 this.testsToRun_ = testsToRun;
490 };
491
492
493 /**
494 * Can be overridden in test classes to indicate whether the tests in a case
495 * should be run in that particular situation. For example, this could be used
496 * to stop tests running in a particular browser, where browser support for
497 * the class under test was absent.
498 * @return {boolean} Whether any of the tests in the case should be run.
499 */
500 goog.testing.TestCase.prototype.shouldRunTests = function() {
501 return true;
502 };
503
504
505 /**
506 * Executes the tests, yielding asynchronously if execution time exceeds
507 * {@link maxRunTime}. There is no guarantee that the test case has finished
508 * once this method has returned. To be notified when the test case
509 * has finished, use {@link #setCompletedCallback} or
510 * {@link #runTestsReturningPromise}.
511 */
512 goog.testing.TestCase.prototype.execute = function() {
513 if (!this.prepareForRun_()) {
514 return;
515 }
516 this.log('Starting tests: ' + this.name_);
517 this.cycleTests();
518 };
519
520
521 /**
522 * Sets up the internal state of the test case for a run.
523 * @return {boolean} If false, preparation failed because the test case
524 * is not supposed to run in the present environment.
525 * @private
526 */
527 goog.testing.TestCase.prototype.prepareForRun_ = function() {
528 this.started = true;
529 this.reset();
530 this.startTime_ = this.now();
531 this.running = true;
532 this.result_.totalCount = this.getCount();
533 if (!this.shouldRunTests()) {
534 this.log('shouldRunTests() returned false, skipping these tests.');
535 this.result_.testSuppressed = true;
536 this.finalize();
537 return false;
538 }
539 return true;
540 };
541
542
543 /**
544 * Finalizes the test case, called when the tests have finished executing.
545 */
546 goog.testing.TestCase.prototype.finalize = function() {
547 this.saveMessage('Done');
548
549 this.tearDownPage();
550
551 this.endTime_ = this.now();
552 this.running = false;
553 this.result_.runTime = this.endTime_ - this.startTime_;
554 this.result_.numFilesLoaded = this.countNumFilesLoaded_();
555 this.result_.complete = true;
556
557 this.log(this.result_.getSummary());
558 if (this.result_.isSuccess()) {
559 this.log('Tests complete');
560 } else {
561 this.log('Tests Failed');
562 }
563 if (this.onCompleteCallback_) {
564 var fn = this.onCompleteCallback_;
565 // Execute's the completed callback in the context of the global object.
566 fn();
567 this.onCompleteCallback_ = null;
568 }
569 };
570
571
572 /**
573 * Saves a message to the result set.
574 * @param {string} message The message to save.
575 */
576 goog.testing.TestCase.prototype.saveMessage = function(message) {
577 this.result_.messages.push(this.getTimeStamp_() + ' ' + message);
578 };
579
580
581 /**
582 * @return {boolean} Whether the test case is running inside the multi test
583 * runner.
584 */
585 goog.testing.TestCase.prototype.isInsideMultiTestRunner = function() {
586 var top = goog.global['top'];
587 return top && typeof top['_allTests'] != 'undefined';
588 };
589
590
591 /**
592 * Logs an object to the console, if available.
593 * @param {*} val The value to log. Will be ToString'd.
594 */
595 goog.testing.TestCase.prototype.log = function(val) {
596 if (!this.isInsideMultiTestRunner() && goog.global.console) {
597 if (typeof val == 'string') {
598 val = this.getTimeStamp_() + ' : ' + val;
599 }
600 if (val instanceof Error && val.stack) {
601 // Chrome does console.log asynchronously in a different process
602 // (http://code.google.com/p/chromium/issues/detail?id=50316).
603 // This is an acute problem for Errors, which almost never survive.
604 // Grab references to the immutable strings so they survive.
605 goog.global.console.log(val, val.message, val.stack);
606 // TODO(gboyer): Consider for Chrome cloning any object if we can ensure
607 // there are no circular references.
608 } else {
609 goog.global.console.log(val);
610 }
611 }
612 };
613
614
615 /**
616 * @return {boolean} Whether the test was a success.
617 */
618 goog.testing.TestCase.prototype.isSuccess = function() {
619 return !!this.result_ && this.result_.isSuccess();
620 };
621
622
623 /**
624 * Returns a string detailing the results from the test.
625 * @param {boolean=} opt_verbose If true results will include data about all
626 * tests, not just what failed.
627 * @return {string} The results from the test.
628 */
629 goog.testing.TestCase.prototype.getReport = function(opt_verbose) {
630 var rv = [];
631
632 if (this.running) {
633 rv.push(this.name_ + ' [RUNNING]');
634 } else if (this.result_.runCount == 0) {
635 rv.push(this.name_ + ' [NO TESTS RUN]');
636 } else {
637 var label = this.result_.isSuccess() ? 'PASSED' : 'FAILED';
638 rv.push(this.name_ + ' [' + label + ']');
639 }
640
641 if (goog.global.location) {
642 rv.push(this.trimPath_(goog.global.location.href));
643 }
644
645 rv.push(this.result_.getSummary());
646
647 if (opt_verbose) {
648 rv.push('.', this.result_.messages.join('\n'));
649 } else if (!this.result_.isSuccess()) {
650 rv.push(this.result_.errors.join('\n'));
651 }
652
653 rv.push(' ');
654
655 return rv.join('\n');
656 };
657
658
659 /**
660 * Returns the test results.
661 * @return {!goog.testing.TestCase.Result}
662 * @package
663 */
664 goog.testing.TestCase.prototype.getResult = function() {
665 return this.result_;
666 };
667
668
669 /**
670 * Returns the amount of time it took for the test to run.
671 * @return {number} The run time, in milliseconds.
672 */
673 goog.testing.TestCase.prototype.getRunTime = function() {
674 return this.result_.runTime;
675 };
676
677
678 /**
679 * Returns the number of script files that were loaded in order to run the test.
680 * @return {number} The number of script files.
681 */
682 goog.testing.TestCase.prototype.getNumFilesLoaded = function() {
683 return this.result_.numFilesLoaded;
684 };
685
686
687 /**
688 * Represents a test result.
689 * @typedef {{
690 * 'source': string,
691 * 'message': string,
692 * 'stacktrace': string
693 * }}
694 */
695 goog.testing.TestCase.IResult;
696
697 /**
698 * Returns the test results object: a map from test names to a list of test
699 * failures (if any exist).
700 * @return {!Object<string, !Array<goog.testing.TestCase.IResult>>} Test
701 * results object.
702 */
703 goog.testing.TestCase.prototype.getTestResults = function() {
704 var map = {};
705 goog.object.forEach(this.result_.resultsByName, function(resultArray, key) {
706 // Make sure we only use properties on the actual map
707 if (!Object.prototype.hasOwnProperty.call(
708 this.result_.resultsByName, key)) {
709 return;
710 }
711 map[key] = [];
712 for (var j = 0; j < resultArray.length; j++) {
713 map[key].push(resultArray[j].toObject_());
714 }
715 }, this);
716 return map;
717 };
718
719 /**
720 * Returns the test results as json.
721 * This is called by the testing infrastructure through G_testrunner.
722 * @return {string} Tests results object.
723 */
724 goog.testing.TestCase.prototype.getTestResultsAsJson = function() {
725 return goog.json.serialize(this.getTestResults());
726 };
727
728 /**
729 * Executes each of the tests, yielding asynchronously if execution time
730 * exceeds {@link #maxRunTime}. There is no guarantee that the test case
731 * has finished execution once this method has returned.
732 * To be notified when the test case has finished execution, use
733 * {@link #setCompletedCallback} or {@link #runTestsReturningPromise}.
734 *
735 * Overridable by the individual test case. This allows test cases to defer
736 * when the test is actually started. If overridden, finalize must be
737 * called by the test to indicate it has finished.
738 */
739 goog.testing.TestCase.prototype.runTests = function() {
740 goog.testing.Continuation_.run(this.runSetUpPage_(this.execute));
741 };
742
743
744 /**
745 * Executes each of the tests, returning a promise that resolves with the
746 * test results once they are done running.
747 * @return {!IThenable<!goog.testing.TestCase.Result>}
748 * @final
749 * @package
750 */
751 goog.testing.TestCase.prototype.runTestsReturningPromise = function() {
752 return new goog.Promise(function(resolve) {
753 goog.testing.Continuation_.run(this.runSetUpPage_(function() {
754 if (!this.prepareForRun_()) {
755 resolve(this.result_);
756 return;
757 }
758 this.log('Starting tests: ' + this.name_);
759 this.saveMessage('Start');
760 this.batchTime_ = this.now();
761 this.runNextTestCallback_ = resolve;
762 goog.testing.Continuation_.run(this.runNextTest_());
763 }));
764 }, this);
765 };
766
767
768 /**
769 * Runs the setUpPage methods.
770 * @param {function(this:goog.testing.TestCase)} runTestsFn Callback to invoke
771 * after setUpPage has completed.
772 * @return {?goog.testing.Continuation_}
773 * @private
774 */
775 goog.testing.TestCase.prototype.runSetUpPage_ = function(runTestsFn) {
776 return this.invokeFunction_(this.setUpPage, runTestsFn, function(e) {
777 this.exceptionBeforeTest = e;
778 runTestsFn.call(this);
779 }, 'setUpPage');
780 };
781
782
783 /**
784 * Executes the next test method synchronously or with promises, depending on
785 * the test method's return value.
786 *
787 * If the test method returns a promise, the next test method will run once
788 * the promise is resolved or rejected. If the test method does not
789 * return a promise, it is assumed to be synchronous, and execution proceeds
790 * immediately to the next test method. This means that test cases can run
791 * partially synchronously and partially asynchronously, depending on
792 * the return values of their test methods. In particular, a test case
793 * executes synchronously until the first promise is returned from a
794 * test method (or until a resource limit is reached; see
795 * {@link finishTestInvocation_}).
796 * @return {?goog.testing.Continuation_}
797 * @private
798 */
799 goog.testing.TestCase.prototype.runNextTest_ = function() {
800 this.curTest_ = this.next();
801 if (!this.curTest_ || !this.running) {
802 this.finalize();
803 return new goog.testing.Continuation_(
804 goog.bind(this.runNextTestCallback_, this, this.result_));
805 }
806 this.curTest_.started();
807 this.result_.runCount++;
808 this.log('Running test: ' + this.curTest_.name);
809 if (this.maybeFailTestEarly(this.curTest_)) {
810 return new goog.testing.Continuation_(
811 goog.bind(this.finishTestInvocation_, this));
812 }
813 goog.testing.TestCase.currentTestName = this.curTest_.name;
814 return this.safeSetUp_();
815 };
816
817 /**
818 * Runs all the setups associated with a test.
819 * @return {?goog.testing.Continuation_}
820 * @private
821 */
822 goog.testing.TestCase.prototype.safeSetUp_ = function() {
823 var setUps =
824 this.curTest_.setUps.length ? this.curTest_.setUps.slice() : [this.setUp];
825 return this.safeSetUpHelper_(setUps).call(this);
826 };
827
828 /**
829 * Recursively invokes setUp functions.
830 * @param {!Array<function()>} setUps
831 * @return {function(): ?goog.testing.Continuation_}
832 * @private
833 */
834 goog.testing.TestCase.prototype.safeSetUpHelper_ = function(setUps) {
835 if (!setUps.length) {
836 return this.safeRunTest_;
837 }
838 return goog.bind(
839 this.invokeFunction_, this, setUps.shift(), this.safeSetUpHelper_(setUps),
840 this.safeTearDown_, 'setUp');
841 };
842
843 /**
844 * Calls the given test function, handling errors appropriately.
845 * @return {?goog.testing.Continuation_}
846 * @private
847 */
848 goog.testing.TestCase.prototype.safeRunTest_ = function() {
849 return this.invokeFunction_(
850 goog.bind(this.curTest_.ref, this.curTest_.scope), this.safeTearDown_,
851 this.safeTearDown_, this.curTest_.name);
852 };
853
854
855 /**
856 * Calls {@link tearDown}, handling errors appropriately.
857 * @param {*=} opt_error Error associated with the test, if any.
858 * @return {?goog.testing.Continuation_}
859 * @private
860 */
861 goog.testing.TestCase.prototype.safeTearDown_ = function(opt_error) {
862 if (arguments.length == 1) {
863 this.doError(this.curTest_, opt_error);
864 }
865 var tearDowns = this.curTest_.tearDowns.length ?
866 this.curTest_.tearDowns.slice() :
867 [this.tearDown];
868 return this.safeTearDownHelper_(tearDowns).call(this);
869 };
870
871 /**
872 * Recursively invokes tearDown functions.
873 * @param {!Array<function()>} tearDowns
874 * @return {function(): ?goog.testing.Continuation_}
875 * @private
876 */
877 goog.testing.TestCase.prototype.safeTearDownHelper_ = function(tearDowns) {
878 if (!tearDowns.length) {
879 return this.finishTestInvocation_;
880 }
881 return goog.bind(
882 this.invokeFunction_, this, tearDowns.shift(),
883 this.safeTearDownHelper_(tearDowns), this.finishTestInvocation_,
884 'tearDown');
885 };
886
887
888 /**
889 * Calls the given {@code fn}, then calls either {@code onSuccess} or
890 * {@code onFailure}, either synchronously or using promises, depending on
891 * {@code fn}'s return value.
892 *
893 * If {@code fn} throws an exception, {@code onFailure} is called immediately
894 * with the exception.
895 *
896 * If {@code fn} returns a promise, and the promise is eventually resolved,
897 * {@code onSuccess} is called with no arguments. If the promise is eventually
898 * rejected, {@code onFailure} is called with the rejection reason.
899 *
900 * Otherwise, if {@code fn} neither returns a promise nor throws an exception,
901 * {@code onSuccess} is called immediately with no arguments.
902 *
903 * {@code fn}, {@code onSuccess}, and {@code onFailure} are all called with
904 * the TestCase instance as the method receiver.
905 *
906 * @param {function()} fn The function to call.
907 * @param {function(): (?goog.testing.Continuation_|undefined)} onSuccess
908 * @param {function(*): (?goog.testing.Continuation_|undefined)} onFailure
909 * @param {string} fnName Name of the function being invoked e.g. 'setUp'.
910 * @return {?goog.testing.Continuation_}
911 * @private
912 */
913 goog.testing.TestCase.prototype.invokeFunction_ = function(
914 fn, onSuccess, onFailure, fnName) {
915 var testCase = this;
916 this.thrownAssertionExceptions_ = [];
917 try {
918 var retval = fn.call(this);
919 if (goog.Thenable.isImplementedBy(retval) ||
920 goog.isFunction(retval && retval['then'])) {
921 // Resolve Thenable into a proper Promise to avoid hard to debug
922 // problems.
923 var promise = goog.Promise.resolve(retval);
924 var self = this;
925 promise = this.rejectIfPromiseTimesOut_(
926 promise, self.promiseTimeout,
927 'Timed out while waiting for a promise returned from ' + fnName +
928 ' to resolve. Set goog.testing.TestCase.getActiveTestCase()' +
929 '.promiseTimeout to adjust the timeout.');
930 promise.then(
931 function() {
932 self.resetBatchTimeAfterPromise_();
933 if (testCase.thrownAssertionExceptions_.length == 0) {
934 goog.testing.Continuation_.run(onSuccess.call(self));
935 } else {
936 goog.testing.Continuation_.run(onFailure.call(
937 self,
938 testCase.reportUnpropagatedAssertionExceptions_(fnName)));
939 }
940 },
941 function(e) {
942 self.resetBatchTimeAfterPromise_();
943 goog.testing.Continuation_.run(onFailure.call(self, e));
944 });
945 return null;
946 } else {
947 if (this.thrownAssertionExceptions_.length == 0) {
948 return new goog.testing.Continuation_(goog.bind(onSuccess, this));
949 } else {
950 return new goog.testing.Continuation_(goog.bind(
951 onFailure, this,
952 this.reportUnpropagatedAssertionExceptions_(fnName)));
953 }
954 }
955 } catch (e) {
956 return new goog.testing.Continuation_(goog.bind(onFailure, this, e));
957 }
958 };
959
960
961 /**
962 * Logs all of the exceptions generated from failing assertions, and returns a
963 * generic exception informing the user that one or more exceptions were not
964 * propagated, causing the test to erroneously pass.
965 * @param {string} testName The test function's name.
966 * @return {!goog.testing.JsUnitException}
967 * @private
968 */
969 goog.testing.TestCase.prototype.reportUnpropagatedAssertionExceptions_ =
970 function(testName) {
971 var numExceptions = this.thrownAssertionExceptions_.length;
972
973 for (var i = 0; i < numExceptions; i++) {
974 this.recordError_(testName, this.thrownAssertionExceptions_[i]);
975 }
976
977 return new goog.testing.JsUnitException(
978 'One or more assertions were raised but not caught by the testing ' +
979 'framework. These assertions may have been unintentionally captured ' +
980 'by a catch block or a thenCatch resolution of a Promise.');
981 };
982
983
984 /**
985 * Resets the batch run timer. This should only be called after resolving a
986 * promise since Promise.then() has an implicit yield.
987 * @private
988 */
989 goog.testing.TestCase.prototype.resetBatchTimeAfterPromise_ = function() {
990 this.batchTime_ = this.now();
991 };
992
993
994 /**
995 * Finishes up bookkeeping for the current test function, and schedules
996 * the next test function to run, either immediately or asychronously.
997 * @param {*=} opt_error Optional error resulting from the test invocation.
998 * @return {?goog.testing.Continuation_}
999 * @private
1000 */
1001 goog.testing.TestCase.prototype.finishTestInvocation_ = function(opt_error) {
1002 if (arguments.length == 1) {
1003 this.doError(this.curTest_, opt_error);
1004 }
1005
1006 // If no errors have been recorded for the test, it is a success.
1007 if (!(this.curTest_.name in this.result_.resultsByName) ||
1008 !this.result_.resultsByName[this.curTest_.name].length) {
1009 this.doSuccess(this.curTest_);
1010 }
1011
1012 goog.testing.TestCase.currentTestName = null;
1013
1014 // If the test case has consumed too much time or stack space,
1015 // yield to avoid blocking the browser. Otherwise, proceed to the next test.
1016 if (this.now() - this.batchTime_ > goog.testing.TestCase.maxRunTime) {
1017 this.saveMessage('Breaking async');
1018 this.timeout(goog.bind(this.startNextBatch_, this), 0);
1019 return null;
1020 } else {
1021 return new goog.testing.Continuation_(goog.bind(this.runNextTest_, this));
1022 }
1023 };
1024
1025
1026 /**
1027 * Start a new batch to tests after yielding, resetting batchTime and depth.
1028 * @private
1029 */
1030 goog.testing.TestCase.prototype.startNextBatch_ = function() {
1031 this.batchTime_ = this.now();
1032 goog.testing.Continuation_.run(this.runNextTest_());
1033 };
1034
1035
1036 /**
1037 * Reorders the tests depending on the {@code order} field.
1038 * @private
1039 */
1040 goog.testing.TestCase.prototype.orderTests_ = function() {
1041 switch (this.order) {
1042 case goog.testing.TestCase.Order.RANDOM:
1043 // Fisher-Yates shuffle
1044 var i = this.tests_.length;
1045 while (i > 1) {
1046 // goog.math.randomInt is inlined to reduce dependencies.
1047 var j = Math.floor(Math.random() * i); // exclusive
1048 i--;
1049 var tmp = this.tests_[i];
1050 this.tests_[i] = this.tests_[j];
1051 this.tests_[j] = tmp;
1052 }
1053 break;
1054
1055 case goog.testing.TestCase.Order.SORTED:
1056 this.tests_.sort(function(t1, t2) {
1057 if (t1.name == t2.name) {
1058 return 0;
1059 }
1060 return t1.name < t2.name ? -1 : 1;
1061 });
1062 break;
1063
1064 // Do nothing for NATURAL.
1065 }
1066 };
1067
1068
1069 /**
1070 * Gets list of objects that potentially contain test cases. For IE 8 and
1071 * below, this is the global "this" (for properties set directly on the global
1072 * this or window) and the RuntimeObject (for global variables and functions).
1073 * For all other browsers, the array simply contains the global this.
1074 *
1075 * @param {string=} opt_prefix An optional prefix. If specified, only get things
1076 * under this prefix. Note that the prefix is only honored in IE, since it
1077 * supports the RuntimeObject:
1078 * http://msdn.microsoft.com/en-us/library/ff521039%28VS.85%29.aspx
1079 * TODO: Remove this option.
1080 * @return {!Array<!Object>} A list of objects that should be inspected.
1081 */
1082 goog.testing.TestCase.prototype.getGlobals = function(opt_prefix) {
1083 return goog.testing.TestCase.getGlobals(opt_prefix);
1084 };
1085
1086
1087 /**
1088 * Gets list of objects that potentially contain test cases. For IE 8 and
1089 * below, this is the global "this" (for properties set directly on the global
1090 * this or window) and the RuntimeObject (for global variables and functions).
1091 * For all other browsers, the array simply contains the global this.
1092 *
1093 * @param {string=} opt_prefix An optional prefix. If specified, only get things
1094 * under this prefix. Note that the prefix is only honored in IE, since it
1095 * supports the RuntimeObject:
1096 * http://msdn.microsoft.com/en-us/library/ff521039%28VS.85%29.aspx
1097 * TODO: Remove this option.
1098 * @return {!Array<!Object>} A list of objects that should be inspected.
1099 */
1100 goog.testing.TestCase.getGlobals = function(opt_prefix) {
1101 // Look in the global scope for most browsers, on IE we use the little known
1102 // RuntimeObject which holds references to all globals. We reference this
1103 // via goog.global so that there isn't an aliasing that throws an exception
1104 // in Firefox.
1105 return typeof goog.global['RuntimeObject'] != 'undefined' ?
1106 [goog.global['RuntimeObject']((opt_prefix || '') + '*'), goog.global] :
1107 [goog.global];
1108 };
1109
1110
1111 /**
1112 * @private {?goog.testing.TestCase}
1113 */
1114 goog.testing.TestCase.activeTestCase_ = null;
1115
1116
1117 /**
1118 * @return {?goog.testing.TestCase} currently active test case or null if not
1119 * test is currently running. Tries the G_testRunner first then the stored
1120 * value (when run outside of G_testRunner.
1121 */
1122 goog.testing.TestCase.getActiveTestCase = function() {
1123 var gTestRunner = goog.global['G_testRunner'];
1124 if (gTestRunner && gTestRunner.testCase) {
1125 return gTestRunner.testCase;
1126 } else {
1127 return goog.testing.TestCase.activeTestCase_;
1128 }
1129 };
1130
1131
1132 /**
1133 * Calls {@link goog.testing.TestCase.prototype.invalidateAssertionException}
1134 * on the active test case if it is installed, and logs an error otherwise.
1135 * @param {!goog.testing.JsUnitException} e The exception object to invalidate.
1136 * @package
1137 */
1138 goog.testing.TestCase.invalidateAssertionException = function(e) {
1139 var testCase = goog.testing.TestCase.getActiveTestCase();
1140 if (testCase) {
1141 testCase.invalidateAssertionException(e);
1142 } else {
1143 goog.global.console.error(
1144 'Failed to remove expected exception: no test case is installed.');
1145 }
1146 };
1147
1148
1149 /**
1150 * Gets called before any tests are executed. Can be overridden to set up the
1151 * environment for the whole test case.
1152 * @return {!Thenable|undefined}
1153 */
1154 goog.testing.TestCase.prototype.setUpPage = function() {};
1155
1156
1157 /**
1158 * Gets called after all tests have been executed. Can be overridden to tear
1159 * down the entire test case.
1160 */
1161 goog.testing.TestCase.prototype.tearDownPage = function() {};
1162
1163
1164 /**
1165 * Gets called before every goog.testing.TestCase.Test is been executed. Can
1166 * be overridden to add set up functionality to each test.
1167 * @return {!Thenable|undefined}
1168 */
1169 goog.testing.TestCase.prototype.setUp = function() {};
1170
1171
1172 /**
1173 * Gets called after every goog.testing.TestCase.Test has been executed. Can
1174 * be overridden to add tear down functionality to each test.
1175 * @return {!Thenable|undefined}
1176 */
1177 goog.testing.TestCase.prototype.tearDown = function() {};
1178
1179
1180 /**
1181 * @return {string} The function name prefix used to auto-discover tests.
1182 */
1183 goog.testing.TestCase.prototype.getAutoDiscoveryPrefix = function() {
1184 return 'test';
1185 };
1186
1187
1188 /**
1189 * @return {number} Time since the last batch of tests was started.
1190 * @protected
1191 */
1192 goog.testing.TestCase.prototype.getBatchTime = function() {
1193 return this.batchTime_;
1194 };
1195
1196
1197 /**
1198 * @param {number} batchTime Time since the last batch of tests was started.
1199 * @protected
1200 */
1201 goog.testing.TestCase.prototype.setBatchTime = function(batchTime) {
1202 this.batchTime_ = batchTime;
1203 };
1204
1205
1206 /**
1207 * Creates a {@code goog.testing.TestCase.Test} from an auto-discovered
1208 * function.
1209 * @param {string} name The name of the function.
1210 * @param {function()} ref The auto-discovered function.
1211 * @param {!Object=} scope The scope to attach to the test.
1212 * @param {!Array<!Object>=} objChain
1213 * @return {!goog.testing.TestCase.Test} The newly created test.
1214 * @protected
1215 */
1216 goog.testing.TestCase.prototype.createTest = function(
1217 name, ref, scope, objChain) {
1218 return new goog.testing.TestCase.Test(name, ref, scope, objChain);
1219 };
1220
1221
1222 /**
1223 * Adds any functions defined on 'obj' (the global object, by default)
1224 * that correspond to lifecycle events for the test case. Overrides
1225 * setUp, tearDown, setUpPage, tearDownPage, runTests, and shouldRunTests
1226 * if they are defined on 'obj'.
1227 * @param {!Object=} opt_obj Defaults to goog.global.
1228 */
1229 goog.testing.TestCase.prototype.autoDiscoverLifecycle = function(opt_obj) {
1230 var obj = opt_obj || goog.global;
1231 if (obj['setUp']) {
1232 this.setUp = goog.bind(obj['setUp'], obj);
1233 }
1234 if (obj['tearDown']) {
1235 this.tearDown = goog.bind(obj['tearDown'], obj);
1236 }
1237 if (obj['setUpPage']) {
1238 this.setUpPage = goog.bind(obj['setUpPage'], obj);
1239 }
1240 if (obj['tearDownPage']) {
1241 this.tearDownPage = goog.bind(obj['tearDownPage'], obj);
1242 }
1243 if (obj['runTests']) {
1244 this.runTests = goog.bind(obj['runTests'], obj);
1245 }
1246 if (obj['shouldRunTests']) {
1247 this.shouldRunTests = goog.bind(obj['shouldRunTests'], obj);
1248 }
1249 };
1250
1251
1252 // TODO(johnlenz): make this package private
1253 /**
1254 * @param {!Object} obj An object from which to extract test and lifecycle
1255 * methods.
1256 */
1257 goog.testing.TestCase.prototype.setTestObj = function(obj) {
1258 // Drop any previously added (likely auto-discovered) tests, only one source
1259 // of discovered test and life-cycle methods is allowed.
1260 goog.asserts.assert(
1261 this.tests_.length == 0, 'Test methods have already been configured.');
1262 if (obj['getTestName']) {
1263 this.name_ = obj['getTestName']();
1264 }
1265
1266 this.autoDiscoverLifecycle(obj);
1267 this.addTestObj_(obj, '', [this]);
1268 };
1269
1270 /**
1271 * @param {!Object} obj An object from which to extract test and lifecycle
1272 * methods.
1273 * @param {string} name
1274 * @param {!Array<!Object>} objChain List of objects that have methods used
1275 * to create tests such as setUp, tearDown.
1276 * @private
1277 */
1278 goog.testing.TestCase.prototype.addTestObj_ = function(obj, name, objChain) {
1279 var regex = new RegExp('^' + this.getAutoDiscoveryPrefix());
1280 var properties = goog.object.getAllPropertyNames(obj);
1281 for (var i = 0; i < properties.length; i++) {
1282 var testName = properties[i];
1283 if (regex.test(testName)) {
1284 var testProperty;
1285 try {
1286 testProperty = obj[testName];
1287 } catch (ex) {
1288 // NOTE(brenneman): When running tests from a file:// URL on Firefox
1289 // 3.5 for Windows, any reference to goog.global.sessionStorage raises
1290 // an "Operation is not supported" exception. Ignore any exceptions
1291 // raised by simply accessing global properties.
1292 testProperty = null;
1293 }
1294 if (name) {
1295 testName = testName.slice(this.getAutoDiscoveryPrefix().length);
1296 }
1297 var fullTestName = name + (testName && name ? '_' : '') + testName;
1298 if (goog.isFunction(testProperty)) {
1299 this.addNewTest(fullTestName, testProperty, obj, objChain);
1300 } else if (goog.isObject(testProperty)) {
1301 // To prevent infinite loops.
1302 if (!goog.array.contains(objChain, testProperty)) {
1303 var newObjChain = objChain.slice();
1304 newObjChain.push(testProperty);
1305 this.addTestObj_(testProperty, fullTestName, newObjChain);
1306 }
1307 }
1308 }
1309 }
1310 };
1311
1312
1313 /**
1314 * Adds any functions defined in the global scope that are prefixed with
1315 * "test" to the test case.
1316 */
1317 goog.testing.TestCase.prototype.autoDiscoverTests = function() {
1318 this.autoDiscoverLifecycle();
1319 var prefix = this.getAutoDiscoveryPrefix();
1320 var testSources = this.getGlobals(prefix);
1321
1322 for (var i = 0; i < testSources.length; i++) {
1323 var testSource = testSources[i];
1324 this.addTestObj_(testSource, '', [this]);
1325 }
1326
1327 this.orderTests_();
1328 this.log(this.getCount() + ' tests auto-discovered');
1329 };
1330
1331
1332 /**
1333 * Checks to see if the test should be marked as failed before it is run.
1334 *
1335 * If there was an error in setUpPage, we treat that as a failure for all
1336 * tests and mark them all as having failed.
1337 *
1338 * @param {goog.testing.TestCase.Test} testCase The current test case.
1339 * @return {boolean} Whether the test was marked as failed.
1340 * @protected
1341 */
1342 goog.testing.TestCase.prototype.maybeFailTestEarly = function(testCase) {
1343 if (this.exceptionBeforeTest) {
1344 // We just use the first error to report an error on a failed test.
1345 testCase.name = 'setUpPage for ' + testCase.name;
1346 this.doError(testCase, this.exceptionBeforeTest);
1347 return true;
1348 }
1349 return false;
1350 };
1351
1352
1353 /**
1354 * Cycles through the tests, yielding asynchronously if the execution time
1355 * exceeds {@link #maxRunTime}. In particular, there is no guarantee that
1356 * the test case has finished execution once this method has returned.
1357 * To be notified when the test case has finished execution, use
1358 * {@link #setCompletedCallback} or {@link #runTestsReturningPromise}.
1359 */
1360 goog.testing.TestCase.prototype.cycleTests = function() {
1361 this.saveMessage('Start');
1362 this.batchTime_ = this.now();
1363 if (this.running) {
1364 this.runNextTestCallback_ = goog.nullFunction;
1365 // Kick off the tests. runNextTest_ will schedule all of the tests,
1366 // using a mixture of synchronous and asynchronous strategies.
1367 goog.testing.Continuation_.run(this.runNextTest_());
1368 }
1369 };
1370
1371
1372 /**
1373 * Counts the number of files that were loaded for dependencies that are
1374 * required to run the test.
1375 * @return {number} The number of files loaded.
1376 * @private
1377 */
1378 goog.testing.TestCase.prototype.countNumFilesLoaded_ = function() {
1379 var scripts = goog.dom.getElementsByTagName(goog.dom.TagName.SCRIPT);
1380 var count = 0;
1381 for (var i = 0, n = scripts.length; i < n; i++) {
1382 if (scripts[i].src) {
1383 count++;
1384 }
1385 }
1386 return count;
1387 };
1388
1389
1390 /**
1391 * Calls a function after a delay, using the protected timeout.
1392 * @param {Function} fn The function to call.
1393 * @param {number} time Delay in milliseconds.
1394 * @return {number} The timeout id.
1395 * @protected
1396 */
1397 goog.testing.TestCase.prototype.timeout = function(fn, time) {
1398 // NOTE: invoking protectedSetTimeout_ as a member of goog.testing.TestCase
1399 // would result in an Illegal Invocation error. The method must be executed
1400 // with the global context.
1401 var protectedSetTimeout = goog.testing.TestCase.protectedSetTimeout_;
1402 return protectedSetTimeout(fn, time);
1403 };
1404
1405
1406 /**
1407 * Clears a timeout created by {@code this.timeout()}.
1408 * @param {number} id A timeout id.
1409 * @protected
1410 */
1411 goog.testing.TestCase.prototype.clearTimeout = function(id) {
1412 // NOTE: see execution note for protectedSetTimeout above.
1413 var protectedClearTimeout = goog.testing.TestCase.protectedClearTimeout_;
1414 protectedClearTimeout(id);
1415 };
1416
1417
1418 /**
1419 * @return {number} The current time in milliseconds.
1420 * @protected
1421 */
1422 goog.testing.TestCase.prototype.now = function() {
1423 return goog.testing.TestCase.now();
1424 };
1425
1426
1427 /**
1428 * @return {number} The current time in milliseconds.
1429 * @protected
1430 */
1431 goog.testing.TestCase.now = function() {
1432 // don't use goog.now as some tests override it.
1433 if (goog.testing.TestCase.protectedPerformance_) {
1434 return goog.testing.TestCase.protectedPerformance_.now();
1435 }
1436 // Fallback for IE8
1437 // Cannot use "new goog.testing.TestCase.protectedDate_()" due to b/8323223.
1438 var protectedDate = goog.testing.TestCase.protectedDate_;
1439 return new protectedDate().getTime();
1440 };
1441
1442
1443 /**
1444 * Returns the current time.
1445 * @return {string} HH:MM:SS.
1446 * @private
1447 */
1448 goog.testing.TestCase.prototype.getTimeStamp_ = function() {
1449 // Cannot use "new goog.testing.TestCase.protectedDate_()" due to b/8323223.
1450 var protectedDate = goog.testing.TestCase.protectedDate_;
1451 var d = new protectedDate();
1452
1453 // Ensure millis are always 3-digits
1454 var millis = '00' + d.getMilliseconds();
1455 millis = millis.substr(millis.length - 3);
1456
1457 return this.pad_(d.getHours()) + ':' + this.pad_(d.getMinutes()) + ':' +
1458 this.pad_(d.getSeconds()) + '.' + millis;
1459 };
1460
1461
1462 /**
1463 * Pads a number to make it have a leading zero if it's less than 10.
1464 * @param {number} number The number to pad.
1465 * @return {string} The resulting string.
1466 * @private
1467 */
1468 goog.testing.TestCase.prototype.pad_ = function(number) {
1469 return number < 10 ? '0' + number : String(number);
1470 };
1471
1472
1473 /**
1474 * Trims a path to be only that after google3.
1475 * @param {string} path The path to trim.
1476 * @return {string} The resulting string.
1477 * @private
1478 */
1479 goog.testing.TestCase.prototype.trimPath_ = function(path) {
1480 return path.substring(path.indexOf('google3') + 8);
1481 };
1482
1483
1484 /**
1485 * Handles a test that passed.
1486 * @param {goog.testing.TestCase.Test} test The test that passed.
1487 * @protected
1488 */
1489 goog.testing.TestCase.prototype.doSuccess = function(test) {
1490 this.result_.successCount++;
1491 // An empty list of error messages indicates that the test passed.
1492 // If we already have a failure for this test, do not set to empty list.
1493 if (!(test.name in this.result_.resultsByName)) {
1494 this.result_.resultsByName[test.name] = [];
1495 }
1496 var message = test.name + ' : PASSED';
1497 this.saveMessage(message);
1498 this.log(message);
1499 if (this.testDone_) {
1500 this.doTestDone_(test, []);
1501 }
1502 };
1503
1504
1505 /**
1506 * Records and logs a test failure.
1507 * @param {string} testName The name of the test that failed.
1508 * @param {*=} opt_e The exception object associated with the
1509 * failure or a string.
1510 * @private
1511 */
1512 goog.testing.TestCase.prototype.recordError_ = function(testName, opt_e) {
1513 var message = testName + ' : FAILED';
1514 this.log(message);
1515 this.saveMessage(message);
1516 var err = this.logError(testName, opt_e);
1517 this.result_.errors.push(err);
1518 if (testName in this.result_.resultsByName) {
1519 this.result_.resultsByName[testName].push(err);
1520 } else {
1521 this.result_.resultsByName[testName] = [err];
1522 }
1523 };
1524
1525
1526 /**
1527 * Handles a test that failed.
1528 * @param {goog.testing.TestCase.Test} test The test that failed.
1529 * @param {*=} opt_e The exception object associated with the
1530 * failure or a string.
1531 * @protected
1532 */
1533 goog.testing.TestCase.prototype.doError = function(test, opt_e) {
1534 if (!test || !test.name) {
1535 console.error('no name!' + opt_e);
1536 }
1537 this.recordError_(test.name, opt_e);
1538 if (this.testDone_) {
1539 var results = this.result_.resultsByName[test.name];
1540 var errMsgs = [];
1541 for (var i = 0; i < results.length; i++) {
1542 errMsgs.push(results[i].toString());
1543 }
1544 this.doTestDone_(test, errMsgs);
1545 }
1546 };
1547
1548
1549 /**
1550 * Makes note of an exception arising from an assertion, and then throws it.
1551 * If the test otherwise passes (i.e., because something else caught the
1552 * exception on its way to the test framework), it will be forced to fail.
1553 * @param {!goog.testing.JsUnitException} e The exception object being thrown.
1554 * @throws {goog.testing.JsUnitException}
1555 * @package
1556 */
1557 goog.testing.TestCase.prototype.raiseAssertionException = function(e) {
1558 if (this.failOnUnreportedAsserts) {
1559 this.thrownAssertionExceptions_.push(e);
1560 }
1561 throw e;
1562 };
1563
1564
1565 /**
1566 * Removes the specified exception from being tracked. This only needs to be
1567 * called for internal functions that intentionally catch an exception, such
1568 * as
1569 * {@code #assertThrowsJsUnitException}.
1570 * @param {!goog.testing.JsUnitException} e The exception object to invalidate.
1571 * @package
1572 */
1573 goog.testing.TestCase.prototype.invalidateAssertionException = function(e) {
1574 if (this.failOnUnreportedAsserts) {
1575 goog.array.remove(this.thrownAssertionExceptions_, e);
1576 }
1577 };
1578
1579
1580 /**
1581 * @param {string} name Failed test name.
1582 * @param {*=} opt_e The exception object associated with the
1583 * failure or a string.
1584 * @return {!goog.testing.TestCase.Error} Error object.
1585 */
1586 goog.testing.TestCase.prototype.logError = function(name, opt_e) {
1587 var errMsg = null;
1588 var stack = null;
1589 if (opt_e) {
1590 this.log(opt_e);
1591 if (goog.isString(opt_e)) {
1592 errMsg = opt_e;
1593 } else {
1594 errMsg = opt_e.message || opt_e.description || opt_e.toString();
1595 stack = opt_e.stack ? opt_e.stack : opt_e['stackTrace'];
1596 }
1597 } else {
1598 errMsg = 'An unknown error occurred';
1599 }
1600 if (stack) {
1601 // Remove extra goog.testing.TestCase frames from the end.
1602 stack = stack.replace(
1603 /\n.*goog\.testing\.TestCase\.(prototype\.)?invokeTestFunction[^\0]*/m,
1604 '');
1605 }
1606 var err = new goog.testing.TestCase.Error(name, errMsg, stack);
1607
1608 // Avoid double logging.
1609 if (!opt_e || !opt_e['isJsUnitException'] ||
1610 !opt_e['loggedJsUnitException']) {
1611 this.saveMessage(err.toString());
1612 }
1613 if (opt_e && opt_e['isJsUnitException']) {
1614 opt_e['loggedJsUnitException'] = true;
1615 }
1616
1617 return err;
1618 };
1619
1620 /**
1621 * A class representing a single test function.
1622 * @param {string} name The test name.
1623 * @param {?function()} ref Reference to the test function or test object.
1624 * @param {?Object=} scope Optional scope that the test function should be
1625 * called in.
1626 * @param {!Array<!Object>=} objChain A chain of objects used to populate setUps
1627 * and tearDowns.
1628 * @constructor
1629 */
1630 goog.testing.TestCase.Test = function(name, ref, scope, objChain) {
1631 /**
1632 * The name of the test.
1633 * @type {string}
1634 */
1635 this.name = name;
1636
1637 /**
1638 * TODO(user): Rename this to something more clear.
1639 * Reference to the test function.
1640 * @type {function()}
1641 */
1642 this.ref = ref || function() {};
1643
1644 /**
1645 * Scope that the test function should be called in.
1646 * @type {?Object}
1647 */
1648 this.scope = scope || null;
1649
1650 /**
1651 * @type {!Array<function()>}
1652 */
1653 this.setUps = [];
1654
1655 /**
1656 * @type {!Array<function()>}
1657 */
1658 this.tearDowns = [];
1659
1660 if (objChain) {
1661 for (var i = 0; i < objChain.length; i++) {
1662 if (goog.isFunction(objChain[i].setUp)) {
1663 this.setUps.push(goog.bind(objChain[i].setUp, objChain[i]));
1664 }
1665 if (goog.isFunction(objChain[i].tearDown)) {
1666 this.tearDowns.push(goog.bind(objChain[i].tearDown, objChain[i]));
1667 }
1668 }
1669 this.tearDowns.reverse();
1670 }
1671
1672 /**
1673 * Timestamp just before the test begins execution.
1674 * @type {number}
1675 * @private
1676 */
1677 this.startTime_;
1678
1679 /**
1680 * Timestamp just after the test ends execution.
1681 * @type {number}
1682 * @private
1683 */
1684 this.stoppedTime_;
1685 };
1686
1687 /**
1688 * Executes the test function.
1689 * @package
1690 */
1691 goog.testing.TestCase.Test.prototype.execute = function() {
1692 this.ref.call(this.scope);
1693 };
1694
1695 /**
1696 * Sets the start time
1697 */
1698 goog.testing.TestCase.Test.prototype.started = function() {
1699 this.startTime_ = goog.testing.TestCase.now();
1700 };
1701
1702 /**
1703 * Sets the stop time
1704 */
1705 goog.testing.TestCase.Test.prototype.stopped = function() {
1706 this.stoppedTime_ = goog.testing.TestCase.now();
1707 };
1708
1709 /**
1710 * Returns the runtime for this test function
1711 * @return {number} milliseconds takenn by the test.
1712 */
1713 goog.testing.TestCase.Test.prototype.getElapsedTime = function() {
1714 return this.stoppedTime_ - this.startTime_;
1715 };
1716
1717 /**
1718 * A class for representing test results. A bag of public properties.
1719 * @param {goog.testing.TestCase} testCase The test case that owns this result.
1720 * @constructor
1721 * @final
1722 */
1723 goog.testing.TestCase.Result = function(testCase) {
1724 /**
1725 * The test case that owns this result.
1726 * @type {goog.testing.TestCase}
1727 * @private
1728 */
1729 this.testCase_ = testCase;
1730
1731 /**
1732 * Total number of tests that should have been run.
1733 * @type {number}
1734 */
1735 this.totalCount = 0;
1736
1737 /**
1738 * Total number of tests that were actually run.
1739 * @type {number}
1740 */
1741 this.runCount = 0;
1742
1743 /**
1744 * Number of successful tests.
1745 * @type {number}
1746 */
1747 this.successCount = 0;
1748
1749 /**
1750 * The amount of time the tests took to run.
1751 * @type {number}
1752 */
1753 this.runTime = 0;
1754
1755 /**
1756 * The number of files loaded to run this test.
1757 * @type {number}
1758 */
1759 this.numFilesLoaded = 0;
1760
1761 /**
1762 * Whether this test case was suppressed by shouldRunTests() returning
1763 * false.
1764 * @type {boolean}
1765 */
1766 this.testSuppressed = false;
1767
1768 /**
1769 * Test results for each test that was run. The test name is always added
1770 * as the key in the map, and the array of strings is an optional list
1771 * of failure messages. If the array is empty, the test passed. Otherwise,
1772 * the test failed.
1773 * @type {!Object<string, !Array<goog.testing.TestCase.Error>>}
1774 */
1775 this.resultsByName = {};
1776
1777 /**
1778 * Errors encountered while running the test.
1779 * @type {!Array<goog.testing.TestCase.Error>}
1780 */
1781 this.errors = [];
1782
1783 /**
1784 * Messages to show the user after running the test.
1785 * @type {!Array<string>}
1786 */
1787 this.messages = [];
1788
1789 /**
1790 * Whether the tests have completed.
1791 * @type {boolean}
1792 */
1793 this.complete = false;
1794 };
1795
1796
1797 /**
1798 * @return {boolean} Whether the test was successful.
1799 */
1800 goog.testing.TestCase.Result.prototype.isSuccess = function() {
1801 return this.complete && this.errors.length == 0;
1802 };
1803
1804
1805 /**
1806 * @return {string} A summary of the tests, including total number of tests that
1807 * passed, failed, and the time taken.
1808 */
1809 goog.testing.TestCase.Result.prototype.getSummary = function() {
1810 var summary = this.runCount + ' of ' + this.totalCount + ' tests run in ' +
1811 this.runTime + 'ms.\n';
1812 if (this.testSuppressed) {
1813 summary += 'Tests not run because shouldRunTests() returned false.';
1814 } else {
1815 var failures = this.totalCount - this.successCount;
1816 var suppressionMessage = '';
1817
1818 var countOfRunTests = this.testCase_.getActuallyRunCount();
1819 if (countOfRunTests) {
1820 failures = countOfRunTests - this.successCount;
1821 suppressionMessage = ', ' + (this.totalCount - countOfRunTests) +
1822 ' suppressed by querystring';
1823 }
1824 summary += this.successCount + ' passed, ' + failures + ' failed' +
1825 suppressionMessage + '.\n' + Math.round(this.runTime / this.runCount) +
1826 ' ms/test. ' + this.numFilesLoaded + ' files loaded.';
1827 }
1828
1829 return summary;
1830 };
1831
1832
1833 /**
1834 * @param {function(goog.testing.TestCase.Test, !Array<string>)} testDone
1835 */
1836 goog.testing.TestCase.prototype.setTestDoneCallback = function(testDone) {
1837 this.testDone_ = testDone;
1838 };
1839
1840
1841 /**
1842 * @param {goog.testing.TestCase.Test} test
1843 * @param {!Array<string>} errMsgs
1844 * @private
1845 */
1846 goog.testing.TestCase.prototype.doTestDone_ = function(test, errMsgs) {
1847 test.stopped();
1848 this.testDone_(test, errMsgs);
1849 };
1850
1851
1852 /**
1853 * Initializes the TestCase.
1854 * @param {goog.testing.TestCase} testCase The test case to install.
1855 * @param {function(goog.testing.TestCase.Test, Array<string>)=} opt_testDone
1856 * Called when each test completes.
1857 */
1858 goog.testing.TestCase.initializeTestCase = function(testCase, opt_testDone) {
1859 if (opt_testDone) {
1860 testCase.setTestDoneCallback(opt_testDone);
1861 }
1862
1863 testCase.autoDiscoverTests();
1864
1865 if (goog.global.location) {
1866 var search = goog.global.location.search;
1867 testCase.setOrder(
1868 goog.testing.TestCase.parseOrder_(search) ||
1869 goog.testing.TestCase.Order.SORTED);
1870 testCase.setTestsToRun(goog.testing.TestCase.parseRunTests_(search));
1871 }
1872 goog.testing.TestCase.activeTestCase_ = testCase;
1873 };
1874
1875
1876 /**
1877 * Initializes the given test case with the global test runner 'G_testRunner'.
1878 * @param {goog.testing.TestCase} testCase The test case to install.
1879 * @param {function(goog.testing.TestCase.Test, Array<string>)=} opt_testDone
1880 * Called when each test completes.
1881 */
1882 goog.testing.TestCase.initializeTestRunner = function(testCase, opt_testDone) {
1883 goog.testing.TestCase.initializeTestCase(testCase, opt_testDone);
1884
1885 var gTestRunner = goog.global['G_testRunner'];
1886 if (gTestRunner) {
1887 gTestRunner['initialize'](testCase);
1888 } else {
1889 throw new Error(
1890 'G_testRunner is undefined. Please ensure goog.testing.jsunit' +
1891 ' is included.');
1892 }
1893 };
1894
1895
1896 /**
1897 * Parses URL query parameters for the 'order' parameter.
1898 * @param {string} search The URL query string.
1899 * @return {?goog.testing.TestCase.Order} The sort order for running tests.
1900 * @private
1901 */
1902 goog.testing.TestCase.parseOrder_ = function(search) {
1903 var order = null;
1904 var orderMatch = search.match(/(?:\?|&)order=(natural|random|sorted)/i);
1905 if (orderMatch) {
1906 order = /** @type {goog.testing.TestCase.Order} */ (
1907 orderMatch[1].toLowerCase());
1908 }
1909 return order;
1910 };
1911
1912
1913 /**
1914 * Parses URL query parameters for the 'runTests' parameter.
1915 * @param {string} search The URL query string.
1916 * @return {Object<string, boolean>} A set of test names or test indices to be
1917 * run by the test runner.
1918 * @private
1919 */
1920 goog.testing.TestCase.parseRunTests_ = function(search) {
1921 var testsToRun = null;
1922 var runTestsMatch = search.match(/(?:\?|&)runTests=([^?&]+)/i);
1923 if (runTestsMatch) {
1924 testsToRun = {};
1925 var arr = runTestsMatch[1].split(',');
1926 for (var i = 0, len = arr.length; i < len; i++) {
1927 testsToRun[arr[i]] = true;
1928 }
1929 }
1930 return testsToRun;
1931 };
1932
1933
1934 /**
1935 * Wraps provided promise and returns a new promise which will be rejected
1936 * if the original promise does not settle within the given timeout.
1937 * @param {!goog.Promise<T>} promise
1938 * @param {number} timeoutInMs Number of milliseconds to wait for the promise to
1939 * settle before failing it with a timeout error.
1940 * @param {string} errorMsg Error message to use if the promise times out.
1941 * @return {!goog.Promise<T>} A promise that will settle with the original
1942 promise unless the timeout is exceeded.
1943 * errror.
1944 * @template T
1945 * @private
1946 */
1947 goog.testing.TestCase.prototype.rejectIfPromiseTimesOut_ = function(
1948 promise, timeoutInMs, errorMsg) {
1949 var self = this;
1950 var start = this.now();
1951 return new goog.Promise(function(resolve, reject) {
1952 var timeoutId = self.timeout(function() {
1953 var elapsed = self.now() - start;
1954 reject(new Error(errorMsg + '\nElapsed time: ' + elapsed + 'ms.'));
1955 }, timeoutInMs);
1956 promise.then(resolve, reject);
1957 var clearTimeout = goog.bind(self.clearTimeout, self, timeoutId);
1958 promise.then(clearTimeout, clearTimeout);
1959 });
1960 };
1961
1962
1963
1964 /**
1965 * A class representing an error thrown by the test
1966 * @param {string} source The name of the test which threw the error.
1967 * @param {string} message The error message.
1968 * @param {string=} opt_stack A string showing the execution stack.
1969 * @constructor
1970 * @final
1971 */
1972 goog.testing.TestCase.Error = function(source, message, opt_stack) {
1973 /**
1974 * The name of the test which threw the error.
1975 * @type {string}
1976 */
1977 this.source = source;
1978
1979 /**
1980 * Reference to the test function.
1981 * @type {string}
1982 */
1983 this.message = message;
1984
1985 /**
1986 * The stack.
1987 * @type {?string}
1988 */
1989 this.stack = null;
1990
1991 if (opt_stack) {
1992 this.stack = opt_stack;
1993 } else {
1994 // Attempt to capture a stack trace.
1995 if (Error.captureStackTrace) {
1996 // See https://code.google.com/p/v8-wiki/wiki/JavaScriptStackTraceApi
1997 Error.captureStackTrace(this, goog.testing.TestCase.Error);
1998 } else {
1999 var stack = new Error().stack;
2000 if (stack) {
2001 this.stack = stack;
2002 }
2003 }
2004 }
2005 };
2006
2007
2008 /**
2009 * Returns a string representing the error object.
2010 * @return {string} A string representation of the error.
2011 * @override
2012 */
2013 goog.testing.TestCase.Error.prototype.toString = function() {
2014 return 'ERROR in ' + this.source + '\n' + this.message +
2015 (this.stack ? '\n' + this.stack : '');
2016 };
2017
2018 /**
2019 * Returns an object representing the error suitable for JSON serialization.
2020 * @return {!goog.testing.TestCase.IResult} An object
2021 * representation of the error.
2022 * @private
2023 */
2024 goog.testing.TestCase.Error.prototype.toObject_ = function() {
2025 return {
2026 'source': this.source,
2027 'message': this.message,
2028 'stacktrace': this.stack || ''
2029 };
2030 };
2031
2032
2033
2034 /**
2035 * @constructor
2036 * @param {!function(): (?goog.testing.Continuation_|undefined)} fn
2037 * @private
2038 */
2039 goog.testing.Continuation_ = function(fn) {
2040 /** @private @const */
2041 this.fn_ = fn;
2042 };
2043
2044
2045 /** @param {?goog.testing.Continuation_|undefined} continuation */
2046 goog.testing.Continuation_.run = function(continuation) {
2047 var fn = continuation && continuation.fn_;
2048 while (fn) {
2049 continuation = fn();
2050 fn = continuation && continuation.fn_;
2051 }
2052 };