jest-doctor 0.1.0 → 0.1.2

package/dist/createEnvMixin.d.ts

@@ -38,12 +38,12 @@ declare const createEnvMixin: <EnvironmentConstructor extends JestDoctorConstruc
                 (str: Uint8Array | string, encoding?: BufferEncoding, cb?: (err?: Error | null) => void): boolean;
             };
             console: {
-                log: (message?: any, ...optionalParams: any[]) => void;
-                info: (message?: any, ...optionalParams: any[]) => void;
-                warn: (message?: any, ...optionalParams: any[]) => void;
-                error: (message?: any, ...optionalParams: any[]) => void;
-                debug: (message?: any, ...optionalParams: any[]) => void;
-                trace: (message?: any, ...optionalParams: any[]) => void;
+                log: (...data: any[]) => void;
+                info: (...data: any[]) => void;
+                warn: (...data: any[]) => void;
+                error: (...data: any[]) => void;
+                debug: (...data: any[]) => void;
+                trace: (...data: any[]) => void;
             };
         };
         readonly promiseOwner: Map<number, string>;

package/dist/createEnvMixin.js

@@ -55,8 +55,10 @@ const createEnvMixin = (Environment) => {
                 processOutputs: 0,
             };
             const tmpDir = (0, getReporterTmpDir_1.default)(config.projectConfig.reporters || config.globalConfig.reporters);
+            const isWorker = typeof process.send === 'function';
+            const seed = (isWorker ? process.ppid : process.pid).toString();
             this.reporterTmpDir = tmpDir
-                ? node_path_1.default.join(tmpDir, config.globalConfig.seed.toString(), this.testPath + 'json')
+                ? node_path_1.default.join(tmpDir, seed, this.testPath + '.json')
                 : '';
             this.options = (0, normalizeOptions_1.default)(config.projectConfig.testEnvironmentOptions);
             (0, initLeakRecord_1.default)(this, consts_1.MAIN_THREAD);

package/dist/env/jsdom.d.ts

@@ -16,17 +16,17 @@ declare const _default: {
                 (str: Uint8Array | string, encoding?: BufferEncoding, cb?: (err?: Error | null) => void): boolean;
             };
             console: {
-                log: (message?: any, ...optionalParams: any[]) => void;
-                info: (message?: any, ...optionalParams: any[]) => void;
-                warn: (message?: any, ...optionalParams: any[]) => void;
-                error: (message?: any, ...optionalParams: any[]) => void;
-                debug: (message?: any, ...optionalParams: any[]) => void;
-                trace: (message?: any, ...optionalParams: any[]) => void;
+                log: (...data: any[]) => void;
+                info: (...data: any[]) => void;
+                warn: (...data: any[]) => void;
+                error: (...data: any[]) => void;
+                debug: (...data: any[]) => void;
+                trace: (...data: any[]) => void;
             };
         };
         readonly promiseOwner: Map<number, string>;
-        readonly asyncHookDetector?: import("async_hooks").AsyncHook;
-        readonly asyncHookCleaner?: import("async_hooks").AsyncHook;
+        readonly asyncHookDetector?: import("node:async_hooks").AsyncHook;
+        readonly asyncHookCleaner?: import("node:async_hooks").AsyncHook;
         readonly options: import("../types").NormalizedOptions;
         seenTearDown: boolean;
         currentAfterEachCount: number;
@@ -53,7 +53,7 @@ declare const _default: {
         fakeTimers: import("@jest/fake-timers").LegacyFakeTimers<unknown> | null;
         fakeTimersModern: import("@jest/fake-timers").ModernFakeTimers | null;
         moduleMocker: import("jest-mock").ModuleMocker | null;
-        getVmContext: () => import("vm").Context | null;
+        getVmContext: () => import("node:vm").Context | null;
         exportConditions: (() => Array<string>) | undefined;
     };
 } & import("../createEnvMixin").JestDoctorConstructor;

package/dist/env/node.d.ts

