feat: use modern fake timers by default

CHANGELOG.md

@@ -5,6 +5,7 @@
 - `[jest-config]` [**BREAKING**] Default to Node testing environment instead of browser (JSDOM) ([#9874](https://github.com/facebook/jest/pull/9874))
 - `[jest-config]` [**BREAKING**] Use `jest-circus` as default test runner ([#10686](https://github.com/facebook/jest/pull/10686))
 - `[jest-config, jest-runtime]` Support ESM for files other than `.js` and `.mjs` ([#10823](https://github.com/facebook/jest/pull/10823))
+- `[jest-config, jest-runtime]` [**BREAKING**] Use "modern" implementation as default for fake timers ([#10874](https://github.com/facebook/jest/pull/10874))
 - `[jest-repl, jest-runner]` [**BREAKING**] Run transforms over environment ([#8751](https://github.com/facebook/jest/pull/8751))
 - `[jest-runner]` [**BREAKING**] set exit code to 1 if test logs after teardown ([#10728](https://github.com/facebook/jest/pull/10728))
 - `[jest-snapshot]` [**BREAKING**] Make prettier optional for inline snapshots - fall back to string replacement ([#7792](https://github.com/facebook/jest/pull/7792))

docs/JestObjectAPI.md

@@ -582,9 +582,9 @@ Restores all mocks back to their original value. Equivalent to calling [`.mockRe
 
 ### `jest.useFakeTimers(implementation?: 'modern' | 'legacy')`
 
-Instructs Jest to use fake versions of the standard timer functions (`setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`, `nextTick`, `setImmediate` and `clearImmediate`).
+Instructs Jest to use fake versions of the standard timer functions (`setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`, `nextTick`, `setImmediate` and `clearImmediate` as well as `Date`).
 
-If you pass `'modern'` as an argument, [`@sinonjs/fake-timers`](https://github.com/sinonjs/fake-timers) will be used as implementation instead of Jest's own fake timers. This also mocks additional timers like `Date`. `'modern'` will be the default behavior in Jest 27.
+If you pass `'legacy'` as an argument, Jest's legacy implementation will be used rather than one based on [`@sinonjs/fake-timers`](https://github.com/sinonjs/fake-timers).
 
 Returns the `jest` object for chaining.
 

packages/jest-circus/src/legacy-code-todo-rewrite/jestAdapter.ts

@@ -41,11 +41,11 @@ const jestAdapter = async (
     testPath,
   });
 
-  if (config.timers === 'fake' || config.timers === 'legacy') {
+  if (config.timers === 'fake' || config.timers === 'modern') {
     // during setup, this cannot be null (and it's fine to explode if it is)
-    environment.fakeTimers!.useFakeTimers();
-  } else if (config.timers === 'modern') {
     environment.fakeTimersModern!.useFakeTimers();
+  } else if (config.timers === 'legacy') {
+    environment.fakeTimers!.useFakeTimers();
   }
 
   globals.beforeEach(() => {
@@ -60,7 +60,7 @@ const jestAdapter = async (
     if (config.resetMocks) {
       runtime.resetAllMocks();
 
-      if (config.timers === 'fake') {
+      if (config.timers === 'legacy') {
         // during setup, this cannot be null (and it's fine to explode if it is)
         environment.fakeTimers!.useFakeTimers();
       }

packages/jest-jasmine2/src/index.ts

@@ -86,10 +86,10 @@ export default async function jasmine2(
   environment.global.describe.skip = environment.global.xdescribe;
   environment.global.describe.only = environment.global.fdescribe;
 
-  if (config.timers === 'fake' || config.timers === 'legacy') {
-    environment.fakeTimers!.useFakeTimers();
-  } else if (config.timers === 'modern') {
+  if (config.timers === 'fake' || config.timers === 'modern') {
     environment.fakeTimersModern!.useFakeTimers();
+  } else if (config.timers === 'legacy') {
+    environment.fakeTimers!.useFakeTimers();
   }
 
   env.beforeEach(() => {
@@ -104,7 +104,7 @@ export default async function jasmine2(
     if (config.resetMocks) {
       runtime.resetAllMocks();
 
-      if (config.timers === 'fake' || config.timers === 'legacy') {
+      if (config.timers === 'legacy') {
         environment.fakeTimers!.useFakeTimers();
       }
     }

packages/jest-runtime/src/index.ts

@@ -243,9 +243,9 @@ export default class Runtime {
     this._transitiveShouldMock = new Map();
 
     this._fakeTimersImplementation =
-      config.timers === 'modern'
-        ? this._environment.fakeTimersModern
-        : this._environment.fakeTimers;
+      config.timers === 'legacy'
+        ? this._environment.fakeTimers
+        : this._environment.fakeTimersModern;
 
     this._unmockList = unmockRegExpCache.get(config);
     if (!this._unmockList && config.unmockedModulePathPatterns) {
@@ -1558,11 +1558,11 @@ export default class Runtime {
 
       return this._fakeTimersImplementation!;
     };
-    const useFakeTimers = (type: string = 'legacy') => {
-      if (type === 'modern') {
-        this._fakeTimersImplementation = this._environment.fakeTimersModern;
-      } else {
+    const useFakeTimers = (type: string = 'modern') => {
+      if (type === 'legacy') {
         this._fakeTimersImplementation = this._environment.fakeTimers;
+      } else {
+        this._fakeTimersImplementation = this._environment.fakeTimersModern;
       }
       this._fakeTimersImplementation!.useFakeTimers();
       return jestObject;