From 5f1047a660011866af18b197ca909fe4f97464ac Mon Sep 17 00:00:00 2001
From: Tom Mrazauskas <tom@mrazauskas.de>
Date: Tue, 5 Apr 2022 21:09:15 +0300
Subject: [PATCH] add upgrading guide

---
 docs/UpgradingGuide.md | 84 ++++++++++++++++++++++++++++++++++++++++++
 website/sidebars.json  |  3 ++
 2 files changed, 87 insertions(+)
 create mode 100644 docs/UpgradingGuide.md

diff --git a/docs/UpgradingGuide.md b/docs/UpgradingGuide.md
new file mode 100644
index 000000000000..95503176d640
--- /dev/null
+++ b/docs/UpgradingGuide.md
@@ -0,0 +1,84 @@
+---
+id: upgrading-guide
+title: From v27 to v28
+---
+
+Upgrading Jest from v27 to v28? This guide aims to help refactoring your tests.
+
+## Fake Timers
+
+Fake timers were refactored to allow passing options to the underlying [`@sinonjs/fake-timers`](https://github.com/sinonjs/fake-timers).
+
+### `fakeTimers`
+
+The `timers` configuration option was renamed to [`fakeTimers`](Configuration.md#faketimers-object) and now takes an object with options:
+
+```diff title="jest.config.js (default)"
+- timers: 'real'
++ fakeTimers: {
++   enableGlobally: false
++ }
+```
+
+```diff title="jest.config.js"
+- timers: 'fake'
++ fakeTimers: {
++   enableGlobally: true
++ }
+```
+
+```diff title="jest.config.js"
+- timers: 'modern'
++ fakeTimers: {
++   enableGlobally: true
++ }
+```
+
+```diff title="jest.config.js"
+- timers: 'legacy'
++ fakeTimers: {
++   enableGlobally: true,
++   legacyFakeTimers: true
++ }
+```
+
+### `jest.useFakeTimers()`
+
+An object with options now should be passed to [`jest.useFakeTimers()`](JestObjectAPI.md#jestusefaketimersfaketimersconfig) as well:
+
+```diff title="fakeTimers.test.js (default)"
+- jest.useFakeTimers('modern')
++ jest.useFakeTimers()
+```
+
+Or if legacy fake timers are enabled in Jest config file, but you would like to use the default fake timers backed by `@sinonjs/fake-timers`:
+
+```diff title="fakeTimers.test.js"
+- jest.useFakeTimers('modern')
++ jest.useFakeTimers({
++   legacyFakeTimers: false
++ })
+```
+
+```diff title="fakeTimers.test.js"
+- jest.useFakeTimers('legacy')
++ jest.useFakeTimers({
++   legacyFakeTimers: true
++ })
+```
+
+## Test Environment
+
+If you are using JSDOM [test environment](Configuration.md#testenvironment-string), `jest-environment-jsdom` package now must be installed additionally:
+
+```bash npm2yarn
+npm install --save-dev jest-environment-jsdom
+```
+
+## Test Runner
+
+If you are using Jasmine [test runner](Configuration.md#testrunner-string), `jest-jasmine2` package now must be installed additionally:
+
+```bash npm2yarn
+npm install --save-dev jest-jasmine2
+```
diff --git a/website/sidebars.json b/website/sidebars.json
index d40f62713a60..940df67f4ff5 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -32,6 +32,9 @@
       "tutorial-react",
       "tutorial-react-native",
       "testing-frameworks"
+    ],
+    "Upgrade Guides": [
+      "upgrading-guide"
     ]
   },
   "api": [