diff --git a/CHANGELOG.md b/CHANGELOG.md index beaa01e200d7..6a4b58b85a51 100644 --- a/CHANGELOG.md +++ b/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)) diff --git a/docs/Es6Import.md b/docs/Es6Import.md new file mode 100644 index 000000000000..71cf3fa32b64 --- /dev/null +++ b/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. diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index 7195b589b527..9cf572280d68 100644 --- a/docs/GettingStarted.md +++ b/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. diff --git a/docs/GlobalAPI.md b/docs/GlobalAPI.md index 125cf8558e77..3cea1ada8fb7 100644 --- a/docs/GlobalAPI.md +++ b/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 diff --git a/docs/JestObjectAPI.md b/docs/JestObjectAPI.md index 3873dc92328b..a4a38893d756 100644 --- a/docs/JestObjectAPI.md +++ b/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 diff --git a/packages/jest/src/__tests__/jest.js b/packages/jest/src/__tests__/jest.js new file mode 100644 index 000000000000..e2be9a2a7126 --- /dev/null +++ b/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); + }); + }); +}); diff --git a/packages/jest/src/jest.js b/packages/jest/src/jest.js index 64c046dcf264..591b55de24c9 100644 --- a/packages/jest/src/jest.js +++ b/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);