@@ -16,17 +16,17 @@ declare const _default: {
                 (str: Uint8Array | string, encoding?: BufferEncoding, cb?: (err?: Error | null) => void): boolean;
             };
             console: {
-                log: (message?: any, ...optionalParams: any[]) => void;
-                info: (message?: any, ...optionalParams: any[]) => void;
-                warn: (message?: any, ...optionalParams: any[]) => void;
-                error: (message?: any, ...optionalParams: any[]) => void;
-                debug: (message?: any, ...optionalParams: any[]) => void;
-                trace: (message?: any, ...optionalParams: any[]) => void;
+                log: (...data: any[]) => void;
+                info: (...data: any[]) => void;
+                warn: (...data: any[]) => void;
+                error: (...data: any[]) => void;
+                debug: (...data: any[]) => void;
+                trace: (...data: any[]) => void;
             };
         };
         readonly promiseOwner: Map<number, string>;
-        readonly asyncHookDetector?: import("async_hooks").AsyncHook;
-        readonly asyncHookCleaner?: import("async_hooks").AsyncHook;
+        readonly asyncHookDetector?: import("node:async_hooks").AsyncHook;
+        readonly asyncHookCleaner?: import("node:async_hooks").AsyncHook;
         readonly options: import("../types").NormalizedOptions;
         seenTearDown: boolean;
         currentAfterEachCount: number;
@@ -53,7 +53,7 @@ declare const _default: {
         fakeTimers: import("@jest/fake-timers").LegacyFakeTimers<unknown> | null;
         fakeTimersModern: import("@jest/fake-timers").ModernFakeTimers | null;
         moduleMocker: import("jest-mock").ModuleMocker | null;
-        getVmContext: () => import("vm").Context | null;
+        getVmContext: () => import("node:vm").Context | null;
         exportConditions: (() => Array<string>) | undefined;
     };
 } & import("../createEnvMixin").JestDoctorConstructor;

package/dist/patch/createAsyncHookCleaner.d.ts

@@ -1,3 +1,3 @@
 import type { JestDoctorEnvironment } from '../types';
-declare const createAsyncHookCleaner: (that: JestDoctorEnvironment) => import("async_hooks").AsyncHook;
+declare const createAsyncHookCleaner: (that: JestDoctorEnvironment) => import("node:async_hooks").AsyncHook;
 export default createAsyncHookCleaner;

package/dist/patch/createAsyncHookDetector.d.ts

@@ -1,3 +1,3 @@
 import { JestDoctorEnvironment } from '../types';
-declare const createAsyncHookDetector: (that: JestDoctorEnvironment) => import("async_hooks").AsyncHook;
+declare const createAsyncHookDetector: (that: JestDoctorEnvironment) => import("node:async_hooks").AsyncHook;
 export default createAsyncHookDetector;

package/dist/patch/fakeTimers.js

