From 503766f512496c89a63fbc650fb75431d9c351d7 Mon Sep 17 00:00:00 2001
From: Andrew Smith <andrewsmith@alumni.stanford.edu>
Date: Wed, 25 Nov 2020 17:53:26 -0800
Subject: [PATCH 1/4] Clarify documentation of global nature of useFakeTimers.

---
 docs/TimerMocks.md | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/docs/TimerMocks.md b/docs/TimerMocks.md
index 5ab344ba81a2..ebc4a1f0ca1d 100644
--- a/docs/TimerMocks.md
+++ b/docs/TimerMocks.md
@@ -35,7 +35,26 @@ test('waits 1 second before ending the game', () => {
 });
 ```
 
-Here we enable fake timers by calling `jest.useFakeTimers();`. This mocks out setTimeout and other timer functions with mock functions. If running multiple tests inside of one file or describe block, `jest.useFakeTimers();` can be called before each test manually or with a setup function such as `beforeEach`. Not doing so will result in the internal usage counter not being reset.
+Here we enable fake timers by calling `jest.useFakeTimers()`. This mocks out `setTimeout` and other timer functions with mock functions. Timers can be restored to their normal behavior with `jest.useRealTimers()`.
+
+While you can call `jest.useFakeTimers()` or `jest.useRealTimers()` from anywhere (top level, inside an `it` block, etc.), it is a **global operation** and will affect other tests within the same file. Additionally, you need to call `jest.useFakeTimers()` to reset internal counters before each test. If you plan to not use fake timers in all your tests, you will want to clean up manually, as otherwise the faked timers will leak across tests:
+
+```javascript
+afterEach(() => {
+  jest.useRealTimers();
+});
+
+it('should do something with fake timers', () => {
+  jest.useFakeTimers();
+  // ...
+});
+
+it('should do something with real timers', () => {
+  // ...
+});
+```
+
+
 
 ## Run All Timers
 

From 477b3a1449aca58a3a67d8bc8442b00b32b0b839 Mon Sep 17 00:00:00 2001
From: Andrew Smith <andrewsmith@alumni.stanford.edu>
Date: Wed, 25 Nov 2020 17:58:30 -0800
Subject: [PATCH 2/4] Update CHANGELOG.

---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d1ef970e9e89..05dd59f9d5d3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -32,6 +32,7 @@
 - `[jest-resolve]` [**BREAKING**] Migrate to ESM ([#10688](https://github.com/facebook/jest/pull/10688))
 - `[jest-repl, jest-runtime]` [**BREAKING**] Move the `jest-runtime` CLI into `jest-repl` ([#10016](https://github.com/facebook/jest/pull/10016))
 - `[jest-util]` No longer checking `enumerable` when adding `process.domain` ([#10862](https://github.com/facebook/jest/pull/10862))
+- `[jest-fake-timers]` Clarify global behavior of `jest.useFakeTimers` and `jest.useRealTimers` ([#10867](https://github.com/facebook/jest/pull/10867))
 
 ### Performance
 

From 0443df4bb818b1cf59814ab4d3a2debabbe0aaae Mon Sep 17 00:00:00 2001
From: Andrew Smith <andrewsmith@alumni.stanford.edu>
Date: Wed, 25 Nov 2020 18:54:01 -0800
Subject: [PATCH 3/4] Run prettier.

---
 docs/TimerMocks.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/TimerMocks.md b/docs/TimerMocks.md
index ebc4a1f0ca1d..30046f8b3914 100644
--- a/docs/TimerMocks.md
+++ b/docs/TimerMocks.md
@@ -54,8 +54,6 @@ it('should do something with real timers', () => {
 });
 ```
 
-
-
 ## Run All Timers
 
 Another test we might want to write for this module is one that asserts that the callback is called after 1 second. To do this, we're going to use Jest's timer control APIs to fast-forward time right in the middle of the test:

From 3ce3540a9c40bb6cb1d33a55630e73dad2fca76a Mon Sep 17 00:00:00 2001
From: Andrew Smith <andrewsmith@alumni.stanford.edu>
Date: Wed, 25 Nov 2020 18:55:43 -0800
Subject: [PATCH 4/4] Use `test` instead of `it` to match rest of docs.

---
 docs/TimerMocks.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/TimerMocks.md b/docs/TimerMocks.md
index 30046f8b3914..5170e399a977 100644
--- a/docs/TimerMocks.md
+++ b/docs/TimerMocks.md
@@ -44,12 +44,12 @@ afterEach(() => {
   jest.useRealTimers();
 });
 
-it('should do something with fake timers', () => {
+test('do something with fake timers', () => {
   jest.useFakeTimers();
   // ...
 });
 
-it('should do something with real timers', () => {
+test('do something with real timers', () => {
   // ...
 });
 ```