Debian Codegraph @

closure-library/closure/goog/testing/async/mockcontrol.js

raw
1 // Copyright 2010 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 wrapper for MockControl that provides mocks and assertions
17 * for testing asynchronous code. All assertions will only be verified when
18 * $verifyAll is called on the wrapped MockControl.
19 *
20 * This class is meant primarily for testing code that exposes asynchronous APIs
21 * without being truly asynchronous (using asynchronous primitives like browser
22 * events or timeouts). This is often the case when true asynchronous
23 * depedencies have been mocked out. This means that it doesn't rely on
24 * AsyncTestCase or DeferredTestCase, although it can be used with those as
25 * well.
26 *
27 * Example usage:
28 *
29 * <pre>
30 * var mockControl = new goog.testing.MockControl();
31 * var asyncMockControl = new goog.testing.async.MockControl(mockControl);
32 *
33 * myAsyncObject.onSuccess(asyncMockControl.asyncAssertEquals(
34 * 'callback should run and pass the correct value',
35 * 'http://someurl.com');
36 * asyncMockControl.assertDeferredEquals(
37 * 'deferred object should be resolved with the correct value',
38 * 'http://someurl.com',
39 * myAsyncObject.getDeferredUrl());
40 * asyncMockControl.run();
41 * mockControl.$verifyAll();
42 * </pre>
43 *
44 */
45
46
47 goog.setTestOnly('goog.testing.async.MockControl');
48 goog.provide('goog.testing.async.MockControl');
49
50 goog.require('goog.asserts');
51 goog.require('goog.async.Deferred');
52 goog.require('goog.debug');
53 goog.require('goog.testing.asserts');
54 goog.require('goog.testing.mockmatchers.IgnoreArgument');
55
56
57
58 /**
59 * Provides asynchronous mocks and assertions controlled by a parent
60 * MockControl.
61 *
62 * @param {goog.testing.MockControl} mockControl The parent MockControl.
63 * @constructor
64 * @final
65 */
66 goog.testing.async.MockControl = function(mockControl) {
67 /**
68 * The parent MockControl.
69 * @type {goog.testing.MockControl}
70 * @private
71 */
72 this.mockControl_ = mockControl;
73 };
74
75
76 /**
77 * Returns a function that will assert that it will be called, and run the given
78 * callback when it is.
79 *
80 * @param {string} name The name of the callback mock.
81 * @param {function(...*) : *} callback The wrapped callback. This will be
82 * called when the returned function is called.
83 * @param {Object=} opt_selfObj The object which this should point to when the
84 * callback is run.
85 * @return {!Function} The mock callback.
86 * @suppress {missingProperties} Mocks do not fit in the type system well.
87 */
88 goog.testing.async.MockControl.prototype.createCallbackMock = function(
89 name, callback, opt_selfObj) {
90 goog.asserts.assert(
91 goog.isString(name),
92 'name parameter ' + goog.debug.deepExpose(name) + ' should be a string');
93
94 var ignored = new goog.testing.mockmatchers.IgnoreArgument();
95
96 // Use everyone's favorite "double-cast" trick to subvert the type system.
97 var obj = /** @type {Object} */ (this.mockControl_.createFunctionMock(name));
98 var fn = /** @type {Function} */ (obj);
99
100 fn(ignored).$does(function(args) {
101 if (opt_selfObj) {
102 callback = goog.bind(callback, opt_selfObj);
103 }
104 return callback.apply(this, args);
105 });
106 fn.$replay();
107 return function() { return fn(arguments); };
108 };
109
110
111 /**
112 * Returns a function that will assert that its arguments are equal to the
113 * arguments given to asyncAssertEquals. In addition, the function also asserts
114 * that it will be called.
115 *
116 * @param {string} message A message to print if the arguments are wrong.
117 * @param {...*} var_args The arguments to assert.
118 * @return {function(...*) : void} The mock callback.
119 */
120 goog.testing.async.MockControl.prototype.asyncAssertEquals = function(
121 message, var_args) {
122 var expectedArgs = Array.prototype.slice.call(arguments, 1);
123 return this.createCallbackMock('asyncAssertEquals', function() {
124 assertObjectEquals(
125 message, expectedArgs, Array.prototype.slice.call(arguments));
126 });
127 };
128
129
130 /**
131 * Asserts that a deferred object will have an error and call its errback
132 * function.
133 * @param {goog.async.Deferred} deferred The deferred object.
134 * @param {function() : void} fn A function wrapping the code in which the error
135 * will occur.
136 */
137 goog.testing.async.MockControl.prototype.assertDeferredError = function(
138 deferred, fn) {
139 deferred.addErrback(
140 this.createCallbackMock('assertDeferredError', function() {}));
141 goog.testing.asserts.callWithoutLogging(fn);
142 };
143
144
145 /**
146 * Asserts that a deferred object will call its callback with the given value.
147 *
148 * @param {string} message A message to print if the arguments are wrong.
149 * @param {goog.async.Deferred|*} expected The expected value. If this is a
150 * deferred object, then the expected value is the deferred value.
151 * @param {goog.async.Deferred|*} actual The actual value. If this is a deferred
152 * object, then the actual value is the deferred value. Either this or
153 * 'expected' must be deferred.
154 */
155 goog.testing.async.MockControl.prototype.assertDeferredEquals = function(
156 message, expected, actual) {
157 if (expected instanceof goog.async.Deferred &&
158 actual instanceof goog.async.Deferred) {
159 // Assert that the first deferred is resolved.
160 expected.addCallback(
161 this.createCallbackMock('assertDeferredEquals', function(exp) {
162 // Assert that the second deferred is resolved, and that the value is
163 // as expected.
164 actual.addCallback(this.asyncAssertEquals(message, exp));
165 }, this));
166 } else if (expected instanceof goog.async.Deferred) {
167 expected.addCallback(
168 this.createCallbackMock('assertDeferredEquals', function(exp) {
169 assertObjectEquals(message, exp, actual);
170 }));
171 } else if (actual instanceof goog.async.Deferred) {
172 actual.addCallback(this.asyncAssertEquals(message, expected));
173 } else {
174 throw new Error('Either expected or actual must be deferred');
175 }
176 };