Add Global Setup/Teardown APIs

CHANGELOG.md

@@ -18,6 +18,7 @@
 * `[jest-resolve]` Preserve module identity for symlinks ([#4761](https://github.com/facebook/jest/pull/4761))
 
 ### Features
+* `[jest-config]` Add Global Setup/Teardown options ([#4716](https://github.com/facebook/jest/pull/4716))
 * `[jest-environment-*]` [**BREAKING**] Add Async Test Environment APIs, dispose is now teardown ([#4506](https://github.com/facebook/jest/pull/4506))
 * `[jest-cli]` Add an option to clear the cache ([#4430](https://github.com/facebook/jest/pull/4430))
 * `[babel-plugin-jest-hoist]` Improve error message, that the second argument of `jest.mock` must be an inline function ([#4593](https://github.com/facebook/jest/pull/4593))

docs/Configuration.md

@@ -170,6 +170,16 @@ For example, the following would create a global `__DEV__` variable set to `true
 
 Note that, if you specify a global reference value (like an object or array) here, and some code mutates that value in the midst of running a test, that mutation will *not* be persisted across test runs for other test files.
 
+### `globalSetup` [string]
+Default: `undefined`
+
+This option allows the use of a custom global setup module which exports an async function that is triggered once before all test suites.
+
+### `globalTeardown` [string]
+Default: `undefined`
+
+This option allows the use of a custom global teardown module which exports an async function that is triggered once after all test suites.
+
 ### `mapCoverage` [boolean]
 
 ##### available in Jest **20.0.0+**

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

@@ -66,6 +66,8 @@ exports[`--showConfig outputs config info and exits 1`] = `
       \\"clover\\"
     ],
     \\"expand\\": false,
+    \\"globalSetup\\": null,
+    \\"globalTeardown\\": null,
     \\"listTests\\": false,
     \\"mapCoverage\\": false,
     \\"maxWorkers\\": \\"[maxWorkers]\\",

integration_tests/__tests__/global_setup.test.js

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. 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.
+ * @flow
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const runJest = require('../runJest');
+const {cleanup} = require('../utils');
+
+const DIR = path.join(os.tmpdir(), '/jest');
+
+beforeEach(() => cleanup(DIR));
+afterAll(() => cleanup(DIR));
+
+test('globalSetup is triggered once before all test suites', () => {
+  const path = require('path');
+  const setupPath = path.resolve(__dirname, '../global_setup/setup.js');
+  const result = runJest.json('global_setup', [`--globalSetup=${setupPath}`]);
+  expect(result.status).toBe(0);
+  const files = fs.readdirSync(DIR);
+  expect(files).toHaveLength(1);
+  const setup = fs.readFileSync(path.join(DIR, '/', files[0]), 'utf8');
+  expect(setup).toBe('setup');
+});

integration_tests/__tests__/global_teardown.test.js

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. 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.
+ * @flow
+ */
+'use strict';
+
+const fs = require('fs');
+const mkdirp = require('mkdirp');
+const os = require('os');
+const path = require('path');
+const runJest = require('../runJest');
+const {cleanup} = require('../utils');
+
+const DIR = path.join(os.tmpdir(), '/jest');
+
+beforeEach(() => cleanup(DIR));
+afterAll(() => cleanup(DIR));
+
+test('globalTeardown is triggered once after all test suites', () => {
+  mkdirp.sync(DIR);
+  const path = require('path');
+  const teardownPath = path.resolve(
+    __dirname,
+    '../global_teardown/teardown.js',
+  );
+  const result = runJest.json('global_teardown', [
+    `--globalTeardown=${teardownPath}`,
+  ]);
+  expect(result.status).toBe(0);
+  const files = fs.readdirSync(DIR);
+  expect(files).toHaveLength(1);
+  const teardown = fs.readFileSync(path.join(DIR, '/', files[0]), 'utf8');
+  expect(teardown).toBe('teardown');
+});

integration_tests/global_setup/__tests__/setup1.test.js

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. 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';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DIR = path.join(os.tmpdir(), '/jest');
+
+test('should exist setup file', () => {
+  const files = fs.readdirSync(DIR);
+  expect(files).toHaveLength(1);
+  const setup = fs.readFileSync(path.join(DIR, '/', files[0]), 'utf8');
+  expect(setup).toBe('setup');
+});

integration_tests/global_setup/__tests__/setup2.test.js

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. 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';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DIR = path.join(os.tmpdir(), '/jest');
+
+test('should exist setup file', () => {
+  const files = fs.readdirSync(DIR);
+  expect(files).toHaveLength(1);
+  const setup = fs.readFileSync(path.join(DIR, '/', files[0]), 'utf8');
+  expect(setup).toBe('setup');
+});

integration_tests/global_setup/__tests__/setup3.test.js

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. 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';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DIR = path.join(os.tmpdir(), '/jest');
+
+test('should exist setup file', () => {
+  const files = fs.readdirSync(DIR);
+  expect(files).toHaveLength(1);
+  const setup = fs.readFileSync(path.join(DIR, '/', files[0]), 'utf8');
+  expect(setup).toBe('setup');
+});

integration_tests/global_setup/package.json

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

integration_tests/global_setup/setup.js

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. 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.
+ */
+const crypto = require('crypto');
+const fs = require('fs');
+const mkdirp = require('mkdirp');
+const os = require('os');
+const path = require('path');
+
+const DIR = path.join(os.tmpdir(), '/jest');
+
+module.exports = function() {
+  return new Promise((resolve, reject) => {
+    mkdirp.sync(DIR);
+    const fileId = crypto.randomBytes(20).toString('hex');
+    fs.writeFileSync(path.join(DIR, '/', fileId), 'setup');
+    resolve();
+  });
+};

integration_tests/global_teardown/__tests__/teardown1.test.js

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. 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';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DIR = path.join(os.tmpdir(), '/jest');
+
+test('should not exist teardown file', () => {
+  const files = fs.readdirSync(DIR);
+  expect(files).toHaveLength(0);
+});

integration_tests/global_teardown/__tests__/teardown2.test.js

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. 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';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DIR = path.join(os.tmpdir(), '/jest');
+
+test('should not exist teardown file', () => {
+  const files = fs.readdirSync(DIR);
+  expect(files).toHaveLength(0);
+});

integration_tests/global_teardown/__tests__/teardown3.test.js

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. 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';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DIR = path.join(os.tmpdir(), '/jest');
+
+test('should not exist teardown file', () => {
+  const files = fs.readdirSync(DIR);
+  expect(files).toHaveLength(0);
+});

integration_tests/global_teardown/package.json

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

integration_tests/global_teardown/teardown.js

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. 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.
+ */
+const crypto = require('crypto');
+const fs = require('fs');
+const mkdirp = require('mkdirp');
+const os = require('os');
+const path = require('path');
+
+const DIR = path.join(os.tmpdir(), '/jest');
+
+module.exports = function() {
+  return new Promise((resolve, reject) => {
+    mkdirp.sync(DIR);
+    const fileId = crypto.randomBytes(20).toString('hex');
+    fs.writeFileSync(path.join(DIR, '/', fileId), 'teardown');
+    resolve();
+  });
+};

packages/jest-cli/src/cli/args.js

@@ -231,6 +231,14 @@ export const options = {
       'adequately cleaned up.',
     type: 'boolean',
   },
+  globalSetup: {
+    description: 'The path to a module that runs before All Tests.',
+    type: 'string',
+  },
+  globalTeardown: {
+    description: 'The path to a module that runs after All Tests.',
+    type: 'string',
+  },
   globals: {
     description:
       'A JSON string with map of global variables that need ' +

packages/jest-cli/src/run_jest.js

@@ -94,6 +94,10 @@ export default async function runJest({
   changedFilesPromise: ?ChangedFilesPromise,
   onComplete: (testResults: AggregatedResult) => any,
 }) {
+  if (globalConfig.globalSetup) {
+    // $FlowFixMe
+    await require(globalConfig.globalSetup)();
+  }
   const sequencer = new TestSequencer();
   let allTests = [];
   const testRunData = await Promise.all(
@@ -161,6 +165,10 @@ export default async function runJest({
 
   sequencer.cacheResults(allTests, results);
 
+  if (globalConfig.globalTeardown) {
+    // $FlowFixMe
+    await require(globalConfig.globalTeardown)();
+  }
   return processResults(results, {
     isJSON: globalConfig.json,
     onComplete,

packages/jest-config/src/defaults.js

@@ -37,6 +37,8 @@ export default ({
   coveragePathIgnorePatterns: [NODE_MODULES_REGEXP],
   coverageReporters: ['json', 'text', 'lcov', 'clover'],
   expand: false,
+  globalSetup: null,
+  globalTeardown: null,
   globals: {},
   haste: {
     providesModuleNodeModules: [],

packages/jest-config/src/index.js

@@ -84,6 +84,8 @@ const getConfigs = (
       expand: options.expand,
       findRelatedTests: options.findRelatedTests,
       forceExit: options.forceExit,
+      globalSetup: options.globalSetup,
+      globalTeardown: options.globalTeardown,
       json: options.json,
       lastCommit: options.lastCommit,
       listTests: options.listTests,

packages/jest-config/src/normalize.js

@@ -452,6 +452,8 @@ export default function normalize(options: InitialOptions, argv: Argv) {
       case 'coverageThreshold':
       case 'displayName':
       case 'expand':
+      case 'globalSetup':
+      case 'globalTeardown':
       case 'globals':
       case 'findRelatedTests':
       case 'forceExit':

test_utils.js

@@ -23,6 +23,8 @@ const DEFAULT_GLOBAL_CONFIG: GlobalConfig = {
   expand: false,
   findRelatedTests: false,
   forceExit: false,
+  globalSetup: null,
+  globalTeardown: null,
   json: false,
   lastCommit: false,
   listTests: false,

types/Argv.js

@@ -33,6 +33,8 @@ export type Argv = {|
   expand: boolean,
   findRelatedTests: boolean,
   forceExit: boolean,
+  globalSetup: ?string,
+  globalTeardown: ?string,
   globals: string,
   h: boolean,
   haste: string,

types/Config.js

@@ -32,6 +32,8 @@ export type DefaultOptions = {|
   coverageReporters: Array<string>,
   expand: boolean,
   globals: ConfigGlobals,
+  globalSetup: ?string,
+  globalTeardown: ?string,
   haste: HasteConfig,
   mapCoverage: boolean,
   moduleDirectories: Array<string>,
@@ -83,6 +85,8 @@ export type InitialOptions = {
   forceExit?: boolean,
   json?: boolean,
   globals?: ConfigGlobals,
+  globalSetup?: ?string,
+  globalTeardown?: ?string,
   haste?: HasteConfig,
   reporters?: Array<ReporterConfig | string>,
   logHeapUsage?: boolean,
@@ -155,6 +159,8 @@ export type GlobalConfig = {|
   findRelatedTests: boolean,
   forceExit: boolean,
   json: boolean,
+  globalSetup: ?string,
+  globalTeardown: ?string,
   lastCommit: boolean,
   logHeapUsage: boolean,
   listTests: boolean,