diff --git a/CHANGELOG.md b/CHANGELOG.md index 02a4ee7443f6..5d052ed31b14 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -80,6 +80,7 @@ - `[@jest/core]`: Migrate to TypeScript ([#7998](https://github.com/facebook/jest/pull/7998)) - `[@jest/source-map]`: Extract `getCallsite` function from `jest-util` into a new separate package ([#8029](https://github.com/facebook/jest/pull/8029)) - `[@jest/console]`: Extract custom `console` implementations from `jest-util` into a new separate package ([#8030](https://github.com/facebook/jest/pull/8030)) +- `[docs]`: Improve runAllTimers doc (it exhausts the micro-task queue) ([#8031](https://github.com/facebook/jest/pull/8031)) ### Performance diff --git a/docs/JestObjectAPI.md b/docs/JestObjectAPI.md index 3873dc92328b..4b4fea15dfed 100644 --- a/docs/JestObjectAPI.md +++ b/docs/JestObjectAPI.md @@ -428,9 +428,9 @@ When this API is called, all pending micro-tasks that have been queued via `proc ### `jest.runAllTimers()` -Exhausts the **macro**-task queue (i.e., all tasks queued by `setTimeout()`, `setInterval()`, and `setImmediate()`). +Exhausts both the **macro**-task queue (i.e., all tasks queued by `setTimeout()`, `setInterval()`, and `setImmediate()`) and the **micro**-task queue (usually interfaced in node via `process.nextTick`). -When this API is called, all pending "macro-tasks" that have been queued via `setTimeout()` or `setInterval()` will be executed. Additionally if those macro-tasks themselves schedule new macro-tasks, those will be continually exhausted until there are no more macro-tasks remaining in the queue. +When this API is called, all pending macro-tasks and micro-tasks will be executed. If those tasks themselves schedule new tasks, those will be continually exhausted until there are no more tasks remaining in the queue. This is often useful for synchronously executing setTimeouts during a test in order to synchronously assert about some behavior that would only happen after the `setTimeout()` or `setInterval()` callbacks executed. See the [Timer mocks](TimerMocks.md) doc for more information. diff --git a/website/versioned_docs/version-22.x/JestObjectAPI.md b/website/versioned_docs/version-22.x/JestObjectAPI.md index 0e2a82382fa3..4fda2af835ba 100644 --- a/website/versioned_docs/version-22.x/JestObjectAPI.md +++ b/website/versioned_docs/version-22.x/JestObjectAPI.md @@ -323,9 +323,9 @@ When this API is called, all pending micro-tasks that have been queued via `proc ### `jest.runAllTimers()` -Exhausts the **macro**-task queue (i.e., all tasks queued by `setTimeout()`, `setInterval()`, and `setImmediate()`). +Exhausts both the **macro**-task queue (i.e., all tasks queued by `setTimeout()`, `setInterval()`, and `setImmediate()`) and the **micro**-task queue (usually interfaced in node via `process.nextTick`). -When this API is called, all pending "macro-tasks" that have been queued via `setTimeout()` or `setInterval()` will be executed. Additionally if those macro-tasks themselves schedule new macro-tasks, those will be continually exhausted until there are no more macro-tasks remaining in the queue. +When this API is called, all pending macro-tasks and micro-tasks will be executed. If those tasks themselves schedule new tasks, those will be continually exhausted until there are no more tasks remaining in the queue. This is often useful for synchronously executing setTimeouts during a test in order to synchronously assert about some behavior that would only happen after the `setTimeout()` or `setInterval()` callbacks executed. See the [Timer mocks](TimerMocks.md) doc for more information. diff --git a/website/versioned_docs/version-23.x/JestObjectAPI.md b/website/versioned_docs/version-23.x/JestObjectAPI.md index 939a7db441fa..e14aaaa58717 100644 --- a/website/versioned_docs/version-23.x/JestObjectAPI.md +++ b/website/versioned_docs/version-23.x/JestObjectAPI.md @@ -339,9 +339,9 @@ When this API is called, all pending micro-tasks that have been queued via `proc ### `jest.runAllTimers()` -Exhausts the **macro**-task queue (i.e., all tasks queued by `setTimeout()`, `setInterval()`, and `setImmediate()`). +Exhausts both the **macro**-task queue (i.e., all tasks queued by `setTimeout()`, `setInterval()`, and `setImmediate()`) and the **micro**-task queue (usually interfaced in node via `process.nextTick`). -When this API is called, all pending "macro-tasks" that have been queued via `setTimeout()` or `setInterval()` will be executed. Additionally if those macro-tasks themselves schedule new macro-tasks, those will be continually exhausted until there are no more macro-tasks remaining in the queue. +When this API is called, all pending macro-tasks and micro-tasks will be executed. If those tasks themselves schedule new tasks, those will be continually exhausted until there are no more tasks remaining in the queue. This is often useful for synchronously executing setTimeouts during a test in order to synchronously assert about some behavior that would only happen after the `setTimeout()` or `setInterval()` callbacks executed. See the [Timer mocks](TimerMocks.md) doc for more information. diff --git a/website/versioned_docs/version-24.0/JestObjectAPI.md b/website/versioned_docs/version-24.0/JestObjectAPI.md index f1d1cdc6ca45..3ab253e66d6a 100644 --- a/website/versioned_docs/version-24.0/JestObjectAPI.md +++ b/website/versioned_docs/version-24.0/JestObjectAPI.md @@ -429,9 +429,9 @@ When this API is called, all pending micro-tasks that have been queued via `proc ### `jest.runAllTimers()` -Exhausts the **macro**-task queue (i.e., all tasks queued by `setTimeout()`, `setInterval()`, and `setImmediate()`). +Exhausts both the **macro**-task queue (i.e., all tasks queued by `setTimeout()`, `setInterval()`, and `setImmediate()`) and the **micro**-task queue (usually interfaced in node via `process.nextTick`). -When this API is called, all pending "macro-tasks" that have been queued via `setTimeout()` or `setInterval()` will be executed. Additionally if those macro-tasks themselves schedule new macro-tasks, those will be continually exhausted until there are no more macro-tasks remaining in the queue. +When this API is called, all pending macro-tasks and micro-tasks will be executed. If those tasks themselves schedule new tasks, those will be continually exhausted until there are no more tasks remaining in the queue. This is often useful for synchronously executing setTimeouts during a test in order to synchronously assert about some behavior that would only happen after the `setTimeout()` or `setInterval()` callbacks executed. See the [Timer mocks](TimerMocks.md) doc for more information.