From a29710ddf5fe123a967403eecb0d26a1ba06a718 Mon Sep 17 00:00:00 2001 From: Dorian Marchal Date: Sun, 3 Mar 2019 18:11:48 +0100 Subject: [PATCH] Improve runAllTimers doc (it exhausts the micro-task queue) Updates `jest.runAllTimers()` documentation to state that it also exhausts the micro-task queue (this is the case since commit 9d17ea9). --- CHANGELOG.md | 1 + docs/JestObjectAPI.md | 4 ++-- website/versioned_docs/version-22.x/JestObjectAPI.md | 4 ++-- website/versioned_docs/version-23.x/JestObjectAPI.md | 4 ++-- website/versioned_docs/version-24.0/JestObjectAPI.md | 4 ++-- 5 files changed, 9 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9d328e2a912c..56050928e790 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -78,6 +78,7 @@ - `[jest-validate]`: Migrate to TypeScript ([#7991](https://github.com/facebook/jest/pull/7991)) - `[docs]`: Update CONTRIBUTING.md to add information about running jest with `jest-circus` locally ([#8013](https://github.com/facebook/jest/pull/8013)). - `[@jest/core]`: Migrate to TypeScript ([#7998](https://github.com/facebook/jest/pull/7998)) +- `[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.