Unit Testing with Jest

Jest is an open source test runner created by Facebook. It is used within Facebook internally as well as many other enterprise and open source projects including Nx itself!

Reasons for Using Jest

  • Jest is faster than karma allowing more time to be spent developing features rather than validating them.
  • Jest was built with monorepos in mind and is able to isolate the important parts of a monorepo to test.
  • Jest has a great built-in reporter for printing out results of tests.
  • Jest has an immersive watch mode which provides near instant feedback when developing tests.
  • Jest provides the ability to use Snapshot Testing to validate features.
  • And more...

How to use Jest

Setting up your workspace to use Jest

First, add the appropriate configuration and dependencies via:

ng generate jest

Generating a Library which uses Jest

The following command will generate a new library which is configured to use jest as its test runner.

ng generate library libname --unit-test-runner jest

Testing a project which uses Jest

Testing a project using Jest within the Nx Workspace is almost identical to testing any other project. Use the following command to execute the unit tests in the libname lib:

ng test libname

Snapshot Testing

Jest has support for Snapshot Testing, a tool which simplifies validating data did not change. Check out the official Jest Documentation on Snapshot Testing.

Writing tests using Snapshot Testing

To write a test which uses Snapshot Testing, use the toMatchSnapshot() matcher.

describe('Home Page', () => {
  it('should have a header', () => {
    const header = fixture.nativeElement
      .querySelector('header');
    expect(header).toMatchSnapshot();
  });
});

The snapshot will be generated the first time the test is run. If the contents of that snapshot change, the test will fail indicating unexpected changes to the snapshot. Below is an example of the test results if the hamburger icon disappears unintentionally.

Home Page > should have a header
 expect(value).toMatchSnapshot()
 Received value does not match stored snapshot "Home Page should have a header 1".
 - Snapshot
+ Received
 <header>
  <h1>
-   <mat-icon>
-     hamburger
-   </mat-icon>
    Example
  </h1>
</header>

Note: These snapshot files should be checked in with your code.

Updating Snapshots

When intentionally changing the contents of a snapshot, you can run tests with the --updateSnapshot flag to update failing snapshots instead of failing the test.

ng test libname --updateSnapshot

Make sure no unintentional snapshots are failing BEFORE updating failing snapshots.

Using Jest locally

If you are a developer making changes locally to a library, start jest's interactive watch mode to run the library's tests related to uncommitted changes and then rerun tests whenever files are changed.

ng test libname --watch

Debugging failing tests using Jest

To debug failing tests using Chrome Devtools or an IDE you can run the test command through node's --inspect-brk flag:

node --inspect-brk ./node_modules/.bin/ng test libname

Now, you can visit chrome://inspect in Chrome and inspect the target to attach to the node process. You can now use Chrome Devtools to step through your code line by line and debug the cause of the failing tests. Visit the official Jest documentation to find out more.

Using Jest in CI/CD

When using Jest in a CI environment, you can continue to use affected to isolate tests affected by the changes in the PR.

yarn affected:test --base=master

Looking for more best practices for enterprise-scale Angular development from the Nrwl team?

Visit Nx Playbook