diff --git a/lib/jasmine.js b/lib/jasmine.js index 8832915..6a05409 100644 --- a/lib/jasmine.js +++ b/lib/jasmine.js @@ -8,6 +8,25 @@ var path = require('path'), module.exports = Jasmine; module.exports.ConsoleReporter = require('./reporters/console_reporter'); +/** + * Options for the {@link Jasmine} constructor + * @name JasmineOptions + * @interface + */ +/** + * The path to the project's base directory. This can be absolute or relative + * to the current working directory. If it isn't specified, the current working + * directory will be used. + * @name JasmineOptions#projectBaseDir + * @type (string | undefined) + */ + +/** + * @classdesc Configures, builds, and executes a Jasmine test suite + * @param {(JasmineOptions | undefined)} options + * @constructor + * @name Jasmine + */ function Jasmine(options) { options = options || {}; this.loader = options.loader || new Loader(); @@ -35,37 +54,89 @@ function Jasmine(options) { }); this.checkExit = checkExit(this); + /** + * @function + * @name Jasmine#coreVersion + * @return {string} The version of jasmine-core in use + */ this.coreVersion = function() { return jasmineCore.version(); }; } +/** + * Sets whether to randomize the order of specs. + * @function + * @name Jasmine#randomizeTests + * @deprecated Use the random option with {@link Jasmine#loadConfig} or a + * config file instead. + * @param {boolean} value Whether to randomize + */ Jasmine.prototype.randomizeTests = function(value) { this.env.configure({random: value}); }; +/** + * Sets the random seed. + * @function + * @name Jasmine#seed + * @deprecated Use the seed option with {@link Jasmine#loadConfig} or a + * config file instead. + * @param {number} seed The random seed + */ Jasmine.prototype.seed = function(value) { this.env.configure({seed: value}); }; +/** + * Sets whether to show colors in the console reporter. + * @function + * @name Jasmine#showColors + * @param {boolean} value Whether to show colors + */ Jasmine.prototype.showColors = function(value) { this.showingColors = value; }; +/** + * Adds a spec file to the list that will be loaded when the suite is executed. + * @function + * @name Jasmine#addSpecFile + * @param {string} filePath The path to the file to be loaded. + */ Jasmine.prototype.addSpecFile = function(filePath) { this.specFiles.push(filePath); }; +/** + * Add a custom reporter to the Jasmine environment. + * @function + * @name Jasmine#addReporter + * @param {Reporter} reporter The reporter to add + * @see custom_reporter + */ Jasmine.prototype.addReporter = function(reporter) { this.env.addReporter(reporter); this.reportersCount++; }; +/** + * Clears all registered reporters. + * @function + * @name Jasmine#clearReporters + */ Jasmine.prototype.clearReporters = function() { this.env.clearReporters(); this.reportersCount = 0; }; +/** + * Provide a fallback reporter if no other reporters have been specified. + * @function + * @name Jasmine#provideFallbackReporter + * @param reporter The fallback reporter + * @see custom_reporter + */ Jasmine.prototype.provideFallbackReporter = function(reporter) { this.env.provideFallbackReporter(reporter); }; @@ -82,6 +153,15 @@ Jasmine.prototype.configureDefaultReporter = function(options) { this.defaultReporterConfigured = true; }; +/** + * Add custom matchers for the current scope of specs. + * + * _Note:_ This is only callable from within a {@link beforeEach}, {@link it}, or {@link beforeAll}. + * @function + * @name Jasmine#addMatchers + * @param {Object} matchers - Keys from this object will be the new matcher names. + * @see custom_matcher + */ Jasmine.prototype.addMatchers = function(matchers) { this.env.addMatchers(matchers); }; @@ -109,6 +189,12 @@ Jasmine.prototype.loadRequires = function() { }); }; +/** + * Loads configuration from the specified file. The file can be a JSON file or + * any JS file that's loadable via require and provides a Jasmine config + * as its default export. + * @param configFilePath + */ Jasmine.prototype.loadConfigFile = function(configFilePath) { try { var absoluteConfigFilePath = path.resolve(this.projectBaseDir, configFilePath || 'spec/support/jasmine.json'); @@ -119,6 +205,10 @@ Jasmine.prototype.loadConfigFile = function(configFilePath) { } }; +/** + * Loads configuration from the specified object. + * @param config + */ Jasmine.prototype.loadConfig = function(config) { this.specDir = config.spec_dir || this.specDir; @@ -216,14 +306,42 @@ function addFiles(kind) { }; } +/** + * Registers a callback that will be called when execution finishes. + * + * _Note_: Only one callback can be registered. The callback will be called + * after the suite has completed and the results have been finalized, but not + * necessarily before all of Jasmine's cleanup has finished. + * + * @deprecated Use the promise returned from {@link Jasmine#execute} instead. + * @param {function} onCompleteCallback + */ Jasmine.prototype.onComplete = function(onCompleteCallback) { this.completionReporter.onComplete(onCompleteCallback); }; +/** + * Sets whether to cause specs to only have one expectation failure. + * @function + * @name Jasmine#stopSpecOnExpectationFailure + * @deprecated Use the oneFailurePerSped option with + * {@link Jasmine#loadConfig} or a config file instead. + * @param {boolean} value Whether to cause specs to only have one expectation + * failure + */ Jasmine.prototype.stopSpecOnExpectationFailure = function(value) { this.env.configure({oneFailurePerSpec: value}); }; +/** + * Sets whether to stop execution of the suite after the first spec failure. + * @function + * @name Jasmine#stopOnSpecFailure + * @deprecated Use the failFast option with {@link Jasmine#loadConfig} or a + * config file instead. + * @param {boolean} value Whether to stop execution of the suite after the + * first spec failure + */ Jasmine.prototype.stopOnSpecFailure = function(value) { this.env.configure({failFast: value}); }; @@ -267,6 +385,14 @@ function checkForJsFileImportSupport() { } } +/** + * Runs the test suite. + * @param {Array.} [files] Spec files to run instead of the previously + * configured set + * @param {string} [filterString] Regex used to filter specs. If specified, only + * specs with matching full names will be run. + * @return {Promise} Promise that is resolved when the suite completes. + */ Jasmine.prototype.execute = async function(files, filterString) { this.completionReporter.exitHandler = this.checkExit;