warren/jasmine
1
0
Fork 0
Code Issues Pull Requests Actions 9 Packages Projects Releases Wiki Activity

Add jsdocs for reporter events

Browse Source
This commit is contained in:
Gregg Van Hove
2017-08-09 10:21:59 -07:00
parent 80dba1138a
commit 1926fc11ae
6 changed files with 176 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
lib/jasmine-core/jasmine.js
View File

@@ -462,6 +462,16 @@ getJasmineRequireObj().Spec = function(j$) {
this.pend();
}
/**
* @typedef SpecResult
* @property {Int} id - The unique id of this spec.
* @property {String} description - The description passed to the {@link it} that created this spec.
* @property {String} fullName - The full description including all ancestors of this spec.
* @property {Expectation[]} failedExpectations - The list of expectations that failed during execution of this spec.
* @property {Expectation[]} passedExpectations - The list of expectations that passed during execution of this spec.
* @property {String} pendingReason - If the spec is {@link pending}, this will be the reason.
* @property {String} status - Once the spec has completed, this string represents the pass/fail status of this spec.
*/
this.result = {
id: this.id,
description: this.description,
@@ -690,12 +700,56 @@ getJasmineRequireObj().Env = function(j$) {
return currentSpec || currentSuite();
};
/**
* This represents the available reporter callback for an object passed to {@link Env#addReporter}.
* @interface Reporter
*/
var reporter = new j$.ReportDispatcher([
/**
* `jasmineStarted` is called after all of the specs have been loaded, but just before execution starts.
* @function
* @name Reporter#jasmineStarted
* @param {JasmineStartedInfo} suiteInfo Information about the full Jasmine suite that is being run
*/
'jasmineStarted',
/**
* When the entire suite has finished execution `jasmineDone` is called
* @function
* @name Reporter#jasmineDone
* @param {JasmineDoneInfo} suiteInfo Information about the full Jasmine suite that just finished running.
*/
'jasmineDone',
/**
* `suiteStarted` is invoked when a `describe` starts to run
* @function
* @name Reporter#suiteStarted
* @param {SuiteResult} result Information about the individual {@link describe} being run
*/
'suiteStarted',
/**
* `suiteDone` is invoked when all of the child specs and suites for a given suite have been run
*
* While jasmine doesn't require any specific functions, not defining a `suiteDone` will make it impossible for a reporter to know when a suite has failures in an `afterAll`.
* @function
* @name Reporter#suiteDone
* @param {SuiteResult} result
*/
'suiteDone',
/**
* `specStarted` is invoked when an `it` starts to run (including associated `beforeEach` functions)
* @function
* @name Reporter#specStarted
* @param {SpecResult} result Information about the individual {@link it} being run
*/
'specStarted',
/**
* `specDone` is invoked when an `it` and its associated `beforeEach` and `afterEach` functions have been run.
*
* While jasmine doesn't require any specific functions, not defining a `specDone` will make it impossible for a reporter to know when a spec has failed.
* @function
* @name Reporter#specDone
* @param {SpecResult} result
*/
'specDone'
]);
@@ -911,6 +965,12 @@ getJasmineRequireObj().Env = function(j$) {
throw new Error('Invalid order: would cause a beforeAll or afterAll to be run multiple times');
}
/**
* Information passed to the {@link Reporter#jasmineStarted} event.
* @typedef JasmineStartedInfo
* @property {Int} totalSpecsDefined - The total number of specs defined in this suite.
* @property {Order} order - Information about the ordering (random or not) of this execution of the suite.
*/
reporter.jasmineStarted({
totalSpecsDefined: totalSpecsDefined,
order: order
@@ -924,6 +984,12 @@ getJasmineRequireObj().Env = function(j$) {
currentlyExecutingSuites.pop();
globalErrors.uninstall();
/**
* Information passed to the {@link Reporter#jasmineDone} event.
* @typedef JasmineDoneInfo
* @property {Order} order - Information about the ordering (random or not) of this execution of the suite.
* @property {Expectation[]} failedExpectations - List of expectations that failed in an {@link afterAll} at the global level.
*/
reporter.jasmineDone({
order: order,
failedExpectations: topSuite.result.failedExpectations
@@ -935,6 +1001,7 @@ getJasmineRequireObj().Env = function(j$) {
* Add a custom reporter to the Jasmine environment.
* @name Env#addReporter
* @function
* @param {Reporter} reporterToAdd The reporter to be added.
* @see custom_reporter
*/
this.addReporter = function(reporterToAdd) {
@@ -1244,8 +1311,9 @@ getJasmineRequireObj().JsApiReporter = function() {
* _Note:_ Do not construct this directly, use the global `jsApiReporter` to retrieve the instantiated object.
*
* @name jsApiReporter
* @classdesc Reporter added by default in `boot.js` to record results for retrieval in javascript code.
* @classdesc {@link Reporter} added by default in `boot.js` to record results for retrieval in javascript code.
* @class
* @hideconstructor
*/
function JsApiReporter(options) {
var timer = options.timer || noopTimer,
@@ -2226,6 +2294,15 @@ getJasmineRequireObj().buildExpectationResult = function() {
var messageFormatter = options.messageFormatter || function() {},
stackFormatter = options.stackFormatter || function() {};
/**
* @typedef Expectation
* @property {String} matcherName - The name of the matcher that was executed for this expectation.
* @property {String} message - The failure message for the expectation.
* @property {String} stack - The stack trace for the failure if available.
* @property {Boolean} passed - Whether the expectation passed or failed.
* @property {Object} expected - If the expectation failed, what was the expected value.
* @property {Object} actual - If the expectation failed, what actual value was produced.
*/
var result = {
matcherName: options.matcherName,
message: message(),
@@ -4284,7 +4361,7 @@ getJasmineRequireObj().interface = function(jasmine, env) {
* By default Jasmine assumes this function completes synchronously.
* If you have code that you need to test asynchronously, you can declare that you receive a `done` callback, return a Promise, or use the `async` keyword if it is supported in your environment.
* @callback implementationCallback
* @param {Function} done Used to specify to Jasmine that this callback is asynchronous and Jasmine should wait until it has been called before moving on.
* @param {Function} [done] Used to specify to Jasmine that this callback is asynchronous and Jasmine should wait until it has been called before moving on.
* @returns {} Optionally return a Promise instead of using `done` to cause Jasmine to wait for completion.
*/
@@ -4296,7 +4373,7 @@ getJasmineRequireObj().interface = function(jasmine, env) {
* @function
* @global
* @param {String} description Textual description of the group
* @param {Function} specDefinitions Function for Jasmine to invoke that will define inner suites a specs
* @param {Function} specDefinitions Function for Jasmine to invoke that will define inner suites and specs
*/
describe: function(description, specDefinitions) {
return env.describe(description, specDefinitions);
@@ -4310,7 +4387,7 @@ getJasmineRequireObj().interface = function(jasmine, env) {
* @function
* @global
* @param {String} description Textual description of the group
* @param {Function} specDefinitions Function for Jasmine to invoke that will define inner suites a specs
* @param {Function} specDefinitions Function for Jasmine to invoke that will define inner suites and specs
*/
xdescribe: function(description, specDefinitions) {
return env.xdescribe(description, specDefinitions);
@@ -4325,7 +4402,7 @@ getJasmineRequireObj().interface = function(jasmine, env) {
* @function
* @global
* @param {String} description Textual description of the group
* @param {Function} specDefinitions Function for Jasmine to invoke that will define inner suites a specs
* @param {Function} specDefinitions Function for Jasmine to invoke that will define inner suites and specs
*/
fdescribe: function(description, specDefinitions) {
return env.fdescribe(description, specDefinitions);
@@ -4887,6 +4964,14 @@ getJasmineRequireObj().Suite = function(j$) {
this.children = [];
/**
* @typedef SuiteResult
* @property {Int} id - The unique id of this suite.
* @property {String} description - The description text passed to the {@link describe} that made this suite.
* @property {String} fullName - The full description including all ancestors of this suite.
* @property {Expectation[]} failedExpectations - The list of expectations that failed in an {@link afterAll} for this suite.
* @property {String} status - Once the suite has completed, this string represents the pass/fail status of this suite.
*/
this.result = {
id: this.id,
description: this.description,

57
src/core/Env.js
View File

@@ -37,12 +37,56 @@ getJasmineRequireObj().Env = function(j$) {
return currentSpec || currentSuite();
};
/**
* This represents the available reporter callback for an object passed to {@link Env#addReporter}.
* @interface Reporter
*/
var reporter = new j$.ReportDispatcher([
/**
* `jasmineStarted` is called after all of the specs have been loaded, but just before execution starts.
* @function
* @name Reporter#jasmineStarted
* @param {JasmineStartedInfo} suiteInfo Information about the full Jasmine suite that is being run
*/
'jasmineStarted',
/**
* When the entire suite has finished execution `jasmineDone` is called
* @function
* @name Reporter#jasmineDone
* @param {JasmineDoneInfo} suiteInfo Information about the full Jasmine suite that just finished running.
*/
'jasmineDone',
/**
* `suiteStarted` is invoked when a `describe` starts to run
* @function
* @name Reporter#suiteStarted
* @param {SuiteResult} result Information about the individual {@link describe} being run
*/
'suiteStarted',
/**
* `suiteDone` is invoked when all of the child specs and suites for a given suite have been run
*
* While jasmine doesn't require any specific functions, not defining a `suiteDone` will make it impossible for a reporter to know when a suite has failures in an `afterAll`.
* @function
* @name Reporter#suiteDone
* @param {SuiteResult} result
*/
'suiteDone',
/**
* `specStarted` is invoked when an `it` starts to run (including associated `beforeEach` functions)
* @function
* @name Reporter#specStarted
* @param {SpecResult} result Information about the individual {@link it} being run
*/
'specStarted',
/**
* `specDone` is invoked when an `it` and its associated `beforeEach` and `afterEach` functions have been run.
*
* While jasmine doesn't require any specific functions, not defining a `specDone` will make it impossible for a reporter to know when a spec has failed.
* @function
* @name Reporter#specDone
* @param {SpecResult} result
*/
'specDone'
]);
@@ -258,6 +302,12 @@ getJasmineRequireObj().Env = function(j$) {
throw new Error('Invalid order: would cause a beforeAll or afterAll to be run multiple times');
}
/**
* Information passed to the {@link Reporter#jasmineStarted} event.
* @typedef JasmineStartedInfo
* @property {Int} totalSpecsDefined - The total number of specs defined in this suite.
* @property {Order} order - Information about the ordering (random or not) of this execution of the suite.
*/
reporter.jasmineStarted({
totalSpecsDefined: totalSpecsDefined,
order: order
@@ -271,6 +321,12 @@ getJasmineRequireObj().Env = function(j$) {
currentlyExecutingSuites.pop();
globalErrors.uninstall();
/**
* Information passed to the {@link Reporter#jasmineDone} event.
* @typedef JasmineDoneInfo
* @property {Order} order - Information about the ordering (random or not) of this execution of the suite.
* @property {Expectation[]} failedExpectations - List of expectations that failed in an {@link afterAll} at the global level.
*/
reporter.jasmineDone({
order: order,
failedExpectations: topSuite.result.failedExpectations
@@ -282,6 +338,7 @@ getJasmineRequireObj().Env = function(j$) {
* Add a custom reporter to the Jasmine environment.
* @name Env#addReporter
* @function
* @param {Reporter} reporterToAdd The reporter to be added.
* @see custom_reporter
*/
this.addReporter = function(reporterToAdd) {

9
src/core/ExpectationResult.js
View File

@@ -4,6 +4,15 @@ getJasmineRequireObj().buildExpectationResult = function() {
var messageFormatter = options.messageFormatter || function() {},
stackFormatter = options.stackFormatter || function() {};
/**
* @typedef Expectation
* @property {String} matcherName - The name of the matcher that was executed for this expectation.
* @property {String} message - The failure message for the expectation.
* @property {String} stack - The stack trace for the failure if available.
* @property {Boolean} passed - Whether the expectation passed or failed.
* @property {Object} expected - If the expectation failed, what was the expected value.
* @property {Object} actual - If the expectation failed, what actual value was produced.
*/
var result = {
matcherName: options.matcherName,
message: message(),

5
src/core/JsApiReporter.js
View File

@@ -6,11 +6,10 @@ getJasmineRequireObj().JsApiReporter = function() {
};
/**
* _Note:_ Do not construct this directly, use the global `jsApiReporter` to retrieve the instantiated object.
*
* @name jsApiReporter
* @classdesc Reporter added by default in `boot.js` to record results for retrieval in javascript code.
* @classdesc {@link Reporter} added by default in `boot.js` to record results for retrieval in javascript code. An instance is made available as `jsApiReporter` on the global object.
* @class
* @hideconstructor
*/
function JsApiReporter(options) {
var timer = options.timer || noopTimer,

10
src/core/Spec.js
View File

@@ -18,6 +18,16 @@ getJasmineRequireObj().Spec = function(j$) {
this.pend();
}
/**
* @typedef SpecResult
* @property {Int} id - The unique id of this spec.
* @property {String} description - The description passed to the {@link it} that created this spec.
* @property {String} fullName - The full description including all ancestors of this spec.
* @property {Expectation[]} failedExpectations - The list of expectations that failed during execution of this spec.
* @property {Expectation[]} passedExpectations - The list of expectations that passed during execution of this spec.
* @property {String} pendingReason - If the spec is {@link pending}, this will be the reason.
* @property {String} status - Once the spec has completed, this string represents the pass/fail status of this spec.
*/
this.result = {
id: this.id,
description: this.description,

8
src/core/Suite.js
View File

@@ -15,6 +15,14 @@ getJasmineRequireObj().Suite = function(j$) {
this.children = [];
/**
* @typedef SuiteResult
* @property {Int} id - The unique id of this suite.
* @property {String} description - The description text passed to the {@link describe} that made this suite.
* @property {String} fullName - The full description including all ancestors of this suite.
* @property {Expectation[]} failedExpectations - The list of expectations that failed in an {@link afterAll} for this suite.
* @property {String} status - Once the suite has completed, this string represents the pass/fail status of this suite.
*/
this.result = {
id: this.id,
description: this.description,