lib/goog/testing/functionmock.js

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 Enable mocking of functions not attached to objects
17 * whether they be global / top-level or anonymous methods / closures.
18 *
19 * See the unit tests for usage.
20 *
21 */
22
23goog.provide('goog.testing');
24goog.provide('goog.testing.FunctionMock');
25goog.provide('goog.testing.GlobalFunctionMock');
26goog.provide('goog.testing.MethodMock');
27
28goog.require('goog.object');
29goog.require('goog.testing.LooseMock');
30goog.require('goog.testing.Mock');
31goog.require('goog.testing.MockInterface');
32goog.require('goog.testing.PropertyReplacer');
33goog.require('goog.testing.StrictMock');
34
35
36/**
37 * Class used to mock a function. Useful for mocking closures and anonymous
38 * callbacks etc. Creates a function object that extends goog.testing.Mock.
39 * @param {string=} opt_functionName The optional name of the function to mock.
40 * Set to '[anonymous mocked function]' if not passed in.
41 * @param {number=} opt_strictness One of goog.testing.Mock.LOOSE or
42 * goog.testing.Mock.STRICT. The default is STRICT.
43 * @return {goog.testing.MockInterface} The mocked function.
44 * @suppress {missingProperties} Mocks do not fit in the type system well.
45 */
46goog.testing.FunctionMock = function(opt_functionName, opt_strictness) {
47 var fn = function() {
48 var args = Array.prototype.slice.call(arguments);
49 args.splice(0, 0, opt_functionName || '[anonymous mocked function]');
50 return fn.$mockMethod.apply(fn, args);
51 };
52 var base = opt_strictness === goog.testing.Mock.LOOSE ?
53 goog.testing.LooseMock : goog.testing.StrictMock;
54 goog.object.extend(fn, new base({}));
55
56 return /** @type {goog.testing.MockInterface} */ (fn);
57};
58
59
60/**
61 * Mocks an existing function. Creates a goog.testing.FunctionMock
62 * and registers it in the given scope with the name specified by functionName.
63 * @param {Object} scope The scope of the method to be mocked out.
64 * @param {string} functionName The name of the function we're going to mock.
65 * @param {number=} opt_strictness One of goog.testing.Mock.LOOSE or
66 * goog.testing.Mock.STRICT. The default is STRICT.
67 * @return {!goog.testing.MockInterface} The mocked method.
68 */
69goog.testing.MethodMock = function(scope, functionName, opt_strictness) {
70 if (!(functionName in scope)) {
71 throw Error(functionName + ' is not a property of the given scope.');
72 }
73
74 var fn = goog.testing.FunctionMock(functionName, opt_strictness);
75
76 fn.$propertyReplacer_ = new goog.testing.PropertyReplacer();
77 fn.$propertyReplacer_.set(scope, functionName, fn);
78 fn.$tearDown = goog.testing.MethodMock.$tearDown;
79
80 return fn;
81};
82
83
84/**
85 * Resets the global function that we mocked back to its original state.
86 * @this {goog.testing.MockInterface}
87 */
88goog.testing.MethodMock.$tearDown = function() {
89 this.$propertyReplacer_.reset();
90};
91
92
93/**
94 * Mocks a global / top-level function. Creates a goog.testing.MethodMock
95 * in the global scope with the name specified by functionName.
96 * @param {string} functionName The name of the function we're going to mock.
97 * @param {number=} opt_strictness One of goog.testing.Mock.LOOSE or
98 * goog.testing.Mock.STRICT. The default is STRICT.
99 * @return {!goog.testing.MockInterface} The mocked global function.
100 */
101goog.testing.GlobalFunctionMock = function(functionName, opt_strictness) {
102 return goog.testing.MethodMock(goog.global, functionName, opt_strictness);
103};
104
105
106/**
107 * Convenience method for creating a mock for a function.
108 * @param {string=} opt_functionName The optional name of the function to mock
109 * set to '[anonymous mocked function]' if not passed in.
110 * @param {number=} opt_strictness One of goog.testing.Mock.LOOSE or
111 * goog.testing.Mock.STRICT. The default is STRICT.
112 * @return {goog.testing.MockInterface} The mocked function.
113 */
114goog.testing.createFunctionMock = function(opt_functionName, opt_strictness) {
115 return goog.testing.FunctionMock(opt_functionName, opt_strictness);
116};
117
118
119/**
120 * Convenience method for creating a mock for a method.
121 * @param {Object} scope The scope of the method to be mocked out.
122 * @param {string} functionName The name of the function we're going to mock.
123 * @param {number=} opt_strictness One of goog.testing.Mock.LOOSE or
124 * goog.testing.Mock.STRICT. The default is STRICT.
125 * @return {!goog.testing.MockInterface} The mocked global function.
126 */
127goog.testing.createMethodMock = function(scope, functionName, opt_strictness) {
128 return goog.testing.MethodMock(scope, functionName, opt_strictness);
129};
130
131
132/**
133 * Convenience method for creating a mock for a constructor. Copies class
134 * members to the mock.
135 *
136 * <p>When mocking a constructor to return a mocked instance, remember to create
137 * the instance mock before mocking the constructor. If you mock the constructor
138 * first, then the mock framework will be unable to examine the prototype chain
139 * when creating the mock instance.
140 * @param {Object} scope The scope of the constructor to be mocked out.
141 * @param {string} constructorName The name of the constructor we're going to
142 * mock.
143 * @param {number=} opt_strictness One of goog.testing.Mock.LOOSE or
144 * goog.testing.Mock.STRICT. The default is STRICT.
145 * @return {!goog.testing.MockInterface} The mocked constructor.
146 */
147goog.testing.createConstructorMock = function(scope, constructorName,
148 opt_strictness) {
149 var realConstructor = scope[constructorName];
150 var constructorMock = goog.testing.MethodMock(scope, constructorName,
151 opt_strictness);
152
153 // Copy class members from the real constructor to the mock. Do not copy
154 // the closure superClass_ property (see goog.inherits), the built-in
155 // prototype property, or properties added to Function.prototype
156 // (see goog.MODIFY_FUNCTION_PROTOTYPES in closure/base.js).
157 for (var property in realConstructor) {
158 if (property != 'superClass_' &&
159 property != 'prototype' &&
160 realConstructor.hasOwnProperty(property)) {
161 constructorMock[property] = realConstructor[property];
162 }
163 }
164 return constructorMock;
165};
166
167
168/**
169 * Convenience method for creating a mocks for a global / top-level function.
170 * @param {string} functionName The name of the function we're going to mock.
171 * @param {number=} opt_strictness One of goog.testing.Mock.LOOSE or
172 * goog.testing.Mock.STRICT. The default is STRICT.
173 * @return {goog.testing.MockInterface} The mocked global function.
174 */
175goog.testing.createGlobalFunctionMock = function(functionName, opt_strictness) {
176 return goog.testing.GlobalFunctionMock(functionName, opt_strictness);
177};