Debian Codegraph @

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

raw
1 // Copyright 2009 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 Defines test classes for tests that can wait for conditions.
17 *
18 * Normal unit tests must complete their test logic within a single function
19 * execution. This is ideal for most tests, but makes it difficult to test
20 * routines that require real time to complete. The tests and TestCase in this
21 * file allow for tests that can wait until a condition is true before
22 * continuing execution.
23 *
24 * Each test has the typical three phases of execution: setUp, the test itself,
25 * and tearDown. During each phase, the test function may add wait conditions,
26 * which result in new test steps being added for that phase. All steps in a
27 * given phase must complete before moving on to the next phase. An error in
28 * any phase will stop that test and report the error to the test runner.
29 *
30 * This class should not be used where adequate mocks exist. Time-based routines
31 * should use the MockClock, which runs much faster and provides equivalent
32 * results. Continuation tests should be used for testing code that depends on
33 * browser behaviors that are difficult to mock. For example, testing code that
34 * relies on Iframe load events, event or layout code that requires a setTimeout
35 * to become valid, and other browser-dependent native object interactions for
36 * which mocks are insufficient.
37 *
38 * Sample usage:
39 *
40 * <pre>
41 * var testCase = new goog.testing.ContinuationTestCase();
42 * testCase.autoDiscoverTests();
43 *
44 * if (typeof G_testRunner != 'undefined') {
45 * G_testRunner.initialize(testCase);
46 * }
47 *
48 * function testWaiting() {
49 * var someVar = true;
50 * waitForTimeout(function() {
51 * assertTrue(someVar)
52 * }, 500);
53 * }
54 *
55 * function testWaitForEvent() {
56 * var et = goog.events.EventTarget();
57 * waitForEvent(et, 'test', function() {
58 * // Test step runs after the event fires.
59 * })
60 * et.dispatchEvent(et, 'test');
61 * }
62 *
63 * function testWaitForCondition() {
64 * var counter = 0;
65 *
66 * waitForCondition(function() {
67 * // This function is evaluated periodically until it returns true, or it
68 * // times out.
69 * return ++counter >= 3;
70 * }, function() {
71 * // This test step is run once the condition becomes true.
72 * assertEquals(3, counter);
73 * });
74 * }
75 * </pre>
76 *
77 * @author [email protected] (Shawn Brenneman)
78 */
79
80
81 goog.setTestOnly('goog.testing.ContinuationTestCase');
82 goog.provide('goog.testing.ContinuationTestCase');
83 goog.provide('goog.testing.ContinuationTestCase.ContinuationTest');
84 goog.provide('goog.testing.ContinuationTestCase.Step');
85
86 goog.require('goog.array');
87 goog.require('goog.events.EventHandler');
88 goog.require('goog.testing.TestCase');
89 goog.require('goog.testing.asserts');
90
91
92
93 /**
94 * Constructs a test case that supports tests with continuations. Test functions
95 * may issue "wait" commands that suspend the test temporarily and continue once
96 * the wait condition is met.
97 *
98 * @param {string=} opt_name Optional name for the test case.
99 * @constructor
100 * @extends {goog.testing.TestCase}
101 * @deprecated ContinuationTestCase is deprecated. Prefer returning Promises
102 * for tests that assert Asynchronous behavior.
103 * @final
104 */
105 goog.testing.ContinuationTestCase = function(opt_name) {
106 goog.testing.TestCase.call(this, opt_name);
107
108 /**
109 * An event handler for waiting on Closure or browser events during tests.
110 * @type {goog.events.EventHandler<!goog.testing.ContinuationTestCase>}
111 * @private
112 */
113 this.handler_ = new goog.events.EventHandler(this);
114 };
115 goog.inherits(goog.testing.ContinuationTestCase, goog.testing.TestCase);
116
117
118 /**
119 * The default maximum time to wait for a single test step in milliseconds.
120 * @type {number}
121 */
122 goog.testing.ContinuationTestCase.MAX_TIMEOUT = 1000;
123
124
125 /**
126 * Lock used to prevent multiple test steps from running recursively.
127 * @type {boolean}
128 * @private
129 */
130 goog.testing.ContinuationTestCase.locked_ = false;
131
132
133 /**
134 * The current test being run.
135 * @type {goog.testing.ContinuationTestCase.ContinuationTest}
136 * @private
137 */
138 goog.testing.ContinuationTestCase.prototype.currentTest_ = null;
139
140
141 /**
142 * Enables or disables the wait functions in the global scope.
143 * @param {boolean} enable Whether the wait functions should be exported.
144 * @private
145 */
146 goog.testing.ContinuationTestCase.prototype.enableWaitFunctions_ = function(
147 enable) {
148 if (enable) {
149 goog.exportSymbol(
150 'waitForCondition', goog.bind(this.waitForCondition, this));
151 goog.exportSymbol('waitForEvent', goog.bind(this.waitForEvent, this));
152 goog.exportSymbol('waitForTimeout', goog.bind(this.waitForTimeout, this));
153 } else {
154 // Internet Explorer doesn't allow deletion of properties on the window.
155 goog.global['waitForCondition'] = undefined;
156 goog.global['waitForEvent'] = undefined;
157 goog.global['waitForTimeout'] = undefined;
158 }
159 };
160
161
162 /** @override */
163 goog.testing.ContinuationTestCase.prototype.runTests = function() {
164 this.enableWaitFunctions_(true);
165 goog.testing.ContinuationTestCase.superClass_.runTests.call(this);
166 };
167
168
169 /** @override */
170 goog.testing.ContinuationTestCase.prototype.finalize = function() {
171 this.enableWaitFunctions_(false);
172 goog.testing.ContinuationTestCase.superClass_.finalize.call(this);
173 };
174
175
176 /** @override */
177 goog.testing.ContinuationTestCase.prototype.cycleTests = function() {
178 // Get the next test in the queue.
179 if (!this.currentTest_) {
180 this.currentTest_ = this.createNextTest_();
181 }
182
183 // Run the next step of the current test, or exit if all tests are complete.
184 if (this.currentTest_) {
185 this.runNextStep_();
186 } else {
187 this.finalize();
188 }
189 };
190
191
192 /**
193 * Creates the next test in the queue.
194 * @return {goog.testing.ContinuationTestCase.ContinuationTest} The next test to
195 * execute, or null if no pending tests remain.
196 * @private
197 */
198 goog.testing.ContinuationTestCase.prototype.createNextTest_ = function() {
199 var test = this.next();
200 if (!test) {
201 return null;
202 }
203
204
205 var name = test.name;
206 goog.testing.TestCase.currentTestName = name;
207 this.result_.runCount++;
208 this.log('Running test: ' + name);
209
210 return new goog.testing.ContinuationTestCase.ContinuationTest(
211 new goog.testing.TestCase.Test(name, this.setUp, this), test,
212 new goog.testing.TestCase.Test(name, this.tearDown, this));
213 };
214
215
216 /**
217 * Cleans up a finished test and cycles to the next test.
218 * @private
219 */
220 goog.testing.ContinuationTestCase.prototype.finishTest_ = function() {
221 var err = this.currentTest_.getError();
222 if (err) {
223 this.doError(this.currentTest_, err);
224 } else {
225 this.doSuccess(this.currentTest_);
226 }
227
228 goog.testing.TestCase.currentTestName = null;
229 this.currentTest_ = null;
230 this.locked_ = false;
231 this.handler_.removeAll();
232
233 this.timeout(goog.bind(this.cycleTests, this), 0);
234 };
235
236
237 /**
238 * Executes the next step in the current phase, advancing through each phase as
239 * all steps are completed.
240 * @private
241 */
242 goog.testing.ContinuationTestCase.prototype.runNextStep_ = function() {
243 if (this.locked_) {
244 // Attempting to run a step before the previous step has finished. Try again
245 // after that step has released the lock.
246 return;
247 }
248
249 var phase = this.currentTest_.getCurrentPhase();
250
251 if (!phase || !phase.length) {
252 // No more steps for this test.
253 this.finishTest_();
254 return;
255 }
256
257 // Find the next step that is not in a wait state.
258 var stepIndex =
259 goog.array.findIndex(phase, function(step) { return !step.waiting; });
260
261 if (stepIndex < 0) {
262 // All active steps are currently waiting. Return until one wakes up.
263 return;
264 }
265
266 this.locked_ = true;
267 var step = phase[stepIndex];
268
269 try {
270 step.execute();
271 // Remove the successfully completed step. If an error is thrown, all steps
272 // will be removed for this phase.
273 goog.array.removeAt(phase, stepIndex);
274
275 } catch (e) {
276 this.currentTest_.setError(e);
277
278 // An assertion has failed, or an exception was raised. Clear the current
279 // phase, whether it is setUp, test, or tearDown.
280 this.currentTest_.cancelCurrentPhase();
281
282 // Cancel the setUp and test phase no matter where the error occurred. The
283 // tearDown phase will still run if it has pending steps.
284 this.currentTest_.cancelTestPhase();
285 }
286
287 this.locked_ = false;
288 this.runNextStep_();
289 };
290
291
292 /**
293 * Creates a new test step that will run after a user-specified
294 * timeout. No guarantee is made on the execution order of the
295 * continuation, except for those provided by each browser's
296 * window.setTimeout. In particular, if two continuations are
297 * registered at the same time with very small delta for their
298 * durations, this class can not guarantee that the continuation with
299 * the smaller duration will be executed first.
300 * @param {function()} continuation The test function to invoke after the timeout.
301 * @param {number=} opt_duration The length of the timeout in milliseconds.
302 */
303 goog.testing.ContinuationTestCase.prototype.waitForTimeout = function(
304 continuation, opt_duration) {
305 var step = this.addStep_(continuation);
306 step.setTimeout(
307 goog.bind(this.handleComplete_, this, step), opt_duration || 0);
308 };
309
310
311 /**
312 * Creates a new test step that will run after an event has fired. If the event
313 * does not fire within a reasonable timeout, the test will fail.
314 * @param {goog.events.EventTarget|EventTarget} eventTarget The target that will
315 * fire the event.
316 * @param {string} eventType The type of event to listen for.
317 * @param {function()} continuation The test function to invoke after the event
318 * fires.
319 */
320 goog.testing.ContinuationTestCase.prototype.waitForEvent = function(
321 eventTarget, eventType, continuation) {
322
323 var step = this.addStep_(continuation);
324
325 var duration = goog.testing.ContinuationTestCase.MAX_TIMEOUT;
326 step.setTimeout(
327 goog.bind(this.handleTimeout_, this, step, duration), duration);
328
329 this.handler_.listenOnce(
330 eventTarget, eventType, goog.bind(this.handleComplete_, this, step));
331 };
332
333
334 /**
335 * Creates a new test step which will run once a condition becomes true. The
336 * condition will be polled at a user-specified interval until it becomes true,
337 * or until a maximum timeout is reached.
338 * @param {Function} condition The condition to poll.
339 * @param {function()} continuation The test code to evaluate once the condition
340 * becomes true.
341 * @param {number=} opt_interval The polling interval in milliseconds.
342 * @param {number=} opt_maxTimeout The maximum amount of time to wait for the
343 * condition in milliseconds (defaults to 1000).
344 */
345 goog.testing.ContinuationTestCase.prototype.waitForCondition = function(
346 condition, continuation, opt_interval, opt_maxTimeout) {
347
348 var interval = opt_interval || 100;
349 var timeout = opt_maxTimeout || goog.testing.ContinuationTestCase.MAX_TIMEOUT;
350
351 var step = this.addStep_(continuation);
352 this.testCondition_(step, condition, goog.now(), interval, timeout);
353 };
354
355
356 /**
357 * Creates a new asynchronous test step which will be added to the current test
358 * phase.
359 * @param {function()} func The test function that will be executed for this step.
360 * @return {!goog.testing.ContinuationTestCase.Step} A new test step.
361 * @private
362 */
363 goog.testing.ContinuationTestCase.prototype.addStep_ = function(func) {
364 if (!this.currentTest_) {
365 throw new Error('Cannot add test steps outside of a running test.');
366 }
367
368 var step = new goog.testing.ContinuationTestCase.Step(
369 this.currentTest_.name, func, this.currentTest_.scope);
370 this.currentTest_.addStep(step);
371 return step;
372 };
373
374
375 /**
376 * Handles completion of a step's wait condition. Advances the test, allowing
377 * the step's test method to run.
378 * @param {goog.testing.ContinuationTestCase.Step} step The step that has
379 * finished waiting.
380 * @private
381 */
382 goog.testing.ContinuationTestCase.prototype.handleComplete_ = function(step) {
383 step.clearTimeout();
384 step.waiting = false;
385 this.runNextStep_();
386 };
387
388
389 /**
390 * Handles the timeout event for a step that has exceeded the maximum time. This
391 * causes the current test to fail.
392 * @param {goog.testing.ContinuationTestCase.Step} step The timed-out step.
393 * @param {number} duration The length of the timeout in milliseconds.
394 * @private
395 */
396 goog.testing.ContinuationTestCase.prototype.handleTimeout_ = function(
397 step, duration) {
398 step.ref = function() {
399 fail('Continuation timed out after ' + duration + 'ms.');
400 };
401
402 // Since the test is failing, cancel any other pending event listeners.
403 this.handler_.removeAll();
404 this.handleComplete_(step);
405 };
406
407
408 /**
409 * Tests a wait condition and executes the associated test step once the
410 * condition is true.
411 *
412 * If the condition does not become true before the maximum duration, the
413 * interval will stop and the test step will fail in the kill timer.
414 *
415 * @param {goog.testing.ContinuationTestCase.Step} step The waiting test step.
416 * @param {Function} condition The test condition.
417 * @param {number} startTime Time when the test step began waiting.
418 * @param {number} interval The duration in milliseconds to wait between tests.
419 * @param {number} timeout The maximum amount of time to wait for the condition
420 * to become true. Measured from the startTime in milliseconds.
421 * @private
422 */
423 goog.testing.ContinuationTestCase.prototype.testCondition_ = function(
424 step, condition, startTime, interval, timeout) {
425
426 var duration = goog.now() - startTime;
427
428 if (condition()) {
429 this.handleComplete_(step);
430 } else if (duration < timeout) {
431 step.setTimeout(
432 goog.bind(
433 this.testCondition_, this, step, condition, startTime, interval,
434 timeout),
435 interval);
436 } else {
437 this.handleTimeout_(step, duration);
438 }
439 };
440
441
442
443 /**
444 * Creates a continuation test case, which consists of multiple test steps that
445 * occur in several phases.
446 *
447 * The steps are distributed between setUp, test, and tearDown phases. During
448 * the execution of each step, 0 or more steps may be added to the current
449 * phase. Once all steps in a phase have completed, the next phase will be
450 * executed.
451 *
452 * If any errors occur (such as an assertion failure), the setUp and Test phases
453 * will be cancelled immediately. The tearDown phase will always start, but may
454 * be cancelled as well if it raises an error.
455 *
456 * @param {goog.testing.TestCase.Test} setUp A setUp test method to run before
457 * the main test phase.
458 * @param {goog.testing.TestCase.Test} test A test method to run.
459 * @param {goog.testing.TestCase.Test} tearDown A tearDown test method to run
460 * after the test method completes or fails.
461 * @constructor
462 * @extends {goog.testing.TestCase.Test}
463 * @final
464 */
465 goog.testing.ContinuationTestCase.ContinuationTest = function(
466 setUp, test, tearDown) {
467 // This test container has a name, but no evaluation function or scope.
468 goog.testing.TestCase.Test.call(this, test.name, function() {}, null);
469
470 /**
471 * The list of test steps to run during setUp.
472 * @type {Array<goog.testing.TestCase.Test>}
473 * @private
474 */
475 this.setUp_ = [setUp];
476
477 /**
478 * The list of test steps to run for the actual test.
479 * @type {Array<goog.testing.TestCase.Test>}
480 * @private
481 */
482 this.test_ = [test];
483
484 /**
485 * The list of test steps to run during the tearDown phase.
486 * @type {Array<goog.testing.TestCase.Test>}
487 * @private
488 */
489 this.tearDown_ = [tearDown];
490 };
491 goog.inherits(
492 goog.testing.ContinuationTestCase.ContinuationTest,
493 goog.testing.TestCase.Test);
494
495
496 /**
497 * The first error encountered during the test run, if any.
498 * @type {Error}
499 * @private
500 */
501 goog.testing.ContinuationTestCase.ContinuationTest.prototype.error_ = null;
502
503
504 /**
505 * @return {Error} The first error to be raised during the test run or null if
506 * no errors occurred.
507 */
508 goog.testing.ContinuationTestCase.ContinuationTest.prototype.getError =
509 function() {
510 return this.error_;
511 };
512
513
514 /**
515 * Sets an error for the test so it can be reported. Only the first error set
516 * during a test will be reported. Additional errors that occur in later test
517 * phases will be discarded.
518 * @param {Error} e An error.
519 */
520 goog.testing.ContinuationTestCase.ContinuationTest.prototype.setError =
521 function(e) {
522 this.error_ = this.error_ || e;
523 };
524
525
526 /**
527 * @return {Array<goog.testing.TestCase.Test>} The current phase of steps
528 * being processed. Returns null if all steps have been completed.
529 */
530 goog.testing.ContinuationTestCase.ContinuationTest.prototype.getCurrentPhase =
531 function() {
532 if (this.setUp_.length) {
533 return this.setUp_;
534 }
535
536 if (this.test_.length) {
537 return this.test_;
538 }
539
540 if (this.tearDown_.length) {
541 return this.tearDown_;
542 }
543
544 return null;
545 };
546
547
548 /**
549 * Adds a new test step to the end of the current phase. The new step will wait
550 * for a condition to be met before running, or will fail after a timeout.
551 * @param {goog.testing.ContinuationTestCase.Step} step The test step to add.
552 */
553 goog.testing.ContinuationTestCase.ContinuationTest.prototype.addStep = function(
554 step) {
555 var phase = this.getCurrentPhase();
556 if (phase) {
557 phase.push(step);
558 } else {
559 throw new Error('Attempted to add a step to a completed test.');
560 }
561 };
562
563
564 /**
565 * Cancels all remaining steps in the current phase. Called after an error in
566 * any phase occurs.
567 */
568 goog.testing.ContinuationTestCase.ContinuationTest.prototype
569 .cancelCurrentPhase = function() {
570 this.cancelPhase_(this.getCurrentPhase());
571 };
572
573
574 /**
575 * Skips the rest of the setUp and test phases, but leaves the tearDown phase to
576 * clean up.
577 */
578 goog.testing.ContinuationTestCase.ContinuationTest.prototype.cancelTestPhase =
579 function() {
580 this.cancelPhase_(this.setUp_);
581 this.cancelPhase_(this.test_);
582 };
583
584
585 /**
586 * Clears a test phase and cancels any pending steps found.
587 * @param {Array<goog.testing.TestCase.Test>} phase A list of test steps.
588 * @private
589 */
590 goog.testing.ContinuationTestCase.ContinuationTest.prototype.cancelPhase_ =
591 function(phase) {
592 while (phase && phase.length) {
593 var step = phase.pop();
594 if (step instanceof goog.testing.ContinuationTestCase.Step) {
595 step.clearTimeout();
596 }
597 }
598 };
599
600
601
602 /**
603 * Constructs a single step in a larger continuation test. Each step is similar
604 * to a typical TestCase test, except it may wait for an event or timeout to
605 * occur before running the test function.
606 *
607 * @param {string} name The test name.
608 * @param {function()} ref The test function to run.
609 * @param {Object=} opt_scope The object context to run the test in.
610 * @constructor
611 * @extends {goog.testing.TestCase.Test}
612 * @final
613 */
614 goog.testing.ContinuationTestCase.Step = function(name, ref, opt_scope) {
615 goog.testing.TestCase.Test.call(this, name, ref, opt_scope);
616 };
617 goog.inherits(
618 goog.testing.ContinuationTestCase.Step, goog.testing.TestCase.Test);
619
620
621 /**
622 * Whether the step is currently waiting for a condition to continue. All new
623 * steps begin in wait state.
624 * @type {boolean}
625 */
626 goog.testing.ContinuationTestCase.Step.prototype.waiting = true;
627
628
629 /**
630 * A saved reference to window.clearTimeout so that MockClock or other overrides
631 * don't affect continuation timeouts.
632 * @type {Function}
633 * @private
634 */
635 goog.testing.ContinuationTestCase.Step.protectedClearTimeout_ =
636 window.clearTimeout;
637
638
639 /**
640 * A saved reference to window.setTimeout so that MockClock or other overrides
641 * don't affect continuation timeouts.
642 * @type {Function}
643 * @private
644 */
645 goog.testing.ContinuationTestCase.Step.protectedSetTimeout_ = window.setTimeout;
646
647
648 /**
649 * Key to this step's timeout. If the step is waiting for an event, the timeout
650 * will be used as a kill timer. If the step is waiting
651 * @type {number}
652 * @private
653 */
654 goog.testing.ContinuationTestCase.Step.prototype.timeout_;
655
656
657 /**
658 * Starts a timeout for this step. Each step may have only one timeout active at
659 * a time.
660 * @param {Function} func The function to call after the timeout.
661 * @param {number} duration The number of milliseconds to wait before invoking
662 * the function.
663 */
664 goog.testing.ContinuationTestCase.Step.prototype.setTimeout = function(
665 func, duration) {
666
667 this.clearTimeout();
668
669 var setTimeout = goog.testing.ContinuationTestCase.Step.protectedSetTimeout_;
670 this.timeout_ = setTimeout(func, duration);
671 };
672
673
674 /**
675 * Clears the current timeout if it is active.
676 */
677 goog.testing.ContinuationTestCase.Step.prototype.clearTimeout = function() {
678 if (this.timeout_) {
679 var clear = goog.testing.ContinuationTestCase.Step.protectedClearTimeout_;
680
681 clear(this.timeout_);
682 delete this.timeout_;
683 }
684 };