@@ -16,7 +16,7 @@ const patchFakeTimers = (that) => {
             const originalFakeSetInterval = env.setInterval.bind(env);
             const originalFakeClearTimeout = env.clearTimeout.bind(env);
             const originalFakeClearInterval = env.clearInterval.bind(env);
-            env.setTimeout = function (callback, delay) {
+            env.setTimeout = Object.assign(function (callback, delay) {
                 const fakeTimeout = that.leakRecords.get(that.currentTestName)?.fakeTimers;
                 const timerId = originalFakeSetTimeout(() => {
                     fakeTimeout?.delete(timerId);
@@ -31,8 +31,8 @@ const patchFakeTimers = (that) => {
                     });
                 }
                 return timerId;
-            };
-            env.setInterval = function (callback, delay) {
+            }, env.setTimeout);
+            env.setInterval = Object.assign(function (callback, delay) {
                 const intervalId = originalFakeSetInterval(callback, delay);
                 const stack = (0, getStack_1.default)(that.global.setInterval);
                 if (!(0, isIgnored_1.default)(stack, that.options.report.fakeTimers.ignore)) {
@@ -45,17 +45,17 @@ const patchFakeTimers = (that) => {
                     });
                 }
                 return intervalId;
-            };
-            env.clearTimeout = (timerId) => {
+            }, env.setInterval);
+            env.clearTimeout = Object.assign((timerId) => {
                 that.leakRecords.get(that.currentTestName)?.fakeTimers.delete(timerId);
                 originalFakeClearTimeout(timerId);
-            };
-            env.clearInterval = (intervalId) => {
+            }, env.clearTimeout);
+            env.clearInterval = Object.assign((intervalId) => {
                 that.leakRecords
                     .get(that.currentTestName)
                     ?.fakeTimers.delete(intervalId);
                 originalFakeClearInterval(intervalId);
-            };
+            }, env.clearInterval);
         };
         const originalClearAllTimers = api.clearAllTimers.bind(api);
         api.clearAllTimers = () => {

package/dist/patch/promiseConcurrency.js

@@ -5,11 +5,11 @@ const patchPromiseConcurrency = (that) => {
     const env = that.global;
     const getRootIds = () => {
         let triggerId = (0, node_async_hooks_1.executionAsyncId)();
-        const rootIds = [triggerId];
-        while (triggerId !== that.asyncRoot && triggerId) {
-            triggerId = that.asyncIdToParentId.get(triggerId);
+        const rootIds = [];
+        do {
             rootIds.push(triggerId);
-        }
+            triggerId = that.asyncIdToParentId.get(triggerId);
+        } while (triggerId && triggerId !== that.asyncRoot);
         return rootIds;
     };
     const cleanPromise = (promises, promise, asyncId) => {

package/dist/reporter.d.ts

@@ -8,9 +8,7 @@ declare class JestDoctorReporter implements Reporter {
     private readonly reportDir;
     private readonly pidDir;
     private readonly keep;
-    constructor(globalConfig: {
-        seed: number;
-    }, options: ReporterOptions);
+    constructor(_: object, options: ReporterOptions);
     onRunComplete(): Promise<void>;
 }
 export default JestDoctorReporter;

package/dist/reporter.js

@@ -56,12 +56,13 @@ class JestDoctorReporter {
     reportDir;
     pidDir;
     keep;
-    constructor(globalConfig, options) {
-        const seed = globalConfig.seed.toString();
+    constructor(_, options) {
+        const seed = process.pid.toString();
         this.tmpDir = options.tmpDir || consts_1.REPORTER_TMP_DIR;
         this.keep = options.keep || false;
         this.reportDir = node_path_1.default.join(this.tmpDir, seed);
         this.pidDir = node_path_1.default.join(this.tmpDir, 'pid');
+        (0, node_fs_1.rmSync)(this.reportDir, { recursive: true, force: true });
         (0, node_fs_1.mkdirSync)(this.pidDir, { recursive: true });
         (0, node_fs_1.mkdirSync)(this.reportDir, { recursive: true });
         if (!this.keep) {

package/dist/utils/getStack.js

@@ -9,8 +9,7 @@ const getStack = (stackFrom) => {
     lines.shift();
     const finalStack = [];
     for (const line of lines) {
-        if (/[/\\]/.test(line) && // this will remove all anonymous frames without a path
-            !line.includes('(node:internal/') &&
+        if (!line.includes('(node:internal/') &&
             !line.includes('node_modules/jest-runtime') &&
             !line.includes('node_modules/jest-circus') &&
             !line.includes('node_modules/jest-runner') &&

package/dist/utils/initOriginal.d.ts

@@ -12,12 +12,12 @@ declare const initOriginal: () => {
         (str: Uint8Array | string, encoding?: BufferEncoding, cb?: (err?: Error | null) => void): boolean;
     };
     console: {
-        log: (message?: any, ...optionalParams: any[]) => void;
-        info: (message?: any, ...optionalParams: any[]) => void;
-        warn: (message?: any, ...optionalParams: any[]) => void;
-        error: (message?: any, ...optionalParams: any[]) => void;
-        debug: (message?: any, ...optionalParams: any[]) => void;
-        trace: (message?: any, ...optionalParams: any[]) => void;
+        log: (...data: any[]) => void;
+        info: (...data: any[]) => void;
+        warn: (...data: any[]) => void;
+        error: (...data: any[]) => void;
+        debug: (...data: any[]) => void;
+        trace: (...data: any[]) => void;
     };
 };
 export default initOriginal;

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "jest-doctor",
-  "version": "0.1.0",
-  "description": "jest environment for leak detection",
+  "version": "0.1.2",
+  "description": "jest environment for leak and issue detection",
   "license": "MIT",
   "author": "Stephan Dum",
   "type": "commonjs",
   "homepage": "https://github.com/stephan-dum/jest-doctor",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/stephan-dum/jest-doctor.git"
+    "url": "git+https://github.com/stephan-dum/jest-doctor.git",
+    "directory": "packages/jest-doctor"
   },
   "exports": {
     "./package.json": "./package.json",
@@ -26,7 +27,10 @@
     "jest-doctor",
     "leak detection",
     "open handles",
-    "testing"
+    "issue detection",
+    "testing",
+    "jest environment",
+    "test hygien"
   ],
   "types": "./dist/types.d.ts",
   "devDependencies": {
@@ -37,11 +41,11 @@
     "@swc/jest": "^0.2.39",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.1",
+    "@testing-library/react": "^16.3.2",
     "@types/cross-spawn": "^6.0.6",
     "@types/jest": "30.0.0",
-    "@types/node": "24.3.3",
-    "@types/react": "^19.2.8",
+    "@types/node": "^25.0.10",
+    "@types/react": "^19.2.9",
     "@types/react-dom": "^19.2.3",
     "c8": "^10.1.3",
     "cross-spawn": "^7.0.6",
@@ -49,12 +53,12 @@
     "jest": "30.2.0",
     "jest-environment-jsdom": "^30.2.0",
     "jest-environment-node": "^30.2.0",
-    "memfs": "^4.52.0",
+    "memfs": "^4.56.10",
     "nyc": "^17.1.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "ts-jest": "^29.4.6",
-    "typescript": "5.9.2"
+    "typescript": "5.9.3"
   },
   "peerDependencies": {
     "jest-environment-jsdom": "*",
@@ -70,7 +74,7 @@
   },
   "dependencies": {
     "chalk": "4.1.2",
-    "zod": "^4.3.5"
+    "zod": "^4.3.6"
   },
   "scripts": {
     "typecheck": "tsc",
@@ -80,6 +84,6 @@
     "test:unit": "jest --coverage",
     "test:matrix": "node ./e2e/runMatrix.mjs",
     "test": "yarn matrix && yarn test:unit && yarn coverage:merge",
-    "coverage:merge": "nyc report --reporter html --reporter text"
+    "coverage:merge": "nyc report"
   }
 }

package/readme.md

@@ -1,165 +1,302 @@
-# jest-doctor
-
-**jest-doctor** is a custom Jest environment that **detects async leaks and test isolation bugs**.
-
-It fails tests deterministically when they:
-- Leave unresolved Promises
-- leave open (fake) timers or intervals
-- Use real timers or intervals and their total delay reach a certain threshold
-- Emit console output
-
-Jest-doctor is intentionally strict. If your test leaks async work, that is a bug, even if Jest normally ignores it.
-
-## Installation
-
-```bash
-npm install --save-dev jest-doctor
-```
-or
-```bash
-yarn add -D jest-doctor
-```
-
-## Usage
-
-Add one of the provided environments to your `jest.config.js`, in addition, the reporter provides a list ordered by severity and a total count overview.
-
-```js
-export default {
-  testEnvironment: 'jest-doctor/env/node',
-  // optional
-  reporters: ['default', 'jest-doctor/reporter']
-};
-```
-
-Out-of-the-box jest-doctor supports node and jsdom environments. But you can also [build your own environment](./docs/build_your_own_environment.md).
-
-### Configuration
-
-The environment can be configured through jest config `testEnvironmentOptions`:
-- **report**: an object defining which leaks should be tracked and reported
-  - **timers**: `false` or object (default: object)
-    - **onError**: `'warn' | 'throw'` (default `throw`) whether normal setTimeout and setInterval should be reported and how
-    - **ignore**: `string | regexp | Array<string | regexp>` (default: []) allows to excluded timers from tracking if the stack trace matches
-  - **fakeTimers**: `false'` or object (default object)
-    - **onError**: `'warn' | 'throw'` (default `throw`) same as timers but for fake api
-    - **ignore**: `string | regexp | Array<string | regexp>` (default: []) same as timers but for fake api
-  - **promises**: `false'` (default object)
-    - **onError**: `'warn' | 'throw'` (default `throw`) indicating if promises should be reported and how
-    - **ignore**: `string | regexp | Array<string | regexp>` (default: []) same as timers but for promises
-  - **console**: `false` or object (default object)
-    - **onError**: `'warn' | 'throw'` (default `throw`) how to handle reporting
-    - **methods**: `keyof Console` (default all methods) which console methods should be tracked
-    - **ignore**: `string | regexp | Array<string | regexp>` (default: []) same as timers but for console output
-  - **processOutputs**: `false` or object (default to object)
-    - **onError**: `'warn' | 'throw'` (default `throw`) how to handle reporting
-    - **methods**: `Array<stderr | stdout>` (default all methods) which process output methods should be tracked
-    - **ignore**: `string | regexp | Array<string | regexp>` (default: []) same as timers but for process output
-- **timerIsolation**: `'afterEach' | 'immediate'` (default: `'afterEach'`)
-  - **immediate**: report and clear timers directly after each test / hook block
-  - **afterEach**: `beforeAll`, `beforeEach` and `afterAll` are immediate but `test` and `afterEach` block defer reporting and cleanup until the last `afterEach` block is executed (or directly after the test if there are no `afterEach` blocks). This allows an easier clean up for example react testing framework registers an unmount function in an `afterEach` block to clean up.
-- **delayThreshold**: `number` (default: `0`) the delay in milliseconds of all `setTimeout` and `setInterval` callback that get executed is add up. If this the sum is higher then the threshold at the end when reporting an error is throw, otherwise a warning is logged.
-- **clearTimers**: `boolean` (default: `true`) whether to clear all timers base on `timerIsolation`
-
-here is an example how the configuration could look like:
-```js
-export default {
-  testEnvironmentOptions: {
-    report: {
-      console: {
-        onError: 'warn',
-        methods: ["log", "warn", "error"],
-        ignore: /Third party message/,
-      },
-      timers: {
-        onError: 'warn',
-      },
-      fakeTimers: {
-        onError: 'throw'
-      },
-      promises:  false,
-    },
-    delayThreshold: 1000,
-    timerIsolation: 'afterEach',
-    clearTimers: true,
-  },
-};
-```
-
-the reporter can be configured by the standard jest reporter config syntax
-- **tmpDir**: `string` (default: `.tmp`) where to store reports from the environment to be read by the reporter
-
-```js
-export default {
-  reporters: [
-    'default',
-    ['jest-doctor/reporter', { tmpDir: 'custom-dir' }]
-  ],
-}
-```
-
-## Limitations
-- it.concurrent is replaced with a sync version
-- test and hook blocks do not support done callback or generators
-- promises that resolve within the next tick cannot be tracked, for example:
-```js
-Promise.resolve().then(() => {
-  /* i am not tracked as unresolved */
-});
-```
-- Promise.race, Promise.any and Promise.all do not support nested blocks.
-```js
-const doSomething = async () => {
-  // both promises will be tracked and never released
-  await someAsyncTask();
-  return new Promise(() => { setTimeout(resolve, 10)})
-};
-
-const p1 = Promise.resolve()
-  .then(() => { /* no problem if not async */});
-
-const p2 = Promise.resolve()
-  .then(() => new Promise((resolve) => {
-    /* the promise will be also always tracked */
-    resolve();
-  }));
-
-await Promise.race([p1, p2, doSomething()]);
-```
-
--  setTimeout / setInterval can also be imported and will not participate in leak detection in these cases, but this can also serve as exit hatch if needed.
-```js
-import { setTimeout, setInterval } from 'node:timers';
-```
-
-
-## Recommendations
-- use eslint to
-  - detect floating promises
-  - disallow setTimeout / setInterval in test files
-  - disallow console usage
-- do only mock console / process output per test not globally, to avoid missing out on errors that are thrown in silence
-- enable fake timers globally in config (be aware that there might be some issues ie axe needs real timers)
-```js
-afterEach(async () => {
-  jest.useRealTimers();
-  await axe();
-  jest.useFakeTimers();
-});
-```
-
-## Tested against
-- Jest 27, 28, 29, 30
-- node 22, 24
-
-# FAQ
-
-### Why is jest-doctor so strict?
-Because flaky tests cost more than broken builds.
-
-### Does this slow tests down?
-Slightly. Overhead is intentional and bounded.
-
-### Why does console output fail tests?
-It pollutes the console and is often a strong indicator that something is wrong.
-Tests should always spy on console and assert on the output.
+# jest-doctor [![main](https://github.com/stephan-dum/jest-doctor/actions/workflows/main.yml/badge.svg)](https://github.com/stephan-dum/jest-doctor/actions/workflows/main.yml) [![codecov](https://codecov.io/gh/stephan-dum/jest-doctor/branch/main/graph/badge.svg)](https://codecov.io/gh/stephan-dum/jest-doctor) [![npm version](https://img.shields.io/npm/v/jest-doctor.svg)](https://www.npmjs.com/package/jest-doctor) [![License](https://img.shields.io/npm/l/jest-doctor.svg)](./LICENSE)
+
+jest-doctor is a custom Jest environment that fails tests deterministically
+when [async work leaks](#what-is-an-async-leak) across test boundaries.
+It prevents flaky tests and enforces strong test hygiene.
+
+## ✨ What problems does it catch?
+
+It detects and reports when tests:
+- Leave unresolved Promises
+- Leave open real or fake timers
+- Rely on excessive real-time delays
+- Emit process / console outputs
+
+---
+**Docs**
+
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Reporter](#reporter)
+- [When not to use jest-doctor](#when-not-to-use-jest-doctor)
+- [Limitations](#limitations)
+- [FAQ](#faq)
+- [Migration](./docs/migration.md)
+
+---
+## 🚀 Quick Start
+
+```bash
+npm install --save-dev jest-doctor
+```
+
+or
+
+```bash
+yarn add -D jest-doctor
+```
+
+Add one of the provided environments to your `jest.config.js`.
+
+```js
+export default {
+  testEnvironment: 'jest-doctor/env/node',
+  // optional
+  reporters: ['default', 'jest-doctor/reporter'],
+};
+```
+
+Out-of-the-box jest-doctor supports node and jsdom environments. But you can also [build your own environment](./docs/build_your_own_environment.md).
+
+---
+## ⚙️ Configuration
+
+The environment can be configured through the Jest config `testEnvironmentOptions`:
+
+
+```js
+export default {
+  testEnvironmentOptions: {
+    report: {
+      console: {
+        onError: 'warn',
+        methods: ['log', 'warn', 'error'],
+        ignore: /Third party message/,
+      },
+      timers: {
+        onError: 'warn',
+      },
+      fakeTimers: {
+        onError: 'throw',
+      },
+      promises: false,
+      processOutputs: {
+        onError: 'warn',
+        methods: ['stderr'],
+      },
+    },
+    delayThreshold: 1000,
+    timerIsolation: 'afterEach',
+    clearTimers: true,
+  },
+};
+```
+
+### report
+Controls which leak types are detected and how they are reported.
+
+Each option can be:
+- false → disabled
+- object → enabled with configuration
+
+Common options:
+- **onError**: `'warn' | 'throw'` (default: `'throw'`)
+- ignore: `string | RegExp | Array<string | RegExp>` (default: `[]`)
+  If the stack trace or emitted message matches, the leak is ignored.
+
+#### possible report options
+
+- **timers:** track real timers
+- **fakeTimers:** track fake timers
+- **promises:** track not awaited promises
+- **console:** track console output
+  - **methods:** `Array<keyof Console>` (default: all) which console methods should be tracked
+- **processOutputs:** track process output
+  - **methods:** `Array<'stderr' | 'stdout'>` (default: both) which process output methods should be tracked
+
+###  timerIsolation
+Controls when timers are validated and cleared.
+
+**afterEach** (default)
+`beforeAll`, `beforeEach` and `afterAll` are still immediate but `test` / `it` and `afterEach` block defer reporting and cleanup until the last `afterEach` block is executed (or directly after the test if there are no `afterEach` blocks).
+
+```
+beforeAll  → check
+beforeEach → check
+test       → defer
+afterEach  → defer
+afterEach  → final check
+afterAll   → check
+```
+
+This allows easier cleanup., for example react testing framework registers an unmount function in an `afterEach` block to clean up.
+The disadvantage of this method is that it can happen that in an afterEach block a long-running task is executed and while running it timers resolve unnoticed.
+
+**immediate**
+timers are checked **after** each test / hook block
+```
+beforeAll  → check
+beforeEach → check
+test       → check
+afterEach  → check
+afterAll   → check
+```
+Use when tests should clean up immediately.
+
+### delayThreshold
+`number` (default: `0`)
+
+The delay in milliseconds of all `setTimeout` and `setInterval` callback that get executed is added up.
+If the sum is higher than the threshold, an error is thrown; otherwise a warning is logged.
+This feature should helps to detect tests that accidentally rely on real time.
+
+### clearTimers
+`boolean` (default: `true`)
+
+Whether timers should be cleared automatically based on `timerIsolation`.
+
+### verbose
+`boolean` (default: `false`)
+
+Jest often hides stack traces and files are not clickable.
+Also it is only possible to report one error type at a time.
+This option will print all errors with the related stack traces.
+
+---
+## 📊 Reporter
+
+The reporter aggregates leaks across all test environments and prints:
+
+- Total number of leaks
+- Grouped by type (timers, promises, console, etc.)
+- Ordered by severity
+
+The environment writes temporary reports to disk and the reporter reads them.
+
+The reporter can be configured by the standard jest reporter config syntax
+
+Options:
+
+
+- **tmpDir**: `string` (default: `.tmp`) Directory used to exchange data between environment and reporter.
+
+```js
+export default {
+  reporters: ['default', ['jest-doctor/reporter', { tmpDir: 'custom-dir' }]],
+};
+```
+
+---
+## ⚠️ Limitations
+
+### No it.concurrent
+Concurrent tests cannot be isolated reliably. jest-doctor replaces them with
+a synchronous version to guarantee deterministic cleanup.
+
+### No done callbacks or generators
+Since this is also a legacy pattern, it is not supported to avoid unnecessary complexity.
+
+## Results are inconsistent
+Promises are handled differently depending on the OS and node version.
+This means the report will always look a bit different depending on the environment.
+
+### Microtasks resolving in same tick are not tracked
+This is a JavaScript limitation, not specific to jest-doctor.
+```js
+Promise.resolve().then(() => {
+  /* i am not tracked as unresolved */
+});
+```
+
+### Concurrent promise combinators with nested async are problematic
+`Promise.race`, `Promise.any`, `Promise.all` cannot safely untrack nested async:
+
+```js
+const doSomething = async () => {
+  // both promises will be tracked and never released
+  await someAsyncTask();
+  return new Promise(() => {
+    setTimeout(resolve, 10);
+  });
+};
+
+const p1 = Promise.resolve().then(() => {
+  /* no problem if not async */
+});
+
+const p2 = Promise.resolve().then(
+  () =>
+    new Promise((resolve) => {
+      /* this promise will be also always tracked */
+      resolve();
+    }),
+);
+
+await Promise.race([p1, p2, doSomething()]);
+```
+
+### Imported timers bypass tracking
+These timers are not intercepted. This can also be used as an escape hatch.
+```js
+import { setTimeout, setInterval } from 'node:timers';
+```
+
+---
+## 🚫 When not to use jest-doctor
+- Heavy integration tests with background workers
+- Tests relying on long-running real timers
+- Legacy test suites using callback-based async
+
+In such cases, consider selectively disabling checks or using ignore rules.
+
+---
+## 💡 Recommendations
+
+- Use ESLint to
+  - detect floating promises
+  - disallow setTimeout / setInterval in tests
+  - disallow console usage
+- Only mock console / process output *per test* not globally, to avoid missing out on errors that are thrown in silence
+- Enable fake timers globally in config (be aware that there might be some issues ie axe needs real timers)
+
+```js
+afterEach(async () => {
+  jest.useRealTimers();
+  await axe();
+  jest.useFakeTimers();
+});
+```
+
+---
+## 🧪 Tested Against
+
+This project is tested against the following combinations:
+- **jest**: 28, 29, 30
+- **node**: 20, 22, 24
+
+---
+# ❓ FAQ
+
+### How to migrate an existing project?
+
+Please read the [migration guide](./docs/migration.md).
+
+### Why is jest-doctor so strict?
+
+Because flaky tests cost more than broken builds.
+
+### Does this slow tests down?
+
+Slightly. Overhead is intentional and bounded.
+
+### What is an async leak?
+
+An async leak happens when a test starts asynchronous work but does not
+properly wait for or clean it up. This can:
+
+- Interfere with later tests
+- Cause flaky failures
+- Hide real bugs
+
+
+### Why does console output fail tests?
+
+In the best case it just pollutes the console.
+In the worst case a real bug is logged but ignored.
+Thats why tests should always spy on console and assert on the output.
+The [react example](./e2e/fixtures/react.fixture.tsx#L20-L25) shows a common problem that can be caught by tests that mock console correctly.
+
+---
+
+If jest-doctor helped you eliminate flaky tests, consider ⭐ starring the repo —
+it helps others discover the project and motivates continued development.