/**
* @license
* Copyright The Closure Library Authors.
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview This file defines base classes used for creating mocks in
* JavaScript. The API was inspired by EasyMock.
*
* The basic API is:
* <ul>
* <li>Create an object to be mocked
* <li>Create a mock object, passing in the above object to the constructor
* <li>Set expectations by calling methods on the mock object
* <li>Call $replay() on the mock object
* <li>Pass the mock to code that will make real calls on it
* <li>Call $verify() to make sure that expectations were met
* </ul>
*
* For examples, please see the unit tests for LooseMock and StrictMock.
*
* Still TODO
* implement better (and pluggable) argument matching
* Have the exceptions for LooseMock show the number of expected/actual calls
* loose and strict mocks share a lot of code - move it to the base class
*/
goog.setTestOnly('goog.testing.Mock');
goog.provide('goog.testing.Mock');
goog.provide('goog.testing.MockExpectation');
goog.require('goog.Promise');
goog.require('goog.asserts');
goog.require('goog.object');
goog.require('goog.promise.Resolver');
goog.require('goog.testing.JsUnitException');
goog.require('goog.testing.MockInterface');
goog.require('goog.testing.mockmatchers');
/**
* This is a class that represents an expectation.
* @param {string} name The name of the method for this expectation.
* @constructor
* @final
*/
goog.testing.MockExpectation = function(name) {
'use strict';
/**
* The name of the method that is expected to be called.
* @type {string}
*/
this.name = name;
/**
* An array of error messages for expectations not met.
* @type {Array<string>}
*/
this.errorMessages = [];
};
/**
* The minimum number of times this method should be called.
* @type {number}
*/
goog.testing.MockExpectation.prototype.minCalls = 1;
/**
* The maximum number of times this method should be called.
* @type {number}
*/
goog.testing.MockExpectation.prototype.maxCalls = 1;
/**
* The value that this method should return.
* @type {*}
*/
goog.testing.MockExpectation.prototype.returnValue;
/**
* The value that will be thrown when the method is called
* @type {*}
*/
goog.testing.MockExpectation.prototype.exceptionToThrow;
/**
* The arguments that are expected to be passed to this function
* @type {Array<*>}
*/
goog.testing.MockExpectation.prototype.argumentList;
/**
* The number of times this method is called by real code.
* @type {number}
*/
goog.testing.MockExpectation.prototype.actualCalls = 0;
/**
* The number of times this method is called during the verification phase.
* @type {number}
*/
goog.testing.MockExpectation.prototype.verificationCalls = 0;
/**
* The function which will be executed when this method is called.
* Method arguments will be passed to this function, and return value
* of this function will be returned by the method.
* @type {Function}
*/
goog.testing.MockExpectation.prototype.toDo;
/**
* Allow expectation failures to include messages.
* @param {string} message The failure message.
*/
goog.testing.MockExpectation.prototype.addErrorMessage = function(message) {
'use strict';
this.errorMessages.push(message);
};
/**
* Get the error messages seen so far.
* @return {string} Error messages separated by \n.
*/
goog.testing.MockExpectation.prototype.getErrorMessage = function() {
'use strict';
return this.errorMessages.join('\n');
};
/**
* Get how many error messages have been seen so far.
* @return {number} Count of error messages.
*/
goog.testing.MockExpectation.prototype.getErrorMessageCount = function() {
'use strict';
return this.errorMessages.length;
};
/**
* The base class for a mock object.
* @param {Object|Function} objectToMock The object that should be mocked, or
* the constructor of an object to mock.
* @param {boolean=} opt_mockStaticMethods An optional argument denoting that
* a mock should be constructed from the static functions of a class.
* @param {boolean=} opt_createProxy An optional argument denoting that
* a proxy for the target mock should be created.
* @constructor
* @implements {goog.testing.MockInterface}
*/
goog.testing.Mock = function(
objectToMock, opt_mockStaticMethods, opt_createProxy) {
'use strict';
if (!goog.isObject(objectToMock) && typeof objectToMock !== 'function') {
throw new Error('objectToMock must be an object or constructor.');
}
if (opt_createProxy && !opt_mockStaticMethods &&
typeof objectToMock === 'function') {
/**
* @constructor
* @final
*/
var tempCtor = function() {};
goog.inherits(tempCtor, objectToMock);
this.$proxy = new tempCtor();
} else if (
opt_createProxy && opt_mockStaticMethods &&
typeof objectToMock === 'function') {
throw new Error('Cannot create a proxy when opt_mockStaticMethods is true');
} else if (opt_createProxy && typeof objectToMock !== 'function') {
throw new Error('Must have a constructor to create a proxy');
}
if (typeof objectToMock === 'function' && !opt_mockStaticMethods) {
this.$initializeFunctions_(objectToMock.prototype);
} else {
this.$initializeFunctions_(objectToMock);
}
this.$argumentListVerifiers_ = {};
/** @protected {?goog.promise.Resolver<undefined>} */
this.waitingForExpectations = null;
};
/**
* Option that may be passed when constructing function, method, and
* constructor mocks. Indicates that the expected calls should be accepted in
* any order.
* @const
* @type {number}
*/
goog.testing.Mock.LOOSE = 1;
/**
* Option that may be passed when constructing function, method, and
* constructor mocks. Indicates that the expected calls should be accepted in
* the recorded order only.
* @const
* @type {number}
*/
goog.testing.Mock.STRICT = 0;
/**
* Asserts that a mock object is in record mode. This avoids type system errors
* from mock expectations.
*
* Usage:
*
* ```
* const record = goog.require('goog.testing.Mock.record');
*
* record(mockObject).someMethod(ignoreArgument).$returns(42);
* record(mockFunction)(ignoreArgument).$returns(42);
* ```
*
* @param {?} obj A mock in record mode.
* @return {?} The same object.
*/
goog.testing.Mock.record = function(obj) {
'use strict';
goog.asserts.assert(
obj.$recording_ !== undefined,
'%s is not a mock. Did you pass a real object to record()?', obj);
goog.asserts.assert(
obj.$recording_,
'Your mock is in replay mode. You can only call record(mock) before mock.$replay()');
return obj;
};
/**
* This array contains the name of the functions that are part of the base
* Object prototype.
* Basically a copy of goog.object.PROTOTYPE_FIELDS_.
* @const
* @type {!Array<string>}
* @private
*/
goog.testing.Mock.OBJECT_PROTOTYPE_FIELDS_ = [
'constructor', 'hasOwnProperty', 'isPrototypeOf', 'propertyIsEnumerable',
'toLocaleString', 'toString', 'valueOf'
];
/**
* This array contains the name of the functions that are part of the base
* Function prototype. The restricted field 'caller' and 'arguments' are
* excluded.
* @const
* @type {!Array<string>}
* @private
*/
goog.testing.Mock.FUNCTION_PROTOTYPE_FIELDS_ = ['apply', 'bind', 'call'];
/**
* A proxy for the mock. This can be used for dependency injection in lieu of
* the mock if the test requires a strict instanceof check.
* @type {?Object}
*/
goog.testing.Mock.prototype.$proxy = null;
/**
* Map of argument name to optional argument list verifier function.
* @type {Object}
*/
goog.testing.Mock.prototype.$argumentListVerifiers_;
/**
* Whether or not we are in recording mode.
* @type {boolean}
* @private
*/
goog.testing.Mock.prototype.$recording_ = true;
/**
* The expectation currently being created. All methods that modify the
* current expectation return the Mock object for easy chaining, so this is
* where we keep track of the expectation that's currently being modified.
* @type {goog.testing.MockExpectation}
* @protected
*/
goog.testing.Mock.prototype.$pendingExpectation;
/**
* First exception thrown by this mock; used in $verify.
* @type {?Object}
* @private
*/
goog.testing.Mock.prototype.$threwException_ = null;
/**
* Initializes the functions on the mock object.
* @param {Object} objectToMock The object being mocked.
* @private
*/
goog.testing.Mock.prototype.$initializeFunctions_ = function(objectToMock) {
'use strict';
// Gets the object properties.
var enumerableProperties = goog.object.getAllPropertyNames(
objectToMock, false /* opt_includeObjectPrototype */,
false /* opt_includeFunctionPrototype */);
if (typeof objectToMock === 'function') {
for (var i = 0; i < goog.testing.Mock.FUNCTION_PROTOTYPE_FIELDS_.length;
i++) {
var prop = goog.testing.Mock.FUNCTION_PROTOTYPE_FIELDS_[i];
// Look at b/6758711 if you're considering adding ALL properties to ALL
// mocks.
if (objectToMock[prop] !== Function.prototype[prop]) {
enumerableProperties.push(prop);
}
}
}
// The non enumerable properties are added if they override the ones in the
// Object prototype. This is due to the fact that IE8 does not enumerate any
// of the prototype Object functions even when overridden and mocking these is
// sometimes needed.
for (var i = 0; i < goog.testing.Mock.OBJECT_PROTOTYPE_FIELDS_.length; i++) {
var prop = goog.testing.Mock.OBJECT_PROTOTYPE_FIELDS_[i];
// Look at b/6758711 if you're considering adding ALL properties to ALL
// mocks.
if (objectToMock[prop] !== Object.prototype[prop]) {
enumerableProperties.push(prop);
}
}
// Adds the properties to the mock.
for (var i = 0; i < enumerableProperties.length; i++) {
var prop = enumerableProperties[i];
if (typeof objectToMock[prop] == 'function') {
this[prop] = goog.bind(this.$mockMethod, this, prop);
if (this.$proxy) {
this.$proxy[prop] = goog.bind(this.$mockMethod, this, prop);
}
}
}
};
/**
* Registers a verifier function to use when verifying method argument lists.
* @param {string} methodName The name of the method for which the verifierFn
* should be used.
* @param {Function} fn Argument list verifier function. Should take 2 argument
* arrays as arguments, and return true if they are considered equivalent.
* @return {!goog.testing.Mock} This mock object.
*/
goog.testing.Mock.prototype.$registerArgumentListVerifier = function(
methodName, fn) {
'use strict';
this.$argumentListVerifiers_[methodName] = fn;
return this;
};
/**
* The function that replaces all methods on the mock object.
* @param {string} name The name of the method being mocked.
* @return {*} In record mode, returns the mock object. In replay mode, returns
* whatever the creator of the mock set as the return value.
*/
goog.testing.Mock.prototype.$mockMethod = function(name) {
'use strict';
try {
// Shift off the name argument so that args contains the arguments to
// the mocked method.
var args = Array.prototype.slice.call(arguments, 1);
if (this.$recording_) {
this.$pendingExpectation = new goog.testing.MockExpectation(name);
this.$pendingExpectation.argumentList = args;
this.$recordExpectation();
return this;
} else {
return this.$recordCall(name, args);
}
} catch (ex) {
this.$recordAndThrow(ex, true /* rethrow */);
}
};
/**
* Records the currently pending expectation, intended to be overridden by a
* subclass.
* @protected
*/
goog.testing.Mock.prototype.$recordExpectation = function() {};
/**
* Records an actual method call, intended to be overridden by a
* subclass. The subclass must find the pending expectation and return the
* correct value.
* @param {string} name The name of the method being called.
* @param {Array<?>} args The arguments to the method.
* @return {*} The return expected by the mock.
* @protected
*/
goog.testing.Mock.prototype.$recordCall = function(name, args) {
'use strict';
return undefined;
};
/**
* If the expectation expects to throw, this method will throw.
* @param {goog.testing.MockExpectation} expectation The expectation.
*/
goog.testing.Mock.prototype.$maybeThrow = function(expectation) {
'use strict';
if (typeof expectation.exceptionToThrow != 'undefined') {
throw expectation.exceptionToThrow;
}
};
/**
* If this expectation defines a function to be called,
* it will be called and its result will be returned.
* Otherwise, if the expectation expects to throw, it will throw.
* Otherwise, this method will return defined value.
* @param {goog.testing.MockExpectation} expectation The expectation.
* @param {Array<?>} args The arguments to the method.
* @return {*} The return value expected by the mock.
*/
goog.testing.Mock.prototype.$do = function(expectation, args) {
'use strict';
if (typeof expectation.toDo == 'undefined') {
this.$maybeThrow(expectation);
return expectation.returnValue;
} else {
return expectation.toDo.apply(this, args);
}
};
/**
* Specifies a return value for the currently pending expectation.
* @param {*} val The return value.
* @return {!goog.testing.Mock} This mock object.
*/
goog.testing.Mock.prototype.$returns = function(val) {
'use strict';
this.$pendingExpectation.returnValue = val;
return this;
};
/**
* Specifies a value for the currently pending expectation to throw.
* @param {*} val The value to throw.
* @return {!goog.testing.Mock} This mock object.
*/
goog.testing.Mock.prototype.$throws = function(val) {
'use strict';
this.$pendingExpectation.exceptionToThrow = val;
return this;
};
/**
* Specifies a function to call for currently pending expectation.
* Note, that using this method overrides declarations made
* using $returns() and $throws() methods.
* @param {Function} func The function to call.
* @return {!goog.testing.Mock} This mock object.
*/
goog.testing.Mock.prototype.$does = function(func) {
'use strict';
this.$pendingExpectation.toDo = func;
return this;
};
/**
* Allows the expectation to be called 0 or 1 times.
* @return {!goog.testing.Mock} This mock object.
*/
goog.testing.Mock.prototype.$atMostOnce = function() {
'use strict';
this.$pendingExpectation.minCalls = 0;
this.$pendingExpectation.maxCalls = 1;
return this;
};
/**
* Allows the expectation to be called any number of times, as long as it's
* called once.
* @return {!goog.testing.Mock} This mock object.
*/
goog.testing.Mock.prototype.$atLeastOnce = function() {
'use strict';
this.$pendingExpectation.maxCalls = Infinity;
return this;
};
/**
* Allows the expectation to be called exactly once.
* @return {!goog.testing.Mock} This mock object.
*/
goog.testing.Mock.prototype.$once = function() {
'use strict';
this.$pendingExpectation.minCalls = 1;
this.$pendingExpectation.maxCalls = 1;
return this;
};
/**
* Disallows the expectation from being called.
* @return {!goog.testing.Mock} This mock object.
*/
goog.testing.Mock.prototype.$never = function() {
'use strict';
this.$pendingExpectation.minCalls = 0;
this.$pendingExpectation.maxCalls = 0;
return this;
};
/**
* Allows the expectation to be called any number of times.
* @return {!goog.testing.Mock} This mock object.
*/
goog.testing.Mock.prototype.$anyTimes = function() {
'use strict';
this.$pendingExpectation.minCalls = 0;
this.$pendingExpectation.maxCalls = Infinity;
return this;
};
/**
* Specifies the number of times the expectation should be called.
* @param {number} times The number of times this method will be called.
* @return {!goog.testing.Mock} This mock object.
*/
goog.testing.Mock.prototype.$times = function(times) {
'use strict';
this.$pendingExpectation.minCalls = times;
this.$pendingExpectation.maxCalls = times;
return this;
};
/**
* Switches from recording to replay mode.
* @override
*/
goog.testing.Mock.prototype.$replay = function() {
'use strict';
this.$recording_ = false;
};
/**
* Resets the state of this mock object. This clears all pending expectations
* without verifying, and puts the mock in recording mode.
* @override
*/
goog.testing.Mock.prototype.$reset = function() {
'use strict';
this.$recording_ = true;
this.$threwException_ = null;
delete this.$pendingExpectation;
if (this.waitingForExpectations) {
this.waitingForExpectations = null;
}
};
/**
* Throws an exception and records that an exception was thrown.
* @param {string} comment A short comment about the exception.
* @param {?string=} opt_message A longer message about the exception.
* @throws {Object} JsUnitException object.
* @protected
*/
goog.testing.Mock.prototype.$throwException = function(comment, opt_message) {
'use strict';
this.$recordAndThrow(new goog.testing.JsUnitException(comment, opt_message));
};
/**
* Throws an exception and records that an exception was thrown.
* @param {Object} ex Exception.
* @param {boolean=} rethrow True if this exception has already been thrown. If
* so, we should not report it to TestCase (since it was already reported at
* the original throw). This is necessary to avoid logging it twice, because
* assertThrowsJsUnitException only removes one record.
* @throws {Object} #ex.
* @protected
*/
goog.testing.Mock.prototype.$recordAndThrow = function(ex, rethrow) {
'use strict';
if (this.waitingForExpectations) {
this.waitingForExpectations.resolve();
}
if (this.$recording_) {
ex = new goog.testing.JsUnitException(
'Threw an exception while in record mode, did you $replay?',
ex.toString());
}
// If it's an assert exception, record it.
if (ex['isJsUnitException']) {
if (!this.$threwException_) {
// Only remember first exception thrown.
this.$threwException_ = ex;
}
// Don't fail if JSUnit isn't loaded. Instead, the test can catch the error
// normally. Other test frameworks won't get automatic failures if assertion
// errors are swallowed.
var getTestCase =
goog.getObjectByName('goog.testing.TestCase.getActiveTestCase');
var testCase = getTestCase && getTestCase();
if (testCase && !rethrow) {
testCase.raiseAssertionException(ex);
}
}
throw ex;
};
/** @override */
goog.testing.Mock.prototype.$waitAndVerify = function() {
'use strict';
goog.asserts.assert(
!this.$recording_,
'$waitAndVerify should be called after recording calls.');
this.waitingForExpectations = goog.Promise.withResolver();
var verify = goog.bind(this.$verify, this);
return this.waitingForExpectations.promise.then(function() {
'use strict';
return new goog.Promise(function(resolve, reject) {
'use strict';
setTimeout(function() {
'use strict';
try {
verify();
} catch (e) {
reject(e);
}
resolve();
}, 0);
});
});
};
/**
* Verify that all of the expectations were met. Should be overridden by
* subclasses.
* @override
*/
goog.testing.Mock.prototype.$verify = function() {
'use strict';
if (this.$threwException_) {
throw this.$threwException_;
}
};
/**
* Verifies that a method call matches an expectation.
* @param {goog.testing.MockExpectation} expectation The expectation to check.
* @param {string} name The name of the called method.
* @param {Array<*>?} args The arguments passed to the mock.
* @return {boolean} Whether the call matches the expectation.
*/
goog.testing.Mock.prototype.$verifyCall = function(expectation, name, args) {
'use strict';
if (expectation.name != name) {
return false;
}
var verifierFn =
this.$argumentListVerifiers_.hasOwnProperty(expectation.name) ?
this.$argumentListVerifiers_[expectation.name] :
goog.testing.mockmatchers.flexibleArrayMatcher;
return verifierFn(expectation.argumentList, args, expectation);
};
/**
* Render the provided argument array to a string to help
* clients with debugging tests.
* @param {Array<*>?} args The arguments passed to the mock.
* @return {string} Human-readable string.
*/
goog.testing.Mock.prototype.$argumentsAsString = function(args) {
'use strict';
var retVal = [];
for (var i = 0; i < args.length; i++) {
try {
retVal.push(goog.typeOf(args[i]));
} catch (e) {
retVal.push('[unknown]');
}
}
return '(' + retVal.join(', ') + ')';
};
/**
* Throw an exception based on an incorrect method call.
* @param {string} name Name of method called.
* @param {Array<*>?} args Arguments passed to the mock.
* @param {goog.testing.MockExpectation=} opt_expectation Expected next call,
* if any.
*/
goog.testing.Mock.prototype.$throwCallException = function(
name, args, opt_expectation) {
'use strict';
var errorStringBuffer = [];
var actualArgsString = this.$argumentsAsString(args);
var expectedArgsString = opt_expectation ?
this.$argumentsAsString(opt_expectation.argumentList) :
'';
if (opt_expectation && opt_expectation.name == name) {
errorStringBuffer.push(
'Bad arguments to ', name, '().\n', 'Actual: ', actualArgsString, '\n',
'Expected: ', expectedArgsString, '\n',
opt_expectation.getErrorMessage());
} else {
errorStringBuffer.push(
'Unexpected call to ', name, actualArgsString, '.',
'\nDid you forget to $replay?');
if (opt_expectation) {
errorStringBuffer.push(
'\nNext expected call was to ', opt_expectation.name,
expectedArgsString);
}
}
this.$throwException(errorStringBuffer.join(''));
};
Codebase Browser
chromium