Add src/setupTests.js to specify environment setup for Jest (#545) (#548)

config/paths.js

@@ -37,6 +37,7 @@ module.exports = {
   appHtml: resolveApp('index.html'),
   appPackageJson: resolveApp('package.json'),
   appSrc: resolveApp('src'),
+  testsSetup: resolveApp('src/setupTests.js'),
   appNodeModules: resolveApp('node_modules'),
   ownNodeModules: resolveApp('node_modules'),
   nodePaths: nodePaths
@@ -53,6 +54,7 @@ module.exports = {
   appHtml: resolveApp('index.html'),
   appPackageJson: resolveApp('package.json'),
   appSrc: resolveApp('src'),
+  testsSetup: resolveApp('src/setupTests.js'),
   appNodeModules: resolveApp('node_modules'),
   // this is empty with npm3 but node resolution searches higher anyway:
   ownNodeModules: resolveOwn('../node_modules'),
@@ -66,6 +68,7 @@ module.exports = {
   appHtml: resolveOwn('../template/index.html'),
   appPackageJson: resolveOwn('../package.json'),
   appSrc: resolveOwn('../template/src'),
+  testsSetup: resolveOwn('../template/src/setupTests.js'),
   appNodeModules: resolveOwn('../node_modules'),
   ownNodeModules: resolveOwn('../node_modules'),
   nodePaths: nodePaths

scripts/utils/createJestConfig.js

@@ -9,14 +9,22 @@
  */
 // @remove-on-eject-end
 
+const pathExists = require('path-exists');
+const paths = require('../../config/paths');
+
 module.exports = (resolve, rootDir) => {
+  const setupFiles = [resolve('config/polyfills.js')];
+  if (pathExists.sync(paths.testsSetup)) {
+    setupFiles.push(paths.testsSetup);
+  }
+
   const config = {
     moduleNameMapper: {
       '^[./a-zA-Z0-9$_-]+\\.(jpg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm)$': resolve('config/jest/FileStub.js'),
       '^[./a-zA-Z0-9$_-]+\\.css$': resolve('config/jest/CSSStub.js')
     },
     scriptPreprocessor: resolve('config/jest/transform.js'),
-    setupFiles: [resolve('config/polyfills.js')],
+    setupFiles: setupFiles,
     testPathIgnorePatterns: ['<rootDir>/(build|docs|node_modules)/'],
     testEnvironment: 'node'
   };

template/README.md

@@ -32,6 +32,7 @@ You can find the most recent version of this guide [here](https://github.com/fac
   - [Writing Tests](#writing-tests)
   - [Testing Components](#testing-components)
   - [Using Third Party Assertion Libraries](#using-third-party-assertion-libraries)
+  - [Initializing Test Environment](#initializing-test-environment)
   - [Focusing and Excluding Tests](#focusing-and-excluding-tests)
   - [Coverage Reporting](#coverage-reporting)
   - [Continuous Integration](#continuous-integration)
@@ -674,6 +675,24 @@ import { expect } from 'chai';
 
 and then use them in your tests like you normally do.
 
+### Initializing Test Environment
+
+>Note: this feature is available with `react-scripts@0.4.0` and higher.
+
+If your app uses a browser API that you need to mock in your tests or if you just need a global setup before running your tests, add a `src/setupTests.js` to your project. It will be automatically executed before running your tests.
+
+For example:
+
+#### `src/setupTests.js`
+```js
+const localStorageMock = {
+  getItem: jest.fn(),
+  setItem: jest.fn(),
+  clear: jest.fn()
+};
+global.localStorage = localStorageMock
+```
+
 ### Focusing and Excluding Tests
 
 You can replace `it()` with `xit()` to temporarily exclude a test from being executed.