feat(jest-runtime): expose isTornDown variable

This commit adds a new feature to the Jest runtime package that exposes
the `isTornDown` variable as a way to check if the Jest environment has
been torn down programmatically. The `isTornDown` variable is a
read-only boolean that is set to `true` when the environment is torn
down and `false` otherwise.

The commit also adds documentation for the `isTornDown` variable to the
Jest runtime module.

Closes #13640

CHANGELOG.md

@@ -12,6 +12,12 @@
 
 ### Performance
 
+## 29.3.2
+
+### Features
+
+- `[jest-runtime]` Expose `isEnvironmentTornDown` function ([#13698](https://github.com/facebook/jest/pull/13698))
+
 ## 29.3.1
 
 ### Fixes

packages/jest-environment/src/index.ts

@@ -172,6 +172,15 @@ export interface Jest {
    * local module state doesn't conflict between tests.
    */
   isolateModules(fn: () => void): Jest;
+  /**
+   * A flag that indicates whether the Jest environment has been torn down.
+   * @example
+   * if (jest.isEnvironmentTornDown()) {
+   *   // The Jest environment has been torn down, so stop doing work
+   *   return;
+   * }
+   */
+  isEnvironmentTornDown(): boolean;
   /**
    * Mocks a module with an auto-mocked version when it is being required.
    */

packages/jest-runtime/src/__tests__/runtime_jest_fn.js

@@ -66,4 +66,21 @@ describe('Runtime', () => {
       expect(mock2).not.toHaveBeenCalled();
     });
   });
+
+  describe('jest.isEnvironmentTornDown()', () => {
+    it('should be set to false when the environment is not torn down', async () => {
+      const runtime = await createRuntime(__filename);
+      const root = runtime.requireModule(runtime.__mockRootPath);
+      runtime['isTornDown'] = false;
+      expect(root.jest.isEnvironmentTornDown()).toBe(false);
+    });
+
+    it('should be set to true when the environment is torn down', async () => {
+      const runtime = await createRuntime(__filename);
+      const root = runtime.requireModule(runtime.__mockRootPath);
+      expect(root.jest.isEnvironmentTornDown()).toBe(false);
+      runtime.teardown();
+      expect(root.jest.isEnvironmentTornDown()).toBe(true);
+    });
+  });
 });

packages/jest-runtime/src/index.ts

@@ -2224,6 +2224,7 @@ export default class Runtime {
         return this._globalConfig.seed;
       },
       getTimerCount: () => _getFakeTimers().getTimerCount(),
+      isEnvironmentTornDown: () => this.isTornDown,
       isMockFunction: this._moduleMocker.isMockFunction,
       isolateModules,
       mock,