1
// Copyright 2016 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 Provides an interface that defines how users can extend the
17
 * {@code goog.labs.mock} mocking framework with custom verification.
18
 *
19
 * In addition to the interface definition, it contains several static
20
 * factories for creating common implementations of the interface.
21
 */
22
goog.provide('goog.labs.mock.verification');
23
goog.provide('goog.labs.mock.verification.VerificationMode');
24

25

26

27
/**
28
 * A mode which defines how mock invocations should be verified.
29
 * When an instance of {@code VerificationMode} is passed to
30
 * {@code goog.labs.mock.verify}, then that instances's {@code #verify}
31
 * method will be used to verify the invocation.
32
 *
33
 * If {@code #verify} returns false, then the test will fail and the
34
 * description returned from {@code #describe} will be shown in the
35
 * test failure message.  Sample usage:
36
 *
37
 * goog.module('my.package.MyClassTest');
38
 * goog.setTestOnly('my.package.MyClassTest');
39
 *
40
 * var testSuite = goog.require('goog.testing.testSuite');
41
 * var verification = goog.require('goog.labs.mock.verification');
42
 *
43
 * var times = verification.times;
44
 *
45
 * testSuite({
46
 *   setUp: function() {
47
 *     // Code creating instances of MyClass and mockObj.
48
 *   },
49
 *
50
 *   testMyMethod_shouldDoSomething: function() {
51
 *     myClassInstance.myMethod();
52
 *
53
 *     goog.labs.mock.verify(mockObj, times(1));
54
 *   }
55
 * });
56
 *
57
 * For an example implementation, see {@code TimesVerificationMode_}.
58
 *
59
 * @interface
60
 */
61
goog.labs.mock.verification.VerificationMode = function() {};
62

63

64
/**
65
 * Returns true if the recorded number of invocations,
66
 * {@code actualNumberOfInvocations}, meets the expectations of this mode.
67
 *
68
 * TODO(user): Have this take in an object which contains the complete
69
 * call record in order to allow more interesting verifications.
70
 *
71
 * @param {number} actualNumberOfInvocations
72
 * @return {boolean}
73
 */
74
goog.labs.mock.verification.VerificationMode.prototype.verify =
75
    goog.abstractMethod;
76

77

78
/**
79
 * Returns a description of what this VerificationMode expected.
80
 *
81
 * @return {string}
82
 */
83
goog.labs.mock.verification.VerificationMode.prototype.describe =
84
    goog.abstractMethod;
85

86

87
/**
88
 * Returns a {@code VerificationMode} which verifies a method was called
89
 * exactly {@code expectedNumberOfInvocations} times.
90
 *
91
 * @param {number} expectedNumberOfInvocations
92
 * @return {!goog.labs.mock.verification.VerificationMode}
93
*/
94
goog.labs.mock.verification.times = function(expectedNumberOfInvocations) {
95
  return new goog.labs.mock.verification.TimesVerificationMode_(
96
      expectedNumberOfInvocations);
97
};
98

99

100
/**
101
 * Returns a {@code VerificationMode} which verifies a method was called at
102
 * least {@code minimumNumberOfInvocations} times.
103
 *
104
 * @param {number} minimumNumberOfInvocations
105
 * @return {!goog.labs.mock.verification.VerificationMode}
106
 */
107
goog.labs.mock.verification.atLeast = function(minimumNumberOfInvocations) {
108
  return new goog.labs.mock.verification.AtLeastVerificationMode_(
109
      minimumNumberOfInvocations);
110
};
111

112

113
/**
114
 * Returns a {@code VerificationMode} which verifies a method was called at
115
 * most {@code maxNumberOfInvocations} times.
116
 *
117
 * @param {number} maxNumberOfInvocations
118
 * @return {!goog.labs.mock.verification.VerificationMode}
119
 */
120
goog.labs.mock.verification.atMost = function(maxNumberOfInvocations) {
121
  return new goog.labs.mock.verification.AtMostVerificationMode_(
122
      maxNumberOfInvocations);
123
};
124

125

126
/**
127
 * Returns a {@code VerificationMode} which verifies a method was never
128
 * called. An alias for {@code VerificatonMode.times(0)}.
129
 *
130
 * @return {!goog.labs.mock.verification.VerificationMode}
131
 */
132
goog.labs.mock.verification.never = function() {
133
  return goog.labs.mock.verification.times(0);
134
};
135

136

137
/**
138
 * A {@code VerificationMode} which verifies a method was called
139
 * exactly {@code expectedNumberOfInvocations} times.
140
 *
141
 * @private @implements {goog.labs.mock.verification.VerificationMode}
142
*/
143
goog.labs.mock.verification.TimesVerificationMode_ = goog.defineClass(null, {
144
  /**
145
   * @param {number} expectedNumberOfInvocations
146
   * @constructor
147
   */
148
  constructor: function(expectedNumberOfInvocations) {
149
    /** @private */
150
    this.expectedNumberOfInvocations_ = expectedNumberOfInvocations;
151
  },
152

153
  /** @override */
154
  verify: function(actualNumberOfInvocations) {
155
    return actualNumberOfInvocations == this.expectedNumberOfInvocations_;
156
  },
157

158
  /** @override */
159
  describe: function() { return this.expectedNumberOfInvocations_ + ' times'; }
160
});
161

162

163
/**
164
 * A {@code VerificationMode} which verifies a method was called at
165
 * least {@code minimumNumberOfInvocations} times.
166
 *
167
 * @private @implements {goog.labs.mock.verification.VerificationMode}
168
 */
169
goog.labs.mock.verification.AtLeastVerificationMode_ = goog.defineClass(null, {
170
  /**
171
   * @param {number} minimumNumberOfInvocations
172
   * @constructor
173
   */
174
  constructor: function(minimumNumberOfInvocations) {
175
    /** @private */
176
    this.minimumNumberOfInvocations_ = minimumNumberOfInvocations;
177
  },
178

179
  /** @override */
180
  verify: function(actualNumberOfInvocations) {
181
    return actualNumberOfInvocations >= this.minimumNumberOfInvocations_;
182
  },
183

184
  /** @override */
185
  describe: function() {
186
    return 'at least ' + this.minimumNumberOfInvocations_ + ' times';
187
  }
188
});
189

190

191
/**
192
 * A {@code VerificationMode} which verifies a method was called at
193
 * most {@code maxNumberOfInvocations} times.
194
 *
195
 * @private @implements {goog.labs.mock.verification.VerificationMode}
196
 */
197
goog.labs.mock.verification.AtMostVerificationMode_ = goog.defineClass(null, {
198
  /**
199
   * @param {number} maxNumberOfInvocations
200
   * @constructor
201
   */
202
  constructor: function(maxNumberOfInvocations) {
203
    /** @private */
204
    this.maxNumberOfInvocations_ = maxNumberOfInvocations;
205
  },
206

207
  /** @override */
208
  verify: function(actualNumberOfInvocations) {
209
    return actualNumberOfInvocations <= this.maxNumberOfInvocations_;
210
  },
211

212
  /** @override */
213
  describe: function() {
214
    return 'at most ' + this.maxNumberOfInvocations_ + ' times';
215
  }
216
});
217

218