1
// Licensed to the Software Freedom Conservancy (SFC) under one
2
// or more contributor license agreements.  See the NOTICE file
3
// distributed with this work for additional information
4
// regarding copyright ownership.  The SFC licenses this file
5
// to you under the Apache License, Version 2.0 (the
6
// "License"); you may not use this file except in compliance
7
// with the License.  You may obtain a copy of the License at
8
//
9
//   http://www.apache.org/licenses/LICENSE-2.0
10
//
11
// Unless required by applicable law or agreed to in writing,
12
// software distributed under the License is distributed on an
13
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14
// KIND, either express or implied.  See the License for the
15
// specific language governing permissions and limitations
16
// under the License.
17

18
goog.provide('webdriver.test.testutil');
19
goog.provide('webdriver.test.testutil.StubError');
20

21
goog.require('goog.array');
22
goog.require('goog.debug.Error');
23
goog.require('goog.string');
24
goog.require('goog.testing.recordFunction');
25
goog.require('webdriver.stacktrace');
26

27

28

29
/**
30
 * A custom error used for testing.
31
 * @param {string=} opt_msg The error message to use.
32
 * @constructor
33
 * @extends {goog.debug.Error}
34
 * @final
35
 */
36
webdriver.test.testutil.StubError = function(opt_msg) {
37
  webdriver.test.testutil.StubError.base(this, 'constructor', opt_msg);
38
};
39
goog.inherits(webdriver.test.testutil.StubError, goog.debug.Error);
40

41

42
/** @override */
43
webdriver.test.testutil.StubError.prototype.name = 'StubError';
44

45

46
/** @type {Array.<!string>} */
47
webdriver.test.testutil.messages = [];
48

49
webdriver.test.testutil.getStackTrace = function() {
50
  return webdriver.stacktrace.get();
51
};
52

53
webdriver.test.testutil.throwStubError = function() {
54
  throw new webdriver.test.testutil.StubError;
55
};
56

57
webdriver.test.testutil.assertIsStubError = function(error) {
58
  assertTrue(error + ' is not an instanceof StubError',
59
      error instanceof webdriver.test.testutil.StubError);
60
};
61

62

63
/**
64
 * Asserts the contents of the {@link webdriver.test.testutil.messages} array
65
 * are as expected.
66
 * @param {...*} var_args The expected contents.
67
 */
68
webdriver.test.testutil.assertMessages = function(var_args) {
69
  var args = Array.prototype.slice.call(arguments, 0);
70
  assertArrayEquals(args, webdriver.test.testutil.messages);
71
};
72

73

74
/**
75
 * Wraps a call to {@link webdriver.test.testutil.assertMessages} so it can
76
 * be passed as a callback.
77
 * @param {...*} var_args The expected contents.
78
 * @return {!Function} The wrapped function.
79
 */
80
webdriver.test.testutil.assertingMessages = function(var_args) {
81
  var args = goog.array.slice(arguments, 0);
82
  return function() {
83
    return webdriver.test.testutil.assertMessages.apply(null, args);
84
  };
85
};
86

87

88
/**
89
 * Asserts an object is a promise.
90
 * @param {*} obj The object to check.
91
 */
92
webdriver.test.testutil.assertIsPromise = function(obj) {
93
  assertTrue('Value is not a promise: ' + goog.typeOf(obj),
94
      webdriver.promise.isPromise(obj));
95
};
96

97

98
/**
99
 * Asserts an object is not a promise.
100
 * @param {*} obj The object to check.
101
 */
102
webdriver.test.testutil.assertNotPromise = function(obj) {
103
  assertFalse(webdriver.promise.isPromise(obj));
104
};
105

106
/**
107
 * Wraps a function. The wrapped function will have several utility functions:
108
 * <ul>
109
 * <li>assertCalled: Asserts that the function was called.
110
 * <li>assertNotCalled: Asserts that the function was not called.
111
 * </ul>
112
 * @param {Function=} opt_fn The function to wrap; defaults to
113
 *     goog.nullFunction.
114
 * @return {!Function} The wrapped function.
115
 * @see goog.testing.recordFunction
116
 */
117
webdriver.test.testutil.callbackHelper = function(opt_fn) {
118
  var callback = goog.testing.recordFunction(opt_fn);
119

120
  callback.getExpectedCallCountMessage = function(n, opt_prefix, opt_noJoin) {
121
    var message = [];
122
    if (opt_prefix) message.push(opt_prefix);
123

124
    var calls = callback.getCalls();
125
    message.push(
126
        'Expected to be called ' + n + ' times.',
127
        '  was called ' + calls.length + ' times:');
128
    goog.array.forEach(calls, function(call) {
129
      var e = call.getError();
130
      if (e) {
131
        throw e;
132
      }
133
    });
134
    return opt_noJoin ? message : message.join('\n');
135
  };
136

137
  callback.assertCalled = function(opt_message) {
138
    assertEquals(callback.getExpectedCallCountMessage(1, opt_message),
139
        1, callback.getCallCount());
140
  };
141

142
  callback.assertNotCalled = function(opt_message) {
143
    assertEquals(callback.getExpectedCallCountMessage(0, opt_message),
144
        0, callback.getCallCount());
145
  };
146

147
  return callback;
148
};
149

150

151
/**
152
 * Creates a utility for managing a pair of callbacks, capable of asserting only
153
 * one of the pair was ever called.
154
 *
155
 * @param {Function=} opt_callback The callback to manage.
156
 * @param {Function=} opt_errback The errback to manage.
157
 */
158
webdriver.test.testutil.callbackPair = function(opt_callback, opt_errback) {
159
  var pair = {
160
    callback: webdriver.test.testutil.callbackHelper(opt_callback),
161
    errback: webdriver.test.testutil.callbackHelper(opt_errback)
162
  };
163

164
  /** @param {string=} opt_message Optional failure message. */
165
  pair.assertEither = function(opt_message) {
166
    if (!pair.callback.getCallCount() &&
167
        !pair.errback.getCallCount()) {
168
      var message = ['Neither callback nor errback has been called'];
169
      if (opt_message) goog.array.insertAt(message, opt_message);
170
      fail(message.join('\n'));
171
    }
172
  };
173

174
  /** @param {string=} opt_message Optional failure message. */
175
  pair.assertNeither = function(opt_message) {
176
    var message = (opt_message || '') + 'Did not expect callback or errback';
177
    pair.callback.assertNotCalled(message);
178
    pair.errback.assertNotCalled(message);
179
  };
180

181
  /** @param {string=} opt_message Optional failure message. */
182
  pair.assertCallback = function(opt_message) {
183
    var message = opt_message ? (opt_message + ': ') : '';
184
    pair.errback.assertNotCalled(message + 'Expected callback, not errback');
185
    pair.callback.assertCalled(message + 'Callback not called');
186
  };
187

188
  /** @param {string=} opt_message Optional failure message. */
189
  pair.assertErrback = function(opt_message) {
190
    var message = opt_message ? (opt_message + ': ') : '';
191
    pair.callback.assertNotCalled(message + 'Expected errback, not callback');
192
    pair.errback.assertCalled(message + 'Errback not called');
193
  };
194

195
  pair.reset = function() {
196
    pair.callback.reset();
197
    pair.errback.reset();
198
  };
199

200
  return pair;
201
};
202

203

204
webdriver.test.testutil.assertObjectEquals = function(expected, actual) {
205
  assertObjectEquals(
206
      'Expected: ' + JSON.stringify(expected) + '\n' +
207
      'Actual:   ' + JSON.stringify(actual),
208
      expected, actual);
209
};
210

211