neutrino-dev/docs/presets/neutrino-preset-jest

Neutrino Jest Preset

neutrino-preset-jest is a Neutrino preset that supports testing JavaScript projects with the Jest test runner.

Features

• Zero upfront configuration necessary to start testing
• Babel compilation that compiles your tests using the same Babel options used by your source code
• Source watching for re-running of tests on change
• Collecting test coverage information and generating report
• Easily extensible to customize your testing as needed

Requirements

• Node.js v6.9+
• Yarn or npm client
• Neutrino v5, Neutrino build preset

Installation

neutrino-preset-jest can be installed via the Yarn or npm clients. Inside your project, make sure neutrino and neutrino-preset-jest are development dependencies. You will also be using another Neutrino preset for building your application source code.

Yarn

❯ yarn add --dev neutrino-preset-jest

npm

❯ npm install --save-dev neutrino-preset-jest

Installation: React Testing

Jest is often used in the testing of React components. If you are using this preset in a React application, which most likely means you are using neutrino-preset-react, you should also consider adding React's TestUtils and potentially a higher-level abstraction such as Airbnb's Enzyme. These should be development dependencies of your project.

Yarn

❯ yarn add --dev react-addons-test-utils enzyme

npm

❯ npm install --save-dev react-addons-test-utils enzyme

See the React's Test Utils documentation for specifics on React testing with this approach.

Project Layout

neutrino-preset-jest follows the standard project layout specified by Neutrino. This means that by default all project test code should live in a directory named test in the root of the project. Test files end in either _test.js, .test.js, _test.jsx, or .test.jsx.

Quickstart

After adding the Jest preset to your Neutrino-built project, add a new directory named test in the root of the project, with a single JS file named simple_test.js in it.

❯ mkdir test && touch test/simple_test.js

Edit your test/simple_test.js file with the following:

describe('simple', () => {
  it('should be sane', () => {
    expect(!false).toBe(true);
  });
});

Now edit your project's package.json to add commands for testing your application. In this example, let's pretend this is a Node.js project:

{
  "scripts": {
    "test": "neutrino test --use neutrino-preset-node neutrino-preset-jest"
  }
}

Or if you have set up Neutrino with neutrino.use in your package.json:

{
  "neutrino": {
    "use": [
      "neutrino-preset-node",
      "neutrino-preset-jest"
    ]
  }
}

Run the tests, and view the results in your console:

Yarn

❯ yarn test
 PASS  test/simple_test.js
  simple
    ✓ should be sane (2ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        0.936s
Ran all test suites.
✨  Done in 2.12s.

npm

❯ npm test

 PASS  test/simple_test.js
  simple
    ✓ should be sane (2ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        0.972s
Ran all test suites.

To run tests against files from your source code, simply import them:

import thingToTest from '../src/thing';

For more details on specific Jest usage, please refer to their documentation.

Executing single tests

By default this preset will execute every test file located in your test directory ending in the appropriate file extension. Use the command line files parameters to execute individual tests.

Watching for changes

neutrino-preset-jest can watch for changes on your source directory and subsequently re-run tests. Simply use the --watch flag with your neutrino test command.

Coverage reporting

Jest has an integrated coverage reporter, which requires no configuration. To collect test coverage information and generate a report:

❯ neutrino test --coverage

You can also edit your package.json file and create a separate command for generating a coverage report, which can be very helpful during continuous integration of your project:

{
  "scripts": {
    "coverage": "neutrino test --coverage"
  }
}

See the Jests documentation for more configuration options for generating coverage reports.

Customizing

To override the test configuration, start with the documentation on customization. neutrino-preset-jest creates some conventions to make overriding the configuration easier once you are ready to make changes.

Rules

The following is a list of rules and their identifiers which can be overridden:

• compile: Compiles JS files from the test directory using adopted Babel settings from other build presets. Contains a single loader named babel.

Simple customization

By following the customization guide and knowing the rule, and loader IDs above, you can override and augment the build directly from package.json.

Jest configuration settings can also be modified directly from package.json, but it is not required. neutrino-preset-jest will import Jest configuration from your package.json's jest object or neutrino.options.jest; the format is defined on the Jest documentation site.

Example: Turn off bailing on test failures.

{
  "neutrino": {
    "options": {
      "jest": {
        "bail": false
      }
    }
  }
}

Advanced configuration

By following the customization guide and knowing the rule, and loader IDs above, you can override and augment testing by creating a JS module which overrides the config.

You can also modify Jest settings by overriding with any options Jest accepts. In a standalone Jest project this is typically done in the package.json file, but neutrino-preset-jest allows advanced configuration through this mechanism as well. This is stored in the neutrino.options.jest object, and takes the same configuration options as outlined in the Jest documentation.

Example: Create a global __DEV__ variable set to true in all test environments.

module.exports = neutrino => {
  neutrino.options.jest.globals = {
    __DEV__: true
  };
};

Contributing

This preset is part of the neutrino-dev repository, a monorepo containing all resources for developing Neutrino and its core presets. Follow the contributing guide for details.