[Feature]: expose isTornDown readonly property

[CreativeTechGuy]

🚀 Feature Proposal

Provide a way to check if the Jest environment is torn down programatically.

Motivation

In cases where a test does a lot of work and can time out, it can result in thousands of errors in the form of:

ReferenceError: You are trying to access a property or method of the Jest environment after it has been torn down.

If the test has timed out, it'd be great to be able to check that and abort what we are doing. This is primarily useful for libraries which build test utilities, specifically when the library interacts with fake timers heavily.

The code I experienced this with was a loop of async/await which may have compounded the issue but I believe the issue is more generic than that.

Example

I am testing code which runs based on requestAnimationFrame. As a result I have a lot of jest.advanceTimersByTime calls in my tests. Sometimes these are called in a loop to advance through several minutes, one frame at a time. These tests can occasionally time out since a lot of work is being done every frame. When that happens, there may still be a few hundred/thousand advanceTimersByTime calls still to be called in the loop. As a result, not only does the test fail due to timeout, but now the entire console is spammed with massive stack traces and errors because of the above ReferenceError.

Pitch

Jest is already tracking this internally to show the error message. It has an isTornDown property (in jest-runtime) which isn't exposed. If we had access to that property, we could stop our work. I don't see a reliable way to check if the environment has been torn down or the test has timed out programatically during the test aside from exposing a new property/method.

[github-actions]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 30 days.

[CreativeTechGuy]

This is not stale

[SimenB]

Happy to take a PR adding this. Exposing on jest should be fairly trivial 🙂 Logic will be contained within jest-runtime

[jomendez]

Created a PR for this: #13698

[mrazauskas]

@jomendez Thanks for PR.

Looking at the issue it seems that the focus is on timed-out test, not on torn down environment. I mean isTornDown does good job internally, but can a user get why jest.isTornDown is useful? When to use it? What is torn down? jest.isEnvironmentTornDown sounds better, but when does the environment torn down and why is it useful for a user?

For example, some callback taking hook like onTimeout() makes it clear that the callback will be executed when test times out. There is no need to explain in what situation it is useful.

Just thinking out loud. Not sure if a hook is useful. From the issue it is not clear how the API could be used. That would help to shape it. @CreativeTechGuy could elaborate please? How do you see the usage?

Rough idea in my head (does AbortController make sense here?):

import {onTimeout} from '@jest/globals';

const ac = new AbortController();

onTimeout(() => {
  ac.abort();
  process.exitCode = 1;
});

---

EDIT Can be I am overthinking. A simple boolean like jest.timedOut might be enough.

[CreativeTechGuy]

@mrazauskas I love the thought process. I think this would need to be documented so it's clear what and why it is needed. I suspect that most often this will be used as a fix once someone has already seen the error:

ReferenceError: You are trying to access a property or method of the Jest environment after it has been torn down.

Since that error uses the term "environment torn down" that seems like a decent way to continue to refer to it. So maybe jest.isEnvironmentTornDown would be good. I like your thinking with the "timed out" verbage, but now someone would need to make the jump from getting that error message to know that what it really means is a timeout.

If I had to guess, a majority of users will never touch this. But now if someone does run into that error, they have the agency to do something about it. That seems like the most likely case to address.

One concern with an onTimeout hook is that it'll be used for all sorts of things which I'm not sure if that's a good pattern to encourage. Currently the on* callbacks in Jest are very common things that most people would need, so I'd assume that people would think they should be using this new one too. Maybe it is and that is something that has a ton of use-cases I've never thought of, but right now I cannot see any.

[SimenB]

https://github.com/facebook/jest/releases/tag/v29.4.0

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.