Revert "Revert "Added the ability to associate trace information with failing specs""

This reverts commit fdad8849df.

src/core/Env.js

@@ -1148,6 +1148,16 @@ getJasmineRequireObj().Env = function(j$) {
       currentSuite().setSuiteProperty(key, value);
     };
 
+    this.trace = function(msg) {
+      var maybeSpec = currentRunnable();
+
+      if (!maybeSpec || !maybeSpec.trace) {
+        throw new Error("'trace' was called when there was no current spec");
+      }
+
+      maybeSpec.trace(msg);
+    };
+
     this.expect = function(actual) {
       if (!currentRunnable()) {
         throw new Error(

src/core/Spec.js

@@ -69,8 +69,9 @@ getJasmineRequireObj().Spec = function(j$) {
      * @property {String} status - Once the spec has completed, this string represents the pass/fail status of this spec.
      * @property {number} duration - The time in ms used by the spec execution, including any before/afterEach.
      * @property {Object} properties - User-supplied properties, if any, that were set using {@link Env#setSpecProperty}
+     * @property {TraceEntry[]|null} trace - Trace messages, if any, that were logged using {@link Env#trace} during a failing spec.
      * @since 2.0.0
-x     */
+     */
     this.result = {
       id: this.id,
       description: this.description,
@@ -80,7 +81,8 @@ x     */
       deprecationWarnings: [],
       pendingReason: '',
       duration: null,
-      properties: null
+      properties: null,
+      trace: null
     };
   }
 
@@ -125,6 +127,11 @@ x     */
         self.queueableFn.fn = null;
         self.result.status = self.status(excluded, failSpecWithNoExp);
         self.result.duration = self.timer.elapsed();
+
+        if (self.result.status !== 'failed') {
+          self.result.trace = null;
+        }
+
         self.resultCallback(self.result, done);
       }
     };
@@ -251,6 +258,20 @@ x     */
     );
   };
 
+  Spec.prototype.trace = function(msg) {
+    if (!this.result.trace) {
+      this.result.trace = [];
+    }
+
+    /**
+     * @typedef TraceEntry
+     * @property {String} message - The message that was passed to {@link Env#trace}.
+     * @property {number} timestamp - The time when the entry was added, in
+     * milliseconds from the spec's start time
+     */
+    this.result.trace.push({ message: msg, timestamp: this.timer.elapsed() });
+  };
+
   var extractCustomPendingMessage = function(e) {
     var fullMessage = e.toString(),
       boilerplateStart = fullMessage.indexOf(Spec.pendingSpecExceptionMessage),

src/core/base.js

@@ -397,4 +397,20 @@ getJasmineRequireObj().base = function(j$, jasmineGlobal) {
       putativeSpy.calls instanceof j$.CallTracker
     );
   };
+
+  /**
+   * Logs a message for use in debugging. If the spec fails, trace messages
+   * will be included in the {@link SpecResult|result} passed to the
+   * reporter's specDone method.
+   *
+   * This method should be called only when a spec (including any associated
+   * beforeEach or afterEach functions) is running.
+   * @function
+   * @name jasmine.trace
+   * @since 3.10.0
+   * @param {String} msg - The message to log
+   */
+  j$.trace = function(msg) {
+    j$.getEnv().trace(msg);
+  };
 };