fixed: add typings for class Result (#5236)

* fixed: typings for class Result

* fix docs for getters

Author: danielrentz

lib/result.js

@@ -3,22 +3,21 @@ const path = require('path')
 const { serializeTest } = require('./mocha/test')
 
 /**
- * Result of the test run
- *
- * @typedef {Object} Stats
- * @property {number} passes
- * @property {number} failures
- * @property {number} tests
- * @property {number} pending
- * @property {number} failedHooks
- * @property {Date} start
- * @property {Date} end
- * @property {number} duration
+ * @typedef {Object} Stats Statistics for a test result.
+ * @property {number} passes Number of passed tests.
+ * @property {number} failures Number of failed tests.
+ * @property {number} tests Total number of tests.
+ * @property {number} pending Number of pending tests.
+ * @property {number} failedHooks Number of failed hooks.
+ * @property {Date} start Start time of the test run.
+ * @property {Date} end End time of the test run.
+ * @property {number} duration Duration of the test run, in milliseconds.
+ */
+
+/**
+ * Result of a test run. Will be emitted for example in "event.all.result" events.
  */
 class Result {
-  /**
-   * Create Result of the test run
-   */
   constructor() {
     this._startTime = new Date()
     this._endTime = null
@@ -27,6 +26,9 @@ class Result {
     this.start()
   }
 
+  /**
+   * Resets all collected stats, tests, and failure reports.
+   */
   reset() {
     this._stats = {
       passes: 0,
@@ -39,43 +41,85 @@ class Result {
       duration: 0,
     }
 
-    /** @type {CodeceptJS.Test[]} */
+    /**
+     * @type {CodeceptJS.Test[]}
+     * @private
+     */
     this._tests = []
 
-    /** @type {String[]} */
+    /**
+     * @type {string[][]}
+     * @private
+     */
     this._failures = []
   }
 
+  /**
+   * Sets the start time to the current time.
+   */
   start() {
     this._startTime = new Date()
   }
 
+  /**
+   * Sets the end time to the current time.
+   */
   finish() {
     this._endTime = new Date()
   }
 
+  /**
+   * Whether this result contains any failed tests.
+   *
+   * @type {boolean}
+   * @readonly
+   */
   get hasFailed() {
     return this._stats.failures > 0
   }
 
+  /**
+   * All collected tests.
+   *
+   * @type {CodeceptJS.Test[]}
+   * @readonly
+   */
   get tests() {
     return this._tests
   }
 
+  /**
+   * The failure reports (array of strings per failed test).
+   *
+   * @type {string[][]}
+   * @readonly
+   */
   get failures() {
     return this._failures.filter(f => f && (!Array.isArray(f) || f.length > 0))
   }
 
+  /**
+   * The test statistics.
+   *
+   * @type {Stats}
+   * @readonly
+   */
   get stats() {
     return this._stats
   }
 
+  /**
+   * The start time of the test run.
+   *
+   * @type {Date}
+   * @readonly
+   */
   get startTime() {
     return this._startTime
   }
 
   /**
-   * Add test to result
+   * Adds a test to this result.
    *
    * @param {CodeceptJS.Test} test
    */
@@ -90,34 +134,67 @@ class Result {
   }
 
   /**
-   * Add failures to result
+   * Adds failure reports to this result.
    *
-   * @param {String[]} newFailures
+   * @param {string[][]} newFailures
    */
   addFailures(newFailures) {
     this._failures.push(...newFailures)
   }
 
+  /**
+   * Whether this result contains any failed tests.
+   *
+   * @type {boolean}
+   * @readonly
+   */
   get hasFailures() {
     return this.stats.failures > 0
   }
 
+  /**
+   * The duration of the test run, in milliseconds.
+   *
+   * @type {number}
+   * @readonly
+   */
   get duration() {
     return this._endTime ? +this._endTime - +this._startTime : 0
   }
 
+  /**
+   * All failed tests.
+   *
+   * @type {CodeceptJS.Test[]}
+   * readonly
+   */
   get failedTests() {
     return this._tests.filter(test => test.state === 'failed')
   }
 
+  /**
+   * All passed tests.
+   *
+   * @type {CodeceptJS.Test[]}
+   * @readonly
+   */
   get passedTests() {
     return this._tests.filter(test => test.state === 'passed')
   }
 
+  /**
+   * All skipped tests.
+   *
+   * @type {CodeceptJS.Test[]}
+   * @readonly
+   */
   get skippedTests() {
     return this._tests.filter(test => test.state === 'skipped' || test.state === 'pending')
   }
 
+  /**
+   * @returns {object} The JSON representation of this result.
+   */
   simplify() {
     return {
       hasFailed: this.hasFailed,
@@ -129,19 +206,19 @@ class Result {
   }
 
   /**
-   * Save result to json file
+   * Saves this result to a JSON file.
    *
-   * @param {string} fileName
+   * @param {string} [fileName] Path to the JSON file, relative to `output_dir`. Defaults to "result.json".
    */
   save(fileName) {
     if (!fileName) fileName = 'result.json'
     fs.writeFileSync(path.join(global.output_dir, fileName), JSON.stringify(this.simplify(), null, 2))
   }
 
   /**
-   * Add stats to result
+   * Adds stats to this result.
    *
-   * @param {object} newStats
+   * @param {Partial<Stats>} [newStats]
    */
   addStats(newStats = {}) {
     this._stats.passes += newStats.passes || 0