chore: update docs for fake timers (#11197)

Author: SimenB

CHANGELOG.md

@@ -9,7 +9,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-config, jest-runtime]` [**BREAKING**] Use "modern" implementation as default for fake timers ([#10874](https://github.com/facebook/jest/pull/10874) & [#11197](https://github.com/facebook/jest/pull/11197))
 - `[jest-core]` make `TestWatcher` extend `emittery` ([#10324](https://github.com/facebook/jest/pull/10324))
 - `[jest-core]` Run failed tests interactively the same way we do with snapshots ([#10858](https://github.com/facebook/jest/pull/10858))
 - `[jest-core]` more `TestSequencer` methods can be async ([#10980](https://github.com/facebook/jest/pull/10980))

docs/Configuration.md

@@ -1275,9 +1275,9 @@ This option sets the URL for the jsdom environment. It is reflected in propertie
 
 Default: `real`
 
-Setting this value to `legacy` or `fake` allows the use of fake timers for functions such as `setTimeout`. Fake timers are useful when a piece of code sets a long timeout that we don't want to wait for in a test.
+Setting this value to `fake` or `modern` allows the use of fake timers for functions such as `setTimeout`. Fake timers are useful when a piece of code sets a long timeout that we don't want to wait for in a test.
 
-If the value is `modern`, [`@sinonjs/fake-timers`](https://github.com/sinonjs/fake-timers) will be used as implementation instead of Jest's own legacy implementation. This will be the default fake implementation in Jest 27.
+If the value is `legacy`, the old implementation will be used as implementation instead of one backed by [`@sinonjs/fake-timers`](https://github.com/sinonjs/fake-timers).
 
 ### `transform` \[object<string, pathToTransformer | \[pathToTransformer, object]>]
 

e2e/__tests__/fakeTime.test.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import runJest from '../runJest';
+
+describe.each(['modern', 'legacy'])(
+  '%s implementation of fake timers',
+  implementation => {
+    it('should be possible to use from config', () => {
+      const result = runJest(`fake-time/${implementation}/from-config`);
+      expect(result.exitCode).toBe(0);
+    });
+
+    it('should be possible to use from jest-object', () => {
+      const result = runJest(`fake-time/${implementation}/from-jest-object`);
+      expect(result.exitCode).toBe(0);
+    });
+  },
+);

e2e/fake-time/legacy/from-config/__tests__/test.js

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+test('fake timers', () => {
+  expect(() => jest.setSystemTime(0)).toThrow(
+    'setSystemTime is not available when not using modern timers',
+  );
+});

e2e/fake-time/legacy/from-config/package.json

@@ -0,0 +1,6 @@
+{
+  "jest": {
+    "timers": "legacy",
+    "testEnvironment": "node"
+  }
+}

e2e/fake-time/legacy/from-jest-object/__tests__/test.js

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+test('fake timers', () => {
+  jest.useFakeTimers('legacy');
+
+  expect(() => jest.setSystemTime(0)).toThrow(
+    'setSystemTime is not available when not using modern timers',
+  );
+});

e2e/fake-time/legacy/from-jest-object/package.json

@@ -0,0 +1,5 @@
+{
+  "jest": {
+    "testEnvironment": "node"
+  }
+}

e2e/fake-time/modern/from-config/__tests__/test.js

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+test('fake timers', () => {
+  jest.setSystemTime(0);
+
+  expect(Date.now()).toBe(0);
+
+  jest.setSystemTime(1000);
+
+  expect(Date.now()).toBe(1000);
+});

e2e/fake-time/modern/from-config/package.json

@@ -0,0 +1,6 @@
+{
+  "jest": {
+    "timers": "fake",
+    "testEnvironment": "node"
+  }
+}

e2e/fake-time/modern/from-jest-object/__tests__/test.js

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+test('fake timers', () => {
+  jest.useFakeTimers();
+
+  jest.setSystemTime(0);
+
+  expect(Date.now()).toBe(0);
+
+  jest.setSystemTime(1000);
+
+  expect(Date.now()).toBe(1000);
+});