Debian Codegraph @

closure-library/closure/goog/testing/recordfunction.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 Helper class for recording the calls of a function.
17 *
18 * Example:
19 * <pre>
20 * var stubs = new goog.testing.PropertyReplacer();
21 *
22 * function tearDown() {
23 * stubs.reset();
24 * }
25 *
26 * function testShuffle() {
27 * stubs.replace(Math, 'random', goog.testing.recordFunction(Math.random));
28 * var arr = shuffle([1, 2, 3, 4, 5]);
29 * assertSameElements([1, 2, 3, 4, 5], arr);
30 * assertEquals(4, Math.random.getCallCount());
31 * }
32 *
33 * function testOpenDialog() {
34 * stubs.replace(goog.ui, 'Dialog',
35 * goog.testing.recordConstructor(goog.ui.Dialog));
36 * openConfirmDialog();
37 * var lastDialogInstance = goog.ui.Dialog.getLastCall().getThis();
38 * assertEquals('confirm', lastDialogInstance.getTitle());
39 * }
40 * </pre>
41 *
42 */
43
44 goog.setTestOnly('goog.testing.FunctionCall');
45 goog.provide('goog.testing.FunctionCall');
46 goog.provide('goog.testing.recordConstructor');
47 goog.provide('goog.testing.recordFunction');
48
49 goog.require('goog.testing.asserts');
50
51
52 /**
53 * Wraps the function into another one which calls the inner function and
54 * records its calls. The recorded function will have 3 static methods:
55 * {@code getCallCount}, {@code getCalls} and {@code getLastCall} but won't
56 * inherit the original function's prototype and static fields.
57 *
58 * @param {!Function=} opt_f The function to wrap and record. Defaults to
59 * {@link goog.nullFunction}.
60 * @return {!Function} The wrapped function.
61 */
62 goog.testing.recordFunction = function(opt_f) {
63 var f = opt_f || goog.nullFunction;
64 var calls = [];
65
66 function recordedFunction() {
67 try {
68 var ret = f.apply(this, arguments);
69 calls.push(new goog.testing.FunctionCall(f, this, arguments, ret, null));
70 return ret;
71 } catch (err) {
72 calls.push(
73 new goog.testing.FunctionCall(f, this, arguments, undefined, err));
74 throw err;
75 }
76 }
77
78 /**
79 * @return {number} Total number of calls.
80 */
81 recordedFunction.getCallCount = function() { return calls.length; };
82
83 /**
84 * Asserts that the function was called a certain number of times.
85 * @param {number|string} a The expected number of calls (1 arg) or debug
86 * message (2 args).
87 * @param {number=} opt_b The expected number of calls (2 args only).
88 */
89 recordedFunction.assertCallCount = function(a, opt_b) {
90 var actual = calls.length;
91 var expected = arguments.length == 1 ? a : opt_b;
92 var message = arguments.length == 1 ? '' : ' ' + a;
93 assertEquals(
94 'Expected ' + expected + ' call(s), but was ' + actual + '.' + message,
95 expected, actual);
96 };
97
98 /**
99 * @return {!Array<!goog.testing.FunctionCall>} All calls of the recorded
100 * function.
101 */
102 recordedFunction.getCalls = function() { return calls; };
103
104
105 /**
106 * @return {goog.testing.FunctionCall} Last call of the recorded function or
107 * null if it hasn't been called.
108 */
109 recordedFunction.getLastCall = function() {
110 return calls[calls.length - 1] || null;
111 };
112
113 /**
114 * Returns and removes the last call of the recorded function.
115 * @return {goog.testing.FunctionCall} Last call of the recorded function or
116 * null if it hasn't been called.
117 */
118 recordedFunction.popLastCall = function() { return calls.pop() || null; };
119
120 /**
121 * Resets the recorded function and removes all calls.
122 */
123 recordedFunction.reset = function() { calls.length = 0; };
124
125 return recordedFunction;
126 };
127
128
129 /**
130 * Same as {@link goog.testing.recordFunction} but the recorded function will
131 * have the same prototype and static fields as the original one. It can be
132 * used with constructors.
133 *
134 * @param {!Function} ctor The function to wrap and record.
135 * @return {!Function} The wrapped function.
136 */
137 goog.testing.recordConstructor = function(ctor) {
138 var recordedConstructor = goog.testing.recordFunction(ctor);
139 recordedConstructor.prototype = ctor.prototype;
140 goog.mixin(recordedConstructor, ctor);
141 return recordedConstructor;
142 };
143
144
145
146 /**
147 * Struct for a single function call.
148 * @param {!Function} func The called function.
149 * @param {!Object} thisContext {@code this} context of called function.
150 * @param {!Arguments} args Arguments of the called function.
151 * @param {*} ret Return value of the function or undefined in case of error.
152 * @param {*} error The error thrown by the function or null if none.
153 * @constructor
154 */
155 goog.testing.FunctionCall = function(func, thisContext, args, ret, error) {
156 this.function_ = func;
157 this.thisContext_ = thisContext;
158 this.arguments_ = Array.prototype.slice.call(args);
159 this.returnValue_ = ret;
160 this.error_ = error;
161 };
162
163
164 /**
165 * @return {!Function} The called function.
166 */
167 goog.testing.FunctionCall.prototype.getFunction = function() {
168 return this.function_;
169 };
170
171
172 /**
173 * @return {!Object} {@code this} context of called function. It is the same as
174 * the created object if the function is a constructor.
175 */
176 goog.testing.FunctionCall.prototype.getThis = function() {
177 return this.thisContext_;
178 };
179
180
181 /**
182 * @return {!Array<?>} Arguments of the called function.
183 */
184 goog.testing.FunctionCall.prototype.getArguments = function() {
185 return this.arguments_;
186 };
187
188
189 /**
190 * Returns the nth argument of the called function.
191 * @param {number} index 0-based index of the argument.
192 * @return {*} The argument value or undefined if there is no such argument.
193 */
194 goog.testing.FunctionCall.prototype.getArgument = function(index) {
195 return this.arguments_[index];
196 };
197
198
199 /**
200 * @return {*} Return value of the function or undefined in case of error.
201 */
202 goog.testing.FunctionCall.prototype.getReturnValue = function() {
203 return this.returnValue_;
204 };
205
206
207 /**
208 * @return {*} The error thrown by the function or null if none.
209 */
210 goog.testing.FunctionCall.prototype.getError = function() {
211 return this.error_;
212 };