Debian Codegraph @

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

raw
1 // Copyright 2008 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 Matchers to be used with the mock utilities. They allow for
17 * flexible matching by type. Custom matchers can be created by passing a
18 * matcher function into an ArgumentMatcher instance.
19 *
20 * For examples, please see the unit test.
21 *
22 */
23
24
25 goog.setTestOnly('goog.testing.mockmatchers');
26 goog.provide('goog.testing.mockmatchers');
27 goog.provide('goog.testing.mockmatchers.ArgumentMatcher');
28 goog.provide('goog.testing.mockmatchers.IgnoreArgument');
29 goog.provide('goog.testing.mockmatchers.InstanceOf');
30 goog.provide('goog.testing.mockmatchers.ObjectEquals');
31 goog.provide('goog.testing.mockmatchers.RegexpMatch');
32 goog.provide('goog.testing.mockmatchers.SaveArgument');
33 goog.provide('goog.testing.mockmatchers.TypeOf');
34
35 goog.require('goog.array');
36 goog.require('goog.dom');
37 goog.require('goog.testing.asserts');
38
39 goog.forwardDeclare('goog.testing.MockExpectation'); // circular
40
41
42
43 /**
44 * A simple interface for executing argument matching. A match in this case is
45 * testing to see if a supplied object fits a given criteria. True is returned
46 * if the given criteria is met.
47 * @param {Function=} opt_matchFn A function that evaluates a given argument
48 * and returns true if it meets a given criteria.
49 * @param {?string=} opt_matchName The name expressing intent as part of
50 * an error message for when a match fails.
51 * @constructor
52 */
53 goog.testing.mockmatchers.ArgumentMatcher = function(
54 opt_matchFn, opt_matchName) {
55 /**
56 * A function that evaluates a given argument and returns true if it meets a
57 * given criteria.
58 * @type {Function}
59 * @private
60 */
61 this.matchFn_ = opt_matchFn || null;
62
63 /**
64 * A string indicating the match intent (e.g. isBoolean or isString).
65 * @type {?string}
66 * @private
67 */
68 this.matchName_ = opt_matchName || null;
69 };
70
71
72 /**
73 * A function that takes a match argument and an optional MockExpectation
74 * which (if provided) will get error information and returns whether or
75 * not it matches.
76 * @param {*} toVerify The argument that should be verified.
77 * @param {goog.testing.MockExpectation?=} opt_expectation The expectation
78 * for this match.
79 * @return {boolean} Whether or not a given argument passes verification.
80 */
81 goog.testing.mockmatchers.ArgumentMatcher.prototype.matches = function(
82 toVerify, opt_expectation) {
83 if (this.matchFn_) {
84 var isamatch = this.matchFn_(toVerify);
85 if (!isamatch && opt_expectation) {
86 if (this.matchName_) {
87 opt_expectation.addErrorMessage(
88 'Expected: ' + this.matchName_ + ' but was: ' +
89 _displayStringForValue(toVerify));
90 } else {
91 opt_expectation.addErrorMessage(
92 'Expected: missing mockmatcher' +
93 ' description but was: ' + _displayStringForValue(toVerify));
94 }
95 }
96 return isamatch;
97 } else {
98 throw new Error('No match function defined for this mock matcher');
99 }
100 };
101
102
103
104 /**
105 * A matcher that verifies that an argument is an instance of a given class.
106 * @param {Function} ctor The class that will be used for verification.
107 * @constructor
108 * @extends {goog.testing.mockmatchers.ArgumentMatcher}
109 * @final
110 */
111 goog.testing.mockmatchers.InstanceOf = function(ctor) {
112 goog.testing.mockmatchers.ArgumentMatcher.call(this, function(obj) {
113 return obj instanceof ctor;
114 // NOTE: Browser differences on ctor.toString() output
115 // make using that here problematic. So for now, just let
116 // people know the instanceOf() failed without providing
117 // browser specific details...
118 }, 'instanceOf()');
119 };
120 goog.inherits(
121 goog.testing.mockmatchers.InstanceOf,
122 goog.testing.mockmatchers.ArgumentMatcher);
123
124
125
126 /**
127 * A matcher that verifies that an argument is of a given type (e.g. "object").
128 * @param {string} type The type that a given argument must have.
129 * @constructor
130 * @extends {goog.testing.mockmatchers.ArgumentMatcher}
131 * @final
132 */
133 goog.testing.mockmatchers.TypeOf = function(type) {
134 goog.testing.mockmatchers.ArgumentMatcher.call(this, function(obj) {
135 return goog.typeOf(obj) == type;
136 }, 'typeOf(' + type + ')');
137 };
138 goog.inherits(
139 goog.testing.mockmatchers.TypeOf,
140 goog.testing.mockmatchers.ArgumentMatcher);
141
142
143
144 /**
145 * A matcher that verifies that an argument matches a given RegExp.
146 * @param {RegExp} regexp The regular expression that the argument must match.
147 * @constructor
148 * @extends {goog.testing.mockmatchers.ArgumentMatcher}
149 * @final
150 */
151 goog.testing.mockmatchers.RegexpMatch = function(regexp) {
152 goog.testing.mockmatchers.ArgumentMatcher.call(this, function(str) {
153 return regexp.test(str);
154 }, 'match(' + regexp + ')');
155 };
156 goog.inherits(
157 goog.testing.mockmatchers.RegexpMatch,
158 goog.testing.mockmatchers.ArgumentMatcher);
159
160
161
162 /**
163 * A matcher that always returns true. It is useful when the user does not care
164 * for some arguments.
165 * For example: mockFunction('username', 'password', IgnoreArgument);
166 * @constructor
167 * @extends {goog.testing.mockmatchers.ArgumentMatcher}
168 * @final
169 */
170 goog.testing.mockmatchers.IgnoreArgument = function() {
171 goog.testing.mockmatchers.ArgumentMatcher.call(
172 this, function() { return true; }, 'true');
173 };
174 goog.inherits(
175 goog.testing.mockmatchers.IgnoreArgument,
176 goog.testing.mockmatchers.ArgumentMatcher);
177
178
179
180 /**
181 * A matcher that verifies that the argument is an object that equals the given
182 * expected object, using a deep comparison.
183 * @param {Object} expectedObject An object to match against when
184 * verifying the argument.
185 * @constructor
186 * @extends {goog.testing.mockmatchers.ArgumentMatcher}
187 */
188 goog.testing.mockmatchers.ObjectEquals = function(expectedObject) {
189 /** @private */
190 this.expectedObject_ = expectedObject;
191 };
192 goog.inherits(
193 goog.testing.mockmatchers.ObjectEquals,
194 goog.testing.mockmatchers.ArgumentMatcher);
195
196
197 /** @override */
198 goog.testing.mockmatchers.ObjectEquals.prototype.matches = function(
199 toVerify, opt_expectation) {
200 // Override the default matches implementation to provide a custom error
201 // message to opt_expectation if it exists.
202 var differences =
203 goog.testing.asserts.findDifferences(this.expectedObject_, toVerify);
204 if (differences) {
205 if (opt_expectation) {
206 opt_expectation.addErrorMessage('Expected equal objects\n' + differences);
207 }
208 return false;
209 }
210 return true;
211 };
212
213
214
215 /**
216 * A matcher that saves the argument that it is verifying so that your unit test
217 * can perform extra tests with this argument later. For example, if the
218 * argument is a callback method, the unit test can then later call this
219 * callback to test the asynchronous portion of the call.
220 * @param {goog.testing.mockmatchers.ArgumentMatcher|Function=} opt_matcher
221 * Argument matcher or matching function that will be used to validate the
222 * argument. By default, argument will always be valid.
223 * @param {?string=} opt_matchName The name expressing intent as part of
224 * an error message for when a match fails.
225 * @constructor
226 * @extends {goog.testing.mockmatchers.ArgumentMatcher}
227 * @final
228 */
229 goog.testing.mockmatchers.SaveArgument = function(opt_matcher, opt_matchName) {
230 goog.testing.mockmatchers.ArgumentMatcher.call(
231 this, /** @type {Function} */ (opt_matcher), opt_matchName);
232
233 if (opt_matcher instanceof goog.testing.mockmatchers.ArgumentMatcher) {
234 /**
235 * Delegate match requests to this matcher.
236 * @type {goog.testing.mockmatchers.ArgumentMatcher}
237 * @private
238 */
239 this.delegateMatcher_ = opt_matcher;
240 } else if (!opt_matcher) {
241 this.delegateMatcher_ = goog.testing.mockmatchers.ignoreArgument;
242 }
243 };
244 goog.inherits(
245 goog.testing.mockmatchers.SaveArgument,
246 goog.testing.mockmatchers.ArgumentMatcher);
247
248
249 /** @override */
250 goog.testing.mockmatchers.SaveArgument.prototype.matches = function(
251 toVerify, opt_expectation) {
252 this.arg = toVerify;
253 if (this.delegateMatcher_) {
254 return this.delegateMatcher_.matches(toVerify, opt_expectation);
255 }
256 return goog.testing.mockmatchers.SaveArgument.superClass_.matches.call(
257 this, toVerify, opt_expectation);
258 };
259
260
261 /**
262 * Saved argument that was verified.
263 * @type {*}
264 */
265 goog.testing.mockmatchers.SaveArgument.prototype.arg;
266
267
268 /**
269 * An instance of the IgnoreArgument matcher. Returns true for all matches.
270 * @type {goog.testing.mockmatchers.IgnoreArgument}
271 */
272 goog.testing.mockmatchers.ignoreArgument =
273 new goog.testing.mockmatchers.IgnoreArgument();
274
275
276 /**
277 * A matcher that verifies that an argument is an array.
278 * @type {goog.testing.mockmatchers.ArgumentMatcher}
279 */
280 goog.testing.mockmatchers.isArray =
281 new goog.testing.mockmatchers.ArgumentMatcher(goog.isArray, 'isArray');
282
283
284 /**
285 * A matcher that verifies that an argument is a array-like. A NodeList is an
286 * example of a collection that is very close to an array.
287 * @type {goog.testing.mockmatchers.ArgumentMatcher}
288 */
289 goog.testing.mockmatchers.isArrayLike =
290 new goog.testing.mockmatchers.ArgumentMatcher(
291 goog.isArrayLike, 'isArrayLike');
292
293
294 /**
295 * A matcher that verifies that an argument is a date-like.
296 * @type {goog.testing.mockmatchers.ArgumentMatcher}
297 */
298 goog.testing.mockmatchers.isDateLike =
299 new goog.testing.mockmatchers.ArgumentMatcher(
300 goog.isDateLike, 'isDateLike');
301
302
303 /**
304 * A matcher that verifies that an argument is a string.
305 * @type {goog.testing.mockmatchers.ArgumentMatcher}
306 */
307 goog.testing.mockmatchers.isString =
308 new goog.testing.mockmatchers.ArgumentMatcher(goog.isString, 'isString');
309
310
311 /**
312 * A matcher that verifies that an argument is a boolean.
313 * @type {goog.testing.mockmatchers.ArgumentMatcher}
314 */
315 goog.testing.mockmatchers.isBoolean =
316 new goog.testing.mockmatchers.ArgumentMatcher(goog.isBoolean, 'isBoolean');
317
318
319 /**
320 * A matcher that verifies that an argument is a number.
321 * @type {goog.testing.mockmatchers.ArgumentMatcher}
322 */
323 goog.testing.mockmatchers.isNumber =
324 new goog.testing.mockmatchers.ArgumentMatcher(goog.isNumber, 'isNumber');
325
326
327 /**
328 * A matcher that verifies that an argument is a function.
329 * @type {goog.testing.mockmatchers.ArgumentMatcher}
330 */
331 goog.testing.mockmatchers.isFunction =
332 new goog.testing.mockmatchers.ArgumentMatcher(
333 goog.isFunction, 'isFunction');
334
335
336 /**
337 * A matcher that verifies that an argument is an object.
338 * @type {goog.testing.mockmatchers.ArgumentMatcher}
339 */
340 goog.testing.mockmatchers.isObject =
341 new goog.testing.mockmatchers.ArgumentMatcher(goog.isObject, 'isObject');
342
343
344 /**
345 * A matcher that verifies that an argument is like a DOM node.
346 * @type {goog.testing.mockmatchers.ArgumentMatcher}
347 */
348 goog.testing.mockmatchers.isNodeLike =
349 new goog.testing.mockmatchers.ArgumentMatcher(
350 goog.dom.isNodeLike, 'isNodeLike');
351
352
353 /**
354 * A function that checks to see if an array matches a given set of
355 * expectations. The expectations array can be a mix of ArgumentMatcher
356 * implementations and values. True will be returned if values are identical or
357 * if a matcher returns a positive result.
358 * @param {Array<?>} expectedArr An array of expectations which can be either
359 * values to check for equality or ArgumentMatchers.
360 * @param {Array<?>} arr The array to match.
361 * @param {goog.testing.MockExpectation?=} opt_expectation The expectation
362 * for this match.
363 * @return {boolean} Whether or not the given array matches the expectations.
364 */
365 goog.testing.mockmatchers.flexibleArrayMatcher = function(
366 expectedArr, arr, opt_expectation) {
367 return goog.array.equals(expectedArr, arr, function(a, b) {
368 var errCount = 0;
369 if (opt_expectation) {
370 errCount = opt_expectation.getErrorMessageCount();
371 }
372 var isamatch = a === b ||
373 a instanceof goog.testing.mockmatchers.ArgumentMatcher &&
374 a.matches(b, opt_expectation);
375 var failureMessage = null;
376 if (!isamatch) {
377 failureMessage = goog.testing.asserts.findDifferences(a, b);
378 isamatch = !failureMessage;
379 }
380 if (!isamatch && opt_expectation) {
381 // If the error count changed, the match sent out an error
382 // message. If the error count has not changed, then
383 // we need to send out an error message...
384 if (errCount == opt_expectation.getErrorMessageCount()) {
385 // Use the _displayStringForValue() from assert.js
386 // for consistency...
387 if (!failureMessage) {
388 failureMessage = 'Expected: ' + _displayStringForValue(a) +
389 ' but was: ' + _displayStringForValue(b);
390 }
391 opt_expectation.addErrorMessage(failureMessage);
392 }
393 }
394 return isamatch;
395 });
396 };