From 361640f52ea6f3f48c7495d448d350c5dbadce43 Mon Sep 17 00:00:00 2001
From: Steve Gravrock <sdg@panix.com>
Date: Sat, 26 Apr 2025 07:38:28 -0700
Subject: [PATCH] Document that SpecResult#filename and SuiteResult#filename
 are wrong in some common scenarios

See:

* https://github.com/jasmine/jasmine/issues/2016
* https://github.com/jasmine/jasmine/issues/1884
---
 lib/jasmine-core/jasmine.js | 6 ++++++
 src/core/Spec.js            | 3 +++
 src/core/Suite.js           | 3 +++
 3 files changed, 12 insertions(+)

diff --git a/lib/jasmine-core/jasmine.js b/lib/jasmine-core/jasmine.js
index 76dbb7bb..5e3bc2f9 100644
--- a/lib/jasmine-core/jasmine.js
+++ b/lib/jasmine-core/jasmine.js
@@ -919,6 +919,9 @@ getJasmineRequireObj().Spec = function(j$) {
      * @property {String} fullName - The full description including all ancestors of this spec.
      * @property {String|null} parentSuiteId - The ID of the suite containing this spec, or null if this spec is not in a describe().
      * @property {String} filename - The name of the file the spec was defined in.
+     * Note: The value may be incorrect if zone.js is installed or
+     * `it`/`fit`/`xit` have been replaced with versions that don't maintain the
+     *  same call stack height as the originals.
      * @property {ExpectationResult[]} failedExpectations - The list of expectations that failed during execution of this spec.
      * @property {ExpectationResult[]} passedExpectations - The list of expectations that passed during execution of this spec.
      * @property {ExpectationResult[]} deprecationWarnings - The list of deprecation warnings that occurred during execution this spec.
@@ -10478,6 +10481,9 @@ getJasmineRequireObj().Suite = function(j$) {
      * @property {String} fullName - The full description including all ancestors of this suite.
      * @property {String|null} parentSuiteId - The ID of the suite containing this suite, or null if this is not in another describe().
      * @property {String} filename - The name of the file the suite was defined in.
+     * Note: The value may be incorrect if zone.js is installed or
+     * `describe`/`fdescribe`/`xdescribe` have been replaced with versions that
+     * don't maintain the same call stack height as the originals.
      * @property {ExpectationResult[]} failedExpectations - The list of expectations that failed in an {@link afterAll} for this suite.
      * @property {ExpectationResult[]} deprecationWarnings - The list of deprecation warnings that occurred on this suite.
      * @property {String} status - Once the suite has completed, this string represents the pass/fail status of this suite.
diff --git a/src/core/Spec.js b/src/core/Spec.js
index 6ba9870a..d6c54df0 100644
--- a/src/core/Spec.js
+++ b/src/core/Spec.js
@@ -148,6 +148,9 @@ getJasmineRequireObj().Spec = function(j$) {
      * @property {String} fullName - The full description including all ancestors of this spec.
      * @property {String|null} parentSuiteId - The ID of the suite containing this spec, or null if this spec is not in a describe().
      * @property {String} filename - The name of the file the spec was defined in.
+     * Note: The value may be incorrect if zone.js is installed or
+     * `it`/`fit`/`xit` have been replaced with versions that don't maintain the
+     *  same call stack height as the originals.
      * @property {ExpectationResult[]} failedExpectations - The list of expectations that failed during execution of this spec.
      * @property {ExpectationResult[]} passedExpectations - The list of expectations that passed during execution of this spec.
      * @property {ExpectationResult[]} deprecationWarnings - The list of deprecation warnings that occurred during execution this spec.
diff --git a/src/core/Suite.js b/src/core/Suite.js
index 106666df..47e9f655 100644
--- a/src/core/Suite.js
+++ b/src/core/Suite.js
@@ -105,6 +105,9 @@ getJasmineRequireObj().Suite = function(j$) {
      * @property {String} fullName - The full description including all ancestors of this suite.
      * @property {String|null} parentSuiteId - The ID of the suite containing this suite, or null if this is not in another describe().
      * @property {String} filename - The name of the file the suite was defined in.
+     * Note: The value may be incorrect if zone.js is installed or
+     * `describe`/`fdescribe`/`xdescribe` have been replaced with versions that
+     * don't maintain the same call stack height as the originals.
      * @property {ExpectationResult[]} failedExpectations - The list of expectations that failed in an {@link afterAll} for this suite.
      * @property {ExpectationResult[]} deprecationWarnings - The list of deprecation warnings that occurred on this suite.
      * @property {String} status - Once the suite has completed, this string represents the pass/fail status of this suite.