Fake promises for fake timers

CHANGELOG.md

@@ -3,15 +3,17 @@
 ### Fixes
 
 - `[jest-cli]` Fix incorrect `testEnvironmentOptions` warning ([#6852](https://github.com/facebook/jest/pull/6852))
-- `[jest-each`] Prevent done callback being supplied to describe ([#6843](https://github.com/facebook/jest/pull/6843))
-- `[jest-config`] Better error message for a case when a preset module was found, but no `jest-preset.js` or `jest-preset.json` at the root ([#6863](https://github.com/facebook/jest/pull/6863))
+- `[jest-each]` Prevent done callback being supplied to describe ([#6843](https://github.com/facebook/jest/pull/6843))
+- `[jest-config]` Better error message for a case when a preset module was found, but no `jest-preset.js` or `jest-preset.json` at the root ([#6863](https://github.com/facebook/jest/pull/6863))
+- `[jest-util]` Introduce FakePromises to fix micro-task run-order issues when using FakeTimers. ([#6876](https://github.com/facebook/jest/pull/6876))
 
 ### Chore & Maintenance
 
 - `[docs]` Add custom toMatchSnapshot matcher docs ([#6837](https://github.com/facebook/jest/pull/6837))
 - `[docs]` Improve the documentation regarding preset configuration ([#6864](https://github.com/facebook/jest/issues/6864))
 - `[docs]` Clarify usage of `--projects` CLI option ([#6872](https://github.com/facebook/jest/pull/6872))
 - `[docs]` Correct `failure-change` notification mode ([#6878](https://github.com/facebook/jest/pull/6878))
+- `[docs]` Add documentation for promise mocks, and clarify how micro-tasks behave when using timer mocks. ([#6876](https://github.com/facebook/jest/pull/6876))
 
 ## 23.5.0
 

TestUtils.js

@@ -91,6 +91,7 @@ const DEFAULT_PROJECT_CONFIG: ProjectConfig = {
   modulePaths: [],
   name: 'test_name',
   prettierPath: 'prettier',
+  promises: 'real',
   resetMocks: false,
   resetModules: false,
   resolver: null,

docs/Configuration.md

@@ -467,6 +467,12 @@ The projects feature can also be used to run multiple configurations or multiple
 
 _Note: When using multi project runner, it's recommended to add a `displayName` for each project. This will show the `displayName` of a project next to its tests._
 
+### `promises` [string]
+
+Default: `real`
+
+Setting this value to `fake` allows the use of fake promises to replace the `Promise` class introduced in ecma-script2015 specification. Fake promises are useful for synchronizing promises, or for use with Jest's fake timers feature.
+
 ### `reporters` [array<moduleName | [moduleName, options]>]
 
 Default: `undefined`

docs/JestObjectAPI.md

@@ -22,13 +22,16 @@ The `jest` object is automatically in scope within every test file. The methods
 - [`jest.restoreAllMocks()`](#jestrestoreallmocks)
 - [`jest.resetModules()`](#jestresetmodules)
 - [`jest.retryTimes()`](#jestretrytimes)
+- [`jest.runAllPromises(runAllTicks)`](#jestrunallpromises)
 - [`jest.runAllTicks()`](#jestrunallticks)
 - [`jest.runAllTimers()`](#jestrunalltimers)
 - [`jest.advanceTimersByTime(msToRun)`](#jestadvancetimersbytimemstorun)
 - [`jest.runOnlyPendingTimers()`](#jestrunonlypendingtimers)
 - [`jest.setMock(moduleName, moduleExports)`](#jestsetmockmodulename-moduleexports)
 - [`jest.setTimeout(timeout)`](#jestsettimeouttimeout)
+- [`jest.useFakePromises()`](#jestusefakepromises)
 - [`jest.useFakeTimers()`](#jestusefaketimers)
+- [`jest.useRealPromises()`](#jestuserealpromises)
 - [`jest.useRealTimers()`](#jestuserealtimers)
 - [`jest.spyOn(object, methodName)`](#jestspyonobject-methodname)
 - [`jest.spyOn(object, methodName, accessType?)`](#jestspyonobject-methodname-accesstype)
@@ -344,11 +347,19 @@ module.exports = {
 
 Returns the `jest` object for chaining.
 
+### `jest.runAllPromises(runAllTicks)`
+
+Exhausts the **micro**-task queue (`process.nextTick` callbacks and promises scheduled via the `Promise` class).
+
+Uses the provided `runAllTicks` callback to exhaust all ticks that are currently queued. Fake promises should be in use (by calling `jest.useFakePromises` ) before calling this method.
+
+This is useful for synchronously executing scheduled promises and ticks in the order in their natural run order in node.
+
 ### `jest.runAllTicks()`
 
-Exhausts the **micro**-task queue (usually interfaced in node via `process.nextTick`).
+Exhausts all scheduled next tick callbacks (usually interfaced in node via `process.nextTick`).
 
-When this API is called, all pending micro-tasks that have been queued via `process.nextTick` will be executed. Additionally, if those micro-tasks themselves schedule new micro-tasks, those will be continually exhausted until there are no more micro-tasks remaining in the queue.
+When this API is called, all pending next tick callbacks that have been queued via `process.nextTick` will be executed. Additionally, if those micro-tasks themselves schedule new micro-tasks, those will be continually exhausted until there are no more micro-tasks remaining in the queue. See the (Promise Mocks)(PromiseMocks.md) doc for more information.
 
 ### `jest.runAllTimers()`
 
@@ -404,12 +415,24 @@ Example:
 jest.setTimeout(1000); // 1 second
 ```
 
+### `jest.useFakePromises()`
+
+Instructs Jest to use fake versions of the standard Promise API (`Promise.resolve`, `Promise.reject`, `Promise.all`, `Promise.race`, `[Promise].then`, `[Promise].catch`, and `[Promise].finally`).
+
+Returns the `jest` object for chaining.
+
 ### `jest.useFakeTimers()`
 
 Instructs Jest to use fake versions of the standard timer functions (`setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`, `nextTick`, `setImmediate` and `clearImmediate`).
 
 Returns the `jest` object for chaining.
 
+### `jest.useRealPromises()`
+
+Instructs Jest to use the real versions of the standard Promise API.
+
+Returns the `jest` object for chaining.
+
 ### `jest.useRealTimers()`
 
 Instructs Jest to use the real versions of the standard timer functions.

docs/PromiseMocks.md

@@ -0,0 +1,54 @@
+---
+id: promise-mocks
+title: Promise Mocks
+---
+
+Can be used to supplement the [timer mocks](TimerMocks.md). Timer mocks work by running timer callbacks synchronously, in the same order they normally would, but without waiting. Promise mocks can be used with timer mocks to skip wait times and still run node micro-tasks and macro-tasks in the order they normally would.
+
+```javascript
+// promiseGame.js
+'use strict';
+
+function promiseGame(callback) {
+  console.log('Ready....go!');
+  Promise.resolve(0).then(() => {
+    console.log('Promise is fulfilled -- stop!');
+    callback && callback();
+  });
+}
+
+module.exports = promiseGame;
+```
+
+```javascript
+// __tests__/promiseGame.js
+'use strict';
+
+jest.useFakePromises();
+
+test('runs all queued promises', () => {
+  const promiseGame = require('../promiseGame');
+  const callback = jest.fn();
+  const runAllTicks = jest.fn();
+
+  promiseGame(callback);
+
+  // At this point, the promise callback should not have been called yet
+  expect(callback).not.toBeCalled();
+
+  // Fast-forward until all promises are completed
+  jest.runAllPromises(runAllTicks);
+
+  // Now our callback should have been called!
+  expect(callback).toBeCalled();
+  expect(callback).toHaveBeenCalledTimes(1);
+
+  // Check that all ticks have been run
+  expect(runAllTicks).toBeCalled();
+  expect(runAllTicks).toHaveBeenCalledTimes(1);
+});
+```
+
+Here we enable fake promises by calling `jest.useFakePromises();`. This mocks out the Promise class and its entire API. `jest.runAllPromises();` is used to synchronously run all queued promises
+
+The timer mock API uses a promise mock delegate to run all queued promises and nextTick callbacks if fake promises are being used.

e2e/__tests__/__snapshots__/show_config.test.js.snap

@@ -34,6 +34,7 @@ exports[`--showConfig outputs config info and exits 1`] = `
       \\"modulePathIgnorePatterns\\": [],
       \\"name\\": \\"[md5 hash]\\",
       \\"prettierPath\\": null,
+      \\"promises\\": \\"real\\",
       \\"resetMocks\\": false,
       \\"resetModules\\": false,
       \\"resolver\\": null,

examples/promise/.babelrc

@@ -0,0 +1,3 @@
+{
+	"presets": ["env"]
+}

examples/promise/__tests__/promise_game.test.js

@@ -0,0 +1,27 @@
+'use strict';
+
+jest.useFakePromises();
+
+describe('promiseGame', () => {
+  it('runs all queued promises', () => {
+    const promiseGame = require('../promiseGame');
+    const callback = jest.fn();
+    const runAllTicks = jest.fn();
+
+    promiseGame(callback);
+
+    // At this point, the promise callback should not have been called yet
+    expect(callback).not.toBeCalled();
+
+    // Fast-forward until all promises are completed
+    jest.runAllPromises(runAllTicks);
+
+    // Now our callback should have been called!
+    expect(callback).toBeCalled();
+    expect(callback.mock.calls.length).toBe(1);
+
+    // Check that all ticks have been run
+    expect(runAllTicks).toBeCalled();
+    expect(runAllTicks.mock.calls.length).toBeGreaterThan(0);
+  });
+});

examples/promise/package.json

@@ -0,0 +1,12 @@
+{
+  "private": true,
+  "version": "0.0.0",
+  "name": "example-promise",
+  "devDependencies": {
+    "babel-preset-env": "*",
+    "jest": "*"
+  },
+  "scripts": {
+    "test": "jest"
+  }
+}

examples/promise/promiseGame.js

@@ -0,0 +1,9 @@
+function promiseGame(callback) {
+  console.log('Ready....go!');
+  Promise.resolve(0).then(() => {
+    console.log('Promise is fulfilled -- stop!');
+    callback && callback();
+  });
+}
+
+module.exports = promiseGame;

packages/jest-circus/src/legacy_code_todo_rewrite/jest_adapter.js

@@ -51,6 +51,10 @@ const jestAdapter = async (
     environment.fakeTimers.useFakeTimers();
   }
 
+  if (config.promises === 'fake') {
+    environment.fakePromises.useFakePromises();
+  }
+
   globals.beforeEach(() => {
     if (config.resetModules) {
       runtime.resetModules();
@@ -66,6 +70,10 @@ const jestAdapter = async (
       if (config.timers === 'fake') {
         environment.fakeTimers.useFakeTimers();
       }
+
+      if (config.promises === 'fake') {
+        environment.fakePromises.useFakePromises();
+      }
     }
 
     if (config.restoreMocks) {

packages/jest-config/src/Defaults.js

@@ -51,6 +51,7 @@ export default ({
   preset: null,
   prettierPath: 'prettier',
   projects: null,
+  promises: 'real',
   resetMocks: false,
   resetModules: false,
   resolver: null,

packages/jest-config/src/index.js

@@ -174,6 +174,7 @@ const getConfigs = (
     modulePaths: options.modulePaths,
     name: options.name,
     prettierPath: options.prettierPath,
+    promises: options.promises,
     resetMocks: options.resetMocks,
     resetModules: options.resetModules,
     resolver: options.resolver,

packages/jest-environment-jsdom/src/__mocks__/index.js

@@ -14,6 +14,7 @@ JSDOMEnvironment.mockImplementation(function(config) {
   this.global = {
     JSON,
     console: {},
+    mockClearPromises: jest.fn(),
     mockClearTimers: jest.fn(),
   };
 

packages/jest-environment-jsdom/src/index.js

@@ -12,12 +12,13 @@ import type {EnvironmentOptions} from 'types/Environment';
 import type {Global} from 'types/Global';
 import type {ModuleMocker} from 'jest-mock';
 
-import {FakeTimers, installCommonGlobals} from 'jest-util';
+import {FakePromises, FakeTimers, installCommonGlobals} from 'jest-util';
 import mock from 'jest-mock';
 import {JSDOM, VirtualConsole} from 'jsdom';
 
 class JSDOMEnvironment {
   dom: ?Object;
+  fakePromises: ?FakePromises;
   fakeTimers: ?FakeTimers<number>;
   global: ?Global;
   errorEventListener: ?Function;
@@ -77,8 +78,14 @@ class JSDOMEnvironment {
       refToId: (ref: number) => ref,
     };
 
+    this.fakePromises = new FakePromises({
+      config,
+      global,
+    });
+
     this.fakeTimers = new FakeTimers({
       config,
+      fakePromises: this.fakePromises,
       global,
       moduleMocker: this.moduleMocker,
       timerConfig,
@@ -90,6 +97,9 @@ class JSDOMEnvironment {
   }
 
   teardown(): Promise<void> {
+    if (this.fakePromises) {
+      this.fakePromises.dispose();
+    }
     if (this.fakeTimers) {
       this.fakeTimers.dispose();
     }
@@ -104,6 +114,7 @@ class JSDOMEnvironment {
     this.errorEventListener = null;
     this.global = null;
     this.dom = null;
+    this.fakePromises = null;
     this.fakeTimers = null;
     return Promise.resolve();
   }

packages/jest-environment-node/src/index.js

@@ -13,7 +13,7 @@ import type {Global} from 'types/Global';
 import type {ModuleMocker} from 'jest-mock';
 
 import vm from 'vm';
-import {FakeTimers, installCommonGlobals} from 'jest-util';
+import {FakePromises, FakeTimers, installCommonGlobals} from 'jest-util';
 import mock from 'jest-mock';
 
 type Timer = {|
@@ -24,6 +24,7 @@ type Timer = {|
 
 class NodeEnvironment {
   context: ?vm$Context;
+  fakePromises: ?FakePromises;
   fakeTimers: ?FakeTimers<Timer>;
   global: ?Global;
   moduleMocker: ?ModuleMocker;
@@ -65,8 +66,14 @@ class NodeEnvironment {
       refToId: timerRefToId,
     };
 
+    this.fakePromises = new FakePromises({
+      config,
+      global,
+    });
+
     this.fakeTimers = new FakeTimers({
       config,
+      fakePromises: this.fakePromises,
       global,
       moduleMocker: this.moduleMocker,
       timerConfig,
@@ -78,10 +85,14 @@ class NodeEnvironment {
   }
 
   teardown(): Promise<void> {
+    if (this.fakePromises) {
+      this.fakePromises.dispose();
+    }
     if (this.fakeTimers) {
       this.fakeTimers.dispose();
     }
     this.context = null;
+    this.fakePromises = null;
     this.fakeTimers = null;
     return Promise.resolve();
   }

packages/jest-jasmine2/src/index.js

@@ -71,6 +71,10 @@ async function jasmine2(
     environment.fakeTimers.useFakeTimers();
   }
 
+  if (config.promises === 'fake') {
+    environment.fakePromises.useFakePromises();
+  }
+
   env.beforeEach(() => {
     if (config.resetModules) {
       runtime.resetModules();
@@ -86,6 +90,10 @@ async function jasmine2(
       if (config.timers === 'fake') {
         environment.fakeTimers.useFakeTimers();
       }
+
+      if (config.promises === 'fake') {
+        environment.fakePromises.useFakePromises();
+      }
     }
 
     if (config.restoreMocks) {