Added the ability to associate trace information with failing specs

This is meant to aid in debugging failures, particularly intermittent
failures, in cases where interactive debugging or console.log aren't
suitable.

src/core/Env.js

@@ -1318,6 +1318,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

@@ -68,8 +68,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,
@@ -79,7 +80,8 @@ x     */
       deprecationWarnings: [],
       pendingReason: '',
       duration: null,
-      properties: null
+      properties: null,
+      trace: null
     };
   }
 
@@ -124,6 +126,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);
       }
     };
@@ -235,6 +242,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

@@ -420,4 +420,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);
+  };
 };