| 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 Performance timer. |
| 17 |
* |
| 18 |
* {@see goog.testing.benchmark} for an easy way to use this functionality. |
| 19 |
* |
| 20 |
* @author [email protected] (Attila Bodis) |
| 21 |
*/ |
| 22 |
|
| 23 |
goog.setTestOnly('goog.testing.PerformanceTimer'); |
| 24 |
goog.provide('goog.testing.PerformanceTimer'); |
| 25 |
goog.provide('goog.testing.PerformanceTimer.Task'); |
| 26 |
|
| 27 |
goog.require('goog.array'); |
| 28 |
goog.require('goog.async.Deferred'); |
| 29 |
goog.require('goog.math'); |
| 30 |
|
| 31 |
|
| 32 |
|
| 33 |
/** |
| 34 |
* Creates a performance timer that runs test functions a number of times to |
| 35 |
* generate timing samples, and provides performance statistics (minimum, |
| 36 |
* maximum, average, and standard deviation). |
| 37 |
* @param {number=} opt_numSamples Number of times to run the test function; |
| 38 |
* defaults to 10. |
| 39 |
* @param {number=} opt_timeoutInterval Number of milliseconds after which the |
| 40 |
* test is to be aborted; defaults to 5 seconds (5,000ms). |
| 41 |
* @constructor |
| 42 |
*/ |
| 43 |
goog.testing.PerformanceTimer = function(opt_numSamples, opt_timeoutInterval) { |
| 44 |
/** |
| 45 |
* Number of times the test function is to be run; defaults to 10. |
| 46 |
* @private {number} |
| 47 |
*/ |
| 48 |
this.numSamples_ = opt_numSamples || 10; |
| 49 |
|
| 50 |
/** |
| 51 |
* Number of milliseconds after which the test is to be aborted; defaults to |
| 52 |
* 5,000ms. |
| 53 |
* @private {number} |
| 54 |
*/ |
| 55 |
this.timeoutInterval_ = opt_timeoutInterval || 5000; |
| 56 |
|
| 57 |
/** |
| 58 |
* Whether to discard outliers (i.e. the smallest and the largest values) |
| 59 |
* from the sample set before computing statistics. Defaults to false. |
| 60 |
* @private {boolean} |
| 61 |
*/ |
| 62 |
this.discardOutliers_ = false; |
| 63 |
}; |
| 64 |
|
| 65 |
|
| 66 |
/** |
| 67 |
* A function whose subsequent calls differ in milliseconds. Used to calculate |
| 68 |
* the start and stop checkpoint times for runs. Note that high performance |
| 69 |
* timers do not necessarily return the current time in milliseconds. |
| 70 |
* @return {number} |
| 71 |
* @private |
| 72 |
*/ |
| 73 |
goog.testing.PerformanceTimer.now_ = function() { |
| 74 |
// goog.now is used in DEBUG mode to make the class easier to test. |
| 75 |
return !goog.DEBUG && window.performance && window.performance.now ? |
| 76 |
window.performance.now() : |
| 77 |
goog.now(); |
| 78 |
}; |
| 79 |
|
| 80 |
|
| 81 |
/** |
| 82 |
* @return {number} The number of times the test function will be run. |
| 83 |
*/ |
| 84 |
goog.testing.PerformanceTimer.prototype.getNumSamples = function() { |
| 85 |
return this.numSamples_; |
| 86 |
}; |
| 87 |
|
| 88 |
|
| 89 |
/** |
| 90 |
* Sets the number of times the test function will be run. |
| 91 |
* @param {number} numSamples Number of times to run the test function. |
| 92 |
*/ |
| 93 |
goog.testing.PerformanceTimer.prototype.setNumSamples = function(numSamples) { |
| 94 |
this.numSamples_ = numSamples; |
| 95 |
}; |
| 96 |
|
| 97 |
|
| 98 |
/** |
| 99 |
* @return {number} The number of milliseconds after which the test times out. |
| 100 |
*/ |
| 101 |
goog.testing.PerformanceTimer.prototype.getTimeoutInterval = function() { |
| 102 |
return this.timeoutInterval_; |
| 103 |
}; |
| 104 |
|
| 105 |
|
| 106 |
/** |
| 107 |
* Sets the number of milliseconds after which the test times out. |
| 108 |
* @param {number} timeoutInterval Timeout interval in ms. |
| 109 |
*/ |
| 110 |
goog.testing.PerformanceTimer.prototype.setTimeoutInterval = function( |
| 111 |
timeoutInterval) { |
| 112 |
this.timeoutInterval_ = timeoutInterval; |
| 113 |
}; |
| 114 |
|
| 115 |
|
| 116 |
/** |
| 117 |
* Sets whether to ignore the smallest and the largest values when computing |
| 118 |
* stats. |
| 119 |
* @param {boolean} discard Whether to discard outlier values. |
| 120 |
*/ |
| 121 |
goog.testing.PerformanceTimer.prototype.setDiscardOutliers = function(discard) { |
| 122 |
this.discardOutliers_ = discard; |
| 123 |
}; |
| 124 |
|
| 125 |
|
| 126 |
/** |
| 127 |
* @return {boolean} Whether outlier values are discarded prior to computing |
| 128 |
* stats. |
| 129 |
*/ |
| 130 |
goog.testing.PerformanceTimer.prototype.isDiscardOutliers = function() { |
| 131 |
return this.discardOutliers_; |
| 132 |
}; |
| 133 |
|
| 134 |
|
| 135 |
/** |
| 136 |
* Executes the test function the required number of times (or until the |
| 137 |
* test run exceeds the timeout interval, whichever comes first). Returns |
| 138 |
* an object containing the following: |
| 139 |
* <pre> |
| 140 |
* { |
| 141 |
* 'average': average execution time (ms) |
| 142 |
* 'count': number of executions (may be fewer than expected due to timeout) |
| 143 |
* 'maximum': longest execution time (ms) |
| 144 |
* 'minimum': shortest execution time (ms) |
| 145 |
* 'standardDeviation': sample standard deviation (ms) |
| 146 |
* 'total': total execution time (ms) |
| 147 |
* } |
| 148 |
* </pre> |
| 149 |
* |
| 150 |
* @param {Function} testFn Test function whose performance is to |
| 151 |
* be measured. |
| 152 |
* @return {!Object} Object containing performance stats. |
| 153 |
*/ |
| 154 |
goog.testing.PerformanceTimer.prototype.run = function(testFn) { |
| 155 |
return this.runTask( |
| 156 |
new goog.testing.PerformanceTimer.Task( |
| 157 |
/** @type {goog.testing.PerformanceTimer.TestFunction} */ (testFn))); |
| 158 |
}; |
| 159 |
|
| 160 |
|
| 161 |
/** |
| 162 |
* Executes the test function of the specified task as described in |
| 163 |
* {@code run}. In addition, if specified, the set up and tear down functions of |
| 164 |
* the task are invoked before and after each invocation of the test function. |
| 165 |
* @see goog.testing.PerformanceTimer#run |
| 166 |
* @param {goog.testing.PerformanceTimer.Task} task A task describing the test |
| 167 |
* function to invoke. |
| 168 |
* @return {!Object} Object containing performance stats. |
| 169 |
*/ |
| 170 |
goog.testing.PerformanceTimer.prototype.runTask = function(task) { |
| 171 |
var samples = []; |
| 172 |
var testStart = goog.testing.PerformanceTimer.now_(); |
| 173 |
var totalRunTime = 0; |
| 174 |
|
| 175 |
var testFn = task.getTest(); |
| 176 |
var setUpFn = task.getSetUp(); |
| 177 |
var tearDownFn = task.getTearDown(); |
| 178 |
|
| 179 |
for (var i = 0; i < this.numSamples_ && totalRunTime <= this.timeoutInterval_; |
| 180 |
i++) { |
| 181 |
setUpFn(); |
| 182 |
var sampleStart = goog.testing.PerformanceTimer.now_(); |
| 183 |
testFn(); |
| 184 |
var sampleEnd = goog.testing.PerformanceTimer.now_(); |
| 185 |
tearDownFn(); |
| 186 |
samples[i] = sampleEnd - sampleStart; |
| 187 |
totalRunTime = sampleEnd - testStart; |
| 188 |
} |
| 189 |
|
| 190 |
return this.finishTask_(samples); |
| 191 |
}; |
| 192 |
|
| 193 |
|
| 194 |
/** |
| 195 |
* Finishes the run of a task by creating a result object from samples, in the |
| 196 |
* format described in {@code run}. |
| 197 |
* @see goog.testing.PerformanceTimer#run |
| 198 |
* @param {!Array<number>} samples The samples to analyze. |
| 199 |
* @return {!Object} Object containing performance stats. |
| 200 |
* @private |
| 201 |
*/ |
| 202 |
goog.testing.PerformanceTimer.prototype.finishTask_ = function(samples) { |
| 203 |
if (this.discardOutliers_ && samples.length > 2) { |
| 204 |
goog.array.remove(samples, Math.min.apply(null, samples)); |
| 205 |
goog.array.remove(samples, Math.max.apply(null, samples)); |
| 206 |
} |
| 207 |
|
| 208 |
return goog.testing.PerformanceTimer.createResults(samples); |
| 209 |
}; |
| 210 |
|
| 211 |
|
| 212 |
/** |
| 213 |
* Executes the test function of the specified task asynchronously. The test |
| 214 |
* function is expected to take a callback as input and has to call it to signal |
| 215 |
* that it's done. In addition, if specified, the setUp and tearDown functions |
| 216 |
* of the task are invoked before and after each invocation of the test |
| 217 |
* function. Note that setUp/tearDown functions take a callback as input and |
| 218 |
* must call this callback when they are done. |
| 219 |
* @see goog.testing.PerformanceTimer#run |
| 220 |
* @param {goog.testing.PerformanceTimer.Task} task A task describing the test |
| 221 |
* function to invoke. |
| 222 |
* @return {!goog.async.Deferred} The deferred result, eventually an object |
| 223 |
* containing performance stats. |
| 224 |
*/ |
| 225 |
goog.testing.PerformanceTimer.prototype.runAsyncTask = function(task) { |
| 226 |
var samples = []; |
| 227 |
var testStart = goog.testing.PerformanceTimer.now_(); |
| 228 |
|
| 229 |
var testFn = task.getTest(); |
| 230 |
var setUpFn = task.getSetUp(); |
| 231 |
var tearDownFn = task.getTearDown(); |
| 232 |
|
| 233 |
// Note that this uses a separate code path from runTask() because |
| 234 |
// implementing runTask() in terms of runAsyncTask() could easily cause |
| 235 |
// a stack overflow if there are many iterations. |
| 236 |
var result = new goog.async.Deferred(); |
| 237 |
this.runAsyncTaskSample_( |
| 238 |
testFn, setUpFn, tearDownFn, result, samples, testStart); |
| 239 |
return result; |
| 240 |
}; |
| 241 |
|
| 242 |
|
| 243 |
/** |
| 244 |
* Runs a task once, waits for the test function to complete asynchronously |
| 245 |
* and starts another run if not enough samples have been collected. Otherwise |
| 246 |
* finishes this task. |
| 247 |
* @param {goog.testing.PerformanceTimer.TestFunction} testFn The test function. |
| 248 |
* @param {goog.testing.PerformanceTimer.TestFunction} setUpFn The set up |
| 249 |
* function that will be called once before the test function is run. |
| 250 |
* @param {goog.testing.PerformanceTimer.TestFunction} tearDownFn The set up |
| 251 |
* function that will be called once after the test function completed. |
| 252 |
* @param {!goog.async.Deferred} result The deferred result, eventually an |
| 253 |
* object containing performance stats. |
| 254 |
* @param {!Array<number>} samples The time samples from all runs of the test |
| 255 |
* function so far. |
| 256 |
* @param {number} testStart The timestamp when the first sample was started. |
| 257 |
* @private |
| 258 |
*/ |
| 259 |
goog.testing.PerformanceTimer.prototype.runAsyncTaskSample_ = function( |
| 260 |
testFn, setUpFn, tearDownFn, result, samples, testStart) { |
| 261 |
var timer = this; |
| 262 |
timer.handleOptionalDeferred_(setUpFn, function() { |
| 263 |
var sampleStart = goog.testing.PerformanceTimer.now_(); |
| 264 |
timer.handleOptionalDeferred_(testFn, function() { |
| 265 |
var sampleEnd = goog.testing.PerformanceTimer.now_(); |
| 266 |
timer.handleOptionalDeferred_(tearDownFn, function() { |
| 267 |
samples.push(sampleEnd - sampleStart); |
| 268 |
var totalRunTime = sampleEnd - testStart; |
| 269 |
if (samples.length < timer.numSamples_ && |
| 270 |
totalRunTime <= timer.timeoutInterval_) { |
| 271 |
timer.runAsyncTaskSample_( |
| 272 |
testFn, setUpFn, tearDownFn, result, samples, testStart); |
| 273 |
} else { |
| 274 |
result.callback(timer.finishTask_(samples)); |
| 275 |
} |
| 276 |
}); |
| 277 |
}); |
| 278 |
}); |
| 279 |
}; |
| 280 |
|
| 281 |
|
| 282 |
/** |
| 283 |
* Return the median of the samples. |
| 284 |
* @param {!Array<number>} samples |
| 285 |
* @return {number} |
| 286 |
*/ |
| 287 |
goog.testing.PerformanceTimer.median = function(samples) { |
| 288 |
samples.sort(function(a, b) { |
| 289 |
return a - b; |
| 290 |
}); |
| 291 |
let half = Math.floor(samples.length / 2); |
| 292 |
if (samples.length % 2) { |
| 293 |
return samples[half]; |
| 294 |
} else { |
| 295 |
return (samples[half - 1] + samples[half]) / 2.0; |
| 296 |
} |
| 297 |
}; |
| 298 |
|
| 299 |
|
| 300 |
/** |
| 301 |
* Execute a function that optionally returns a deferred object and continue |
| 302 |
* with the given continuation function only once the deferred object has a |
| 303 |
* result. |
| 304 |
* @param {goog.testing.PerformanceTimer.TestFunction} deferredFactory The |
| 305 |
* function that optionally returns a deferred object. |
| 306 |
* @param {function()} continuationFunction The function that should be called |
| 307 |
* after the optional deferred has a result. |
| 308 |
* @private |
| 309 |
*/ |
| 310 |
goog.testing.PerformanceTimer.prototype.handleOptionalDeferred_ = function( |
| 311 |
deferredFactory, continuationFunction) { |
| 312 |
var deferred = deferredFactory(); |
| 313 |
if (deferred) { |
| 314 |
deferred.addCallback(continuationFunction); |
| 315 |
} else { |
| 316 |
continuationFunction(); |
| 317 |
} |
| 318 |
}; |
| 319 |
|
| 320 |
|
| 321 |
/** |
| 322 |
* Creates a performance timer results object by analyzing a given array of |
| 323 |
* sample timings. |
| 324 |
* @param {!Array<number>} samples The samples to analyze. |
| 325 |
* @return {!Object} Object containing performance stats. |
| 326 |
*/ |
| 327 |
goog.testing.PerformanceTimer.createResults = function(samples) { |
| 328 |
return { |
| 329 |
'average': goog.math.average.apply(null, samples), |
| 330 |
'count': samples.length, |
| 331 |
'median': goog.testing.PerformanceTimer.median(samples), |
| 332 |
'maximum': Math.max.apply(null, samples), |
| 333 |
'minimum': Math.min.apply(null, samples), |
| 334 |
'standardDeviation': goog.math.standardDeviation.apply(null, samples), |
| 335 |
'total': goog.math.sum.apply(null, samples) |
| 336 |
}; |
| 337 |
}; |
| 338 |
|
| 339 |
|
| 340 |
/** |
| 341 |
* A test function whose performance should be measured or a setUp/tearDown |
| 342 |
* function. It may optionally return a deferred object. If it does so, the |
| 343 |
* test harness will assume the function is asynchronous and it must signal |
| 344 |
* that it's done by setting an (empty) result on the deferred object. If the |
| 345 |
* function doesn't return anything, the test harness will assume it's |
| 346 |
* synchronous. |
| 347 |
* @typedef {function():(goog.async.Deferred|undefined)} |
| 348 |
*/ |
| 349 |
goog.testing.PerformanceTimer.TestFunction; |
| 350 |
|
| 351 |
|
| 352 |
|
| 353 |
/** |
| 354 |
* A task for the performance timer to measure. Callers can specify optional |
| 355 |
* setUp and tearDown methods to control state before and after each run of the |
| 356 |
* test function. |
| 357 |
* @param {goog.testing.PerformanceTimer.TestFunction} test Test function whose |
| 358 |
* performance is to be measured. |
| 359 |
* @constructor |
| 360 |
* @final |
| 361 |
*/ |
| 362 |
goog.testing.PerformanceTimer.Task = function(test) { |
| 363 |
/** |
| 364 |
* The test function to time. |
| 365 |
* @type {goog.testing.PerformanceTimer.TestFunction} |
| 366 |
* @private |
| 367 |
*/ |
| 368 |
this.test_ = test; |
| 369 |
}; |
| 370 |
|
| 371 |
|
| 372 |
/** |
| 373 |
* An optional set up function to run before each invocation of the test |
| 374 |
* function. |
| 375 |
* @type {goog.testing.PerformanceTimer.TestFunction} |
| 376 |
* @private |
| 377 |
*/ |
| 378 |
goog.testing.PerformanceTimer.Task.prototype.setUp_ = goog.nullFunction; |
| 379 |
|
| 380 |
|
| 381 |
/** |
| 382 |
* An optional tear down function to run after each invocation of the test |
| 383 |
* function. |
| 384 |
* @type {goog.testing.PerformanceTimer.TestFunction} |
| 385 |
* @private |
| 386 |
*/ |
| 387 |
goog.testing.PerformanceTimer.Task.prototype.tearDown_ = goog.nullFunction; |
| 388 |
|
| 389 |
|
| 390 |
/** |
| 391 |
* @return {goog.testing.PerformanceTimer.TestFunction} The test function to |
| 392 |
* time. |
| 393 |
*/ |
| 394 |
goog.testing.PerformanceTimer.Task.prototype.getTest = function() { |
| 395 |
return this.test_; |
| 396 |
}; |
| 397 |
|
| 398 |
|
| 399 |
/** |
| 400 |
* Specifies a set up function to be invoked before each invocation of the test |
| 401 |
* function. |
| 402 |
* @param {goog.testing.PerformanceTimer.TestFunction} setUp The set up |
| 403 |
* function. |
| 404 |
* @return {!goog.testing.PerformanceTimer.Task} This task. |
| 405 |
*/ |
| 406 |
goog.testing.PerformanceTimer.Task.prototype.withSetUp = function(setUp) { |
| 407 |
this.setUp_ = setUp; |
| 408 |
return this; |
| 409 |
}; |
| 410 |
|
| 411 |
|
| 412 |
/** |
| 413 |
* @return {goog.testing.PerformanceTimer.TestFunction} The set up function or |
| 414 |
* the default no-op function if none was specified. |
| 415 |
*/ |
| 416 |
goog.testing.PerformanceTimer.Task.prototype.getSetUp = function() { |
| 417 |
return this.setUp_; |
| 418 |
}; |
| 419 |
|
| 420 |
|
| 421 |
/** |
| 422 |
* Specifies a tear down function to be invoked after each invocation of the |
| 423 |
* test function. |
| 424 |
* @param {goog.testing.PerformanceTimer.TestFunction} tearDown The tear down |
| 425 |
* function. |
| 426 |
* @return {!goog.testing.PerformanceTimer.Task} This task. |
| 427 |
*/ |
| 428 |
goog.testing.PerformanceTimer.Task.prototype.withTearDown = function(tearDown) { |
| 429 |
this.tearDown_ = tearDown; |
| 430 |
return this; |
| 431 |
}; |
| 432 |
|
| 433 |
|
| 434 |
/** |
| 435 |
* @return {goog.testing.PerformanceTimer.TestFunction} The tear down function |
| 436 |
* or the default no-op function if none was specified. |
| 437 |
*/ |
| 438 |
goog.testing.PerformanceTimer.Task.prototype.getTearDown = function() { |
| 439 |
return this.tearDown_; |
| 440 |
}; |