Allow importing Jest as an ES6 module

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### Features
 
+- `[jest]` Export globals as an ES6 module ([./docs/Es6Import.md](./docs/Es6Import.md)).
 - `[jest-runtime]` Add `jest.isolateModules` for scoped module initialization ([#6701](https://github.com/facebook/jest/pull/6701))
 - `[jest-cli]` [**BREAKING**] Only set error process error codes when they are non-zero ([#7363](https://github.com/facebook/jest/pull/7363))
 - `[jest-config]` [**BREAKING**] Deprecate `setupTestFrameworkScriptFile` in favor of new `setupFilesAfterEnv` ([#7119](https://github.com/facebook/jest/pull/7119))

docs/Es6Import.md

@@ -0,0 +1,86 @@
+---
+id: es6-import
+title: ES6 Import
+---
+
+If you prefer the [Ava](https://ava.li/) approach of no polluting the global environment, Jest now supports importing as an ES6 module to avoid refering to global variables.
+
+This is completely optional. Everything is still usable the same as before. But if you have a code editor that complains when you use unrecognized globals, or you just prefer to use the ES6 module approach, you can now import anything that is already defined as a global.
+
+## Example
+
+Consider the following example:
+
+```js
+test('it works', () => {
+  expect('Hello, World!').toHaveLength(13);
+});
+```
+
+This can now be rewritten as:
+
+```js
+import jest from 'jest';
+
+jest.test('it works', () => {
+  jest.expect('Hello, World!').toHaveLength(13);
+});
+```
+
+## Reference
+
+```js
+import jest from 'jest';
+```
+
+The `jest` object now contains the following properties:
+
+```
+{
+  expect
+  afterAll
+  afterEach
+  beforeAll
+  beforeEach
+  describe
+  describe.each
+  describe.only
+  describe.only.each
+  describe.skip
+  describe.skip.each
+  test
+  test.each
+  test.only
+  test.only.each
+  test.skip
+  test.skip.each
+  clearAllTimers
+  disableAutomock
+  enableAutomock
+  fn
+  isMockFunction
+  genMockFromModule
+  mock
+  unmock
+  doMock
+  dontMock
+  clearAllMocks
+  resetAllMocks
+  restoreAllMocks
+  resetModules
+  retryTimes
+  runAllTicks
+  runAllTimers
+  advanceTimersByTime
+  runOnlyPendingTimers
+  requireActual
+  requireMock
+  setMock
+  setTimeout
+  useFakeTimers
+  useRealTimers
+  spyOn
+}
+```
+
+See [Expect API](ExpectAPI.md), [Global API](GlobalAPI.md), and [Jest Object API](JestObjectAPI.md) for more info.

docs/GettingStarted.md

@@ -57,6 +57,8 @@ PASS  ./sum.test.js
 
 This test used `expect` and `toBe` to test that two values were exactly identical. To learn about the other things that Jest can test, see [Using Matchers](UsingMatchers.md).
 
+If you prefer to import functions instead of using them globally, see [ES6 Import](Es6Import.md).
+
 ## Running from command line
 
 You can run Jest directly from the CLI (if it's globally available in your `PATH`, e.g. by `yarn global add jest` or `npm install jest --global`) with a variety of useful options.

docs/GlobalAPI.md

@@ -3,7 +3,7 @@ id: api
 title: Globals
 ---
 
-In your test files, Jest puts each of these methods and objects into the global environment. You don't have to require or import anything to use them.
+In your test files, Jest puts each of these methods and objects into the global environment. You don't have to require or import anything to use them (though they still can be [imported](Es6Import.md) if you prefer).
 
 ## Methods
 

docs/JestObjectAPI.md

@@ -3,7 +3,7 @@ id: jest-object
 title: The Jest Object
 ---
 
-The `jest` object is automatically in scope within every test file. The methods in the `jest` object help create mocks and let you control Jest's overall behavior.
+The `jest` object is automatically in scope within every test file (although it can also be imported as an [ES6 module](Es6Import.md)). The methods in the `jest` object help create mocks and let you control Jest's overall behavior.
 
 ## Mock Modules
 

packages/jest/src/__tests__/jest.js

@@ -0,0 +1,19 @@
+// Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+
+import jest from '../jest';
+
+const sum = (a, b) => a + b;
+
+describe('jest es6 import', () => {
+  jest.describe('jest.describe', () => {
+    jest.test('should work like global describe', () => {
+      jest.expect(sum(1, 2)).toBe(3);
+    });
+  });
+
+  jest.xdescribe('jest.xdescribe', () => {
+    jest.test('should be skipped just like global describe.skip', () => {
+      jest.expect(sum(1, 2)).toBe(3);
+    });
+  });
+});

packages/jest/src/jest.js

@@ -7,4 +7,20 @@
  * @flow
  */
 
-export {default} from 'jest-cli';
+import cli from 'jest-cli';
+
+const obj = {
+  ...jest,
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  fdescribe: describe.only,
+  it: test,
+  test,
+  xdescribe: describe.skip,
+};
+
+export default (process.env.JEST_WORKER_ID !== undefined ? obj : cli);