Setup before tests but after framework loads

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### Features
 
+- `[jest-config]` [**BREAKING**] Deprecate `setupTestFrameworkScriptFile` in favor of new `setupFilesAfterEnv` ([#7119](https://github.com/facebook/jest/pull/7119))
 - `[jest-jasmine2/jest-circus/jest-cli]` Add test.todo ([#6996](https://github.com/facebook/jest/pull/6996))
 - `[pretty-format]` Option to not escape strings in diff messages ([#5661](https://github.com/facebook/jest/pull/5661))
 - `[jest-haste-map]` Add `getFileIterator` to `HasteFS` for faster file iteration ([#7010](https://github.com/facebook/jest/pull/7010)).

TestUtils.js

@@ -99,7 +99,7 @@ const DEFAULT_PROJECT_CONFIG: ProjectConfig = {
   roots: [],
   runner: 'jest-runner',
   setupFiles: [],
-  setupTestFrameworkScriptFile: null,
+  setupFilesAfterEnv: [],
   skipFilter: false,
   skipNodeResolution: false,
   snapshotResolver: null,

docs/Configuration.md

@@ -628,19 +628,21 @@ If you need to restrict your test-runner to only run in serial rather then being
 
 Default: `[]`
 
-The paths to modules that run some code to configure or set up the testing environment. Each setupFile will be run once per test file. Since every test runs in its own environment, these scripts will be executed in the testing environment immediately before executing the test code itself.
+A list of paths to modules that run some code to configure or set up the testing environment. Each setupFile will be run once per test file. Since every test runs in its own environment, these scripts will be executed in the testing environment immediately before executing the test code itself.
 
-It's also worth noting that `setupFiles` will execute _before_ [`setupTestFrameworkScriptFile`](#setuptestframeworkscriptfile-string).
+It's also worth noting that `setupFiles` will execute _before_ [`setupFilesAfterEnv`](#setupFilesAfterEnv-array).
 
-### `setupTestFrameworkScriptFile` [string]
+### `setupFilesAfterEnv` [array]
 
-Default: `undefined`
+Default: `[]`
+
+A list of paths to modules that run some code to configure or set up the testing framework before each test. Since [`setupFiles`](#setupfiles-array) executes before the test framework is installed in the environment, this script file presents you the opportunity of running some code immediately after the test framework has been installed in the environment.
 
-The path to a module that runs some code to configure or set up the testing framework before each test. Since [`setupFiles`](#setupfiles-array) executes before the test framework is installed in the environment, this script file presents you the opportunity of running some code immediately after the test framework has been installed in the environment.
+If you want a path to be [relative to the root directory of your project](#rootdir-string), please include `<rootDir>` inside a path's string, like `"<rootDir>/a-configs-folder"`.
 
-If you want this path to be [relative to the root directory of your project](#rootdir-string), please include `<rootDir>` inside the path string, like `"<rootDir>/a-configs-folder"`.
+For example, Jest ships with several plug-ins to `jasmine` that work by monkey-patching the jasmine API. If you wanted to add even more jasmine plugins to the mix (or if you wanted some custom, project-wide matchers for example), you could do so in these modules.
 
-For example, Jest ships with several plug-ins to `jasmine` that work by monkey-patching the jasmine API. If you wanted to add even more jasmine plugins to the mix (or if you wanted some custom, project-wide matchers for example), you could do so in this module.
+_Note: `setupTestFrameworkScriptFile` is deprecated in favor of `setupFilesAfterEnv`._
 
 ### `snapshotResolver` [string]
 

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

@@ -45,7 +45,7 @@ exports[`--showConfig outputs config info and exits 1`] = `
       ],
       \\"runner\\": \\"jest-runner\\",
       \\"setupFiles\\": [],
-      \\"setupTestFrameworkScriptFile\\": null,
+      \\"setupFilesAfterEnv\\": [],
       \\"skipFilter\\": false,
       \\"snapshotSerializers\\": [],
       \\"testEnvironment\\": \\"jest-environment-jsdom\\",

e2e/__tests__/setup_files_after_env_config.test.js

@@ -0,0 +1,70 @@
+/**
+ * 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';
+
+import fs from 'fs';
+import path from 'path';
+import {json as runWithJson} from '../runJest';
+import {writeFiles} from '../Utils';
+
+const DIR = path.resolve(__dirname, '../setup-files-after-env-config');
+
+const pkgJsonOutputFilePath = path.join(
+  process.cwd(),
+  'e2e/setup-files-after-env-config/package.json',
+);
+
+afterAll(() => {
+  fs.unlinkSync(pkgJsonOutputFilePath);
+});
+
+describe('setupFilesAfterEnv', () => {
+  it('requires multiple setup files before each file in the suite', () => {
+    const pkgJson = {
+      jest: {
+        setupFilesAfterEnv: ['./setup1.js', './setup2.js'],
+      },
+    };
+
+    writeFiles(DIR, {
+      'package.json': JSON.stringify(pkgJson, null, 2),
+    });
+
+    const result = runWithJson('setup-files-after-env-config', [
+      'test1.test.js',
+      'test2.test.js',
+    ]);
+
+    expect(result.json.numTotalTests).toBe(2);
+    expect(result.json.numPassedTests).toBe(2);
+    expect(result.json.testResults.length).toBe(2);
+    expect(result.status).toBe(0);
+  });
+
+  it('requires setup files *after* the test runners are required', () => {
+    const pkgJson = {
+      jest: {
+        setupFilesAfterEnv: ['./setup_hooks_into_runner.js'],
+      },
+    };
+
+    writeFiles(DIR, {
+      'package.json': JSON.stringify(pkgJson, null, 2),
+    });
+
+    const result = runWithJson('setup-files-after-env-config', [
+      'runner_patch.test.js',
+    ]);
+
+    expect(result.json.numTotalTests).toBe(1);
+    expect(result.json.numPassedTests).toBe(1);
+    expect(result.json.testResults.length).toBe(1);
+    expect(result.status).toBe(0);
+  });
+});

e2e/setup-files-after-env-config/setup2.js

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+
+global.definedInSetupFile = true;

jest.config.js

@@ -21,7 +21,7 @@ module.exports = {
     'e2e/runtime-internal-module-registry/__mocks__',
   ],
   projects: ['<rootDir>', '<rootDir>/examples/*/'],
-  setupTestFrameworkScriptFile: '<rootDir>/testSetupFile.js',
+  setupFilesAfterEnv: ['<rootDir>/testSetupFile.js'],
   snapshotSerializers: [
     '<rootDir>/packages/pretty-format/build/plugins/convert_ansi.js',
   ],

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

@@ -73,9 +73,7 @@ const jestAdapter = async (
     }
   });
 
-  if (config.setupTestFrameworkScriptFile) {
-    runtime.requireModule(config.setupTestFrameworkScriptFile);
-  }
+  config.setupFilesAfterEnv.forEach(path => runtime.requireModule(path));
 
   runtime.requireModule(testPath);
   const results = await runAndTransformResultsToJestFormat({

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

@@ -501,15 +501,15 @@ export const options = {
   },
   setupFiles: {
     description:
-      'The paths to modules that run some code to configure or ' +
+      'A list of paths to modules that run some code to configure or ' +
       'set up the testing environment before each test. ',
     type: 'array',
   },
-  setupTestFrameworkScriptFile: {
+  setupFilesAfterEnv: {
     description:
-      'The path to a module that runs some code to configure or ' +
-      'set up the testing framework before each test.',
-    type: 'string',
+      'A list of paths to modules that run some code to configure or ' +
+      'set up the testing framework before each test ',
+    type: 'array',
   },
   showConfig: {
     default: undefined,

packages/jest-cli/src/lib/__tests__/__snapshots__/init.test.js.snap

@@ -138,8 +138,8 @@ module.exports = {
   // The paths to modules that run some code to configure or set up the testing environment before each test
   // setupFiles: [],
 
-  // The path to a module that runs some code to configure or set up the testing framework before each test
-  // setupTestFrameworkScriptFile: null,
+  // A list of paths to modules that run some code to configure or set up the testing framework before each test
+  // setupFilesAfterEnv: [],
 
   // A list of paths to snapshot serializer modules Jest should use for snapshot testing
   // snapshotSerializers: [],

packages/jest-config/src/Defaults.js

@@ -61,7 +61,7 @@ export default ({
   runTestsByPath: false,
   runner: 'jest-runner',
   setupFiles: [],
-  setupTestFrameworkScriptFile: null,
+  setupFilesAfterEnv: [],
   skipFilter: false,
   snapshotSerializers: [],
   testEnvironment: 'jest-environment-jsdom',

packages/jest-config/src/Deprecated.js

@@ -53,6 +53,16 @@ export default {
 
   Please update your configuration.`,
 
+  setupTestFrameworkScriptFile: (options: {
+    setupTestFrameworkScriptFile: Array<string>,
+  }) => `  Option ${chalk.bold(
+    '"setupTestFrameworkScriptFile"',
+  )} was replaced by configuration ${chalk.bold(
+    '"setupFilesAfterEnv"',
+  )}, which supports multiple paths.
+
+  Please update your configuration.`,
+
   testPathDirs: (options: {
     testPathDirs: Array<string>,
   }) => `  Option ${chalk.bold('"testPathDirs"')} was replaced by ${chalk.bold(

packages/jest-config/src/Descriptions.js

@@ -61,8 +61,8 @@ export default ({
     "Allows you to use a custom runner instead of Jest's default test runner",
   setupFiles:
     'The paths to modules that run some code to configure or set up the testing environment before each test',
-  setupTestFrameworkScriptFile:
-    'The path to a module that runs some code to configure or set up the testing framework before each test',
+  setupFilesAfterEnv:
+    'A list of paths to modules that run some code to configure or set up the testing framework before each test',
   snapshotSerializers:
     'A list of paths to snapshot serializer modules Jest should use for snapshot testing',
   testEnvironment: 'The test environment that will be used for testing',

packages/jest-config/src/ValidConfig.js

@@ -88,7 +88,7 @@ export default ({
   runTestsByPath: false,
   runner: 'jest-runner',
   setupFiles: ['<rootDir>/setup.js'],
-  setupTestFrameworkScriptFile: '<rootDir>/testSetupFile.js',
+  setupFilesAfterEnv: ['<rootDir>/testSetupFile.js'],
   silent: true,
   skipFilter: false,
   skipNodeResolution: false,

packages/jest-config/src/__tests__/__snapshots__/normalize.test.js.snap

@@ -47,6 +47,29 @@ exports[`rootDir throws if the options is missing a rootDir property 1`] = `
 <red></>"
 `;
 
+exports[`setupTestFrameworkScriptFile logs a deprecation warning when \`setupTestFrameworkScriptFile\` is used 1`] = `
+"<yellow><bold><bold>●<bold> Deprecation Warning</>:</>
+<yellow></>
+<yellow>  Option <bold>\\"setupTestFrameworkScriptFile\\"</> was replaced by configuration <bold>\\"setupFilesAfterEnv\\"</>, which supports multiple paths.</>
+<yellow></>
+<yellow>  Please update your configuration.</>
+<yellow></>
+<yellow>  <bold>Configuration Documentation:</></>
+<yellow>  https://jestjs.io/docs/configuration.html</>
+<yellow></>"
+`;
+
+exports[`setupTestFrameworkScriptFile logs an error when \`setupTestFrameworkScriptFile\` and \`setupFilesAfterEnv\` are used 1`] = `
+"<red><bold><bold>● <bold>Validation Error</>:</>
+<red></>
+<red>  Options: <bold>setupTestFrameworkScriptFile</> and <bold>setupFilesAfterEnv</> cannot be used together.</>
+<red>  Please change your configuration to only use <bold>setupFilesAfterEnv</>.</>
+<red></>
+<red>  <bold>Configuration Documentation:</></>
+<red>  https://jestjs.io/docs/configuration.html</>
+<red></>"
+`;
+
 exports[`testEnvironment throws on invalid environment names 1`] = `
 "<red><bold><bold>● <bold>Validation Error</>:</>
 <red></>