If you want to skip all the news and just get going, run npm install jest@^30.0.0 and follow the migration guide: Upgrading from Jest 29 to 30.

What’s New?​

Jest 30 is noticeably faster, uses less memory, and comes with tons of new features. First, let’s take a look at the breaking changes:

Breaking Changes​

• Jest 30 drops support for Node 14, 16, 19, and 21.
• jest-environment-jsdom was upgraded from jsdom 21 to 26.
• The minimum compatible TypeScript version is now 5.4.
• Various expect aliases were removed. eslint-plugin-jest has an autofixer which you can run to automatically upgrade your codebase.
• Non-enumerable object properties are now excluded from object matchers such as toEqual by default.
• Jest now supports .mts and .cts files by default.
• --testPathPattern was renamed to --testPathPatterns.
• Jest now properly handles promises that are first rejected and then later caught to avoid false positive test failures.
• We made various improvements to Jest’s printing of snapshots which might require you to update snapshots. Google deprecated goo.gl links which we were using in snapshots. We don’t like it either, but you’ll have to update all your snapshots.
• Jest itself is now bundled into a single file per package. This improves performance, but might break if you built tools that reach into Jest's internals.

These are just some of the highlights. The full list of breaking changes can be found in the CHANGELOG and the Jest 30 migration guide.

Performance & Memory Improvements​

Jest 30 delivers real-world performance gains thanks to many optimizations, especially related to module resolution, memory usage, and test isolation. By relying on the new unrs-resolver, module resolution in Jest became more feature-rich, standards-compliant, and faster. Thanks to @JounQin for the migration. Depending on your project, you may see significantly faster test runs and reduced memory consumption. For example, one large TypeScript app with a client and server observed 37% faster test runs and 77% lower memory usage in one part of their codebase:

Jest is fast, but due to Jest's test isolation, slow user code often exacerbates performance issues and leads to slow test runs. When tests leave behind open handles like unclosed timers or connections to other services, it can cause Jest to hang or slow down. Jest 30 has gotten better at detecting and reporting these issues, which helps you identify and fix slow or problematic tests more easily. For example, tests at Happo were sped up by 50% from 14 minutes down to 9 minutes by cleaning up open handles and upgrading to Jest 30.

If you are using files that consolidate the exports of multiple modules into a single file (i.e. "barrel files"), we recommend using tools such as babel-jest-boost, babel-plugin-transform-barrels or no-barrel-file to avoid loading large swaths of application code for each test file. This can lead to performance improvements of up to 100x.

Globals cleanup between test files​

Jest achieves test isolation between files by running each test in a separate VM context, giving each file a fresh global environment. However, if your code does not clean up globals after each test file, it can lead to memory leaks across Jest and slow down your test runs. Jest 30 introduces a new feature that notifies you about globals that are not correctly cleaned up after a test run.

In the future, Jest will automatically clean up globals after each test run. If you don't get any warnings about uncleaned globals with Jest 30, you can already set the globals cleanup mode to "on" now to enable this feature fully, and benefit from major memory savings and performance improvements:

export default {
  testEnvironmentOptions: {
    globalsCleanup: 'on',
  },
};

The default in Jest is globalsCleanup: 'soft'. To disable this feature you can set it to off. If you need to protect specific global objects from being cleaned up -- for example, shared utilities or caches -- you can mark them as protected using jest-util:

import {protectProperties} from 'jest-util';

protectProperties(globalThis['my-property']);

Thanks to @eyalroth for implementing this feature!

New Features​

Improved ECMAScript Module & TypeScript Support​

Support for import.meta.* and file:// was added when using native ESM with Jest. In addition, you can now write your Jest config files in TypeScript, and .mts and .cts files are natively supported without requiring extra configuration. If you are using Node’s native TypeScript type stripping feature, we no longer load the TypeScript transformer to strip types, leading to faster test runs.

Spies and the using keyword​

You can now use JavaScript’s new explicit resource management syntax (using) with Jest spies. If your environment supports it, writing using jest.spyOn(obj, 'method') will automatically restore the spy when the block ends, so you don’t have to manually clean up.

test('logs a warning', () => {
  using spy = jest.spyOn(console, 'warn');
  doSomeThingWarnWorthy();
  expect(spy).toHaveBeenCalled();
});

Documentation

expect.arrayOf​

Jest 30 introduces a new asymmetric matcher, expect.arrayOf, which lets you validate every element of an array against a condition or type. For instance, you can expect an array of numbers ensuring all items are numbers:

expect(someArray).toEqual(expect.arrayOf(expect.any(Number)));

Documentation

New test.each placeholder: %$​

If you use data-driven tests with test.each, you can now include a special placeholder %$ in your test titles to inject the number of the test case. For example:

test.each(cases)('Case %$ works as expected', () => {});

will replace %$ with the test’s sequence number.

Documentation

jest.advanceTimersToNextFrame()​

@sinonjs/fake-timers was upgraded to v13, adding jest.advanceTimersToNextFrame(). This new function allows you to advance all pending requestAnimationFrame callbacks to the next frame boundary, making it easier to test animations or code that relies on requestAnimationFrame without having to guess millisecond durations.

Documentation

Configurable test retries​

Jest 30 enhances jest.retryTimes() with new options that give you control over how retries are handled. You can specify a delay or immediately retry a failed test instead of waiting until the entire test suite finishes:

// Retry failed tests up to 3 times, waiting 1 second between attempts:
jest.retryTimes(3, {waitBeforeRetry: 1000});

// Immediately retry without waiting for other tests to finish:
jest.retryTimes(3, {retryImmediately: true});

Documentation

jest.unstable_unmockModule()​

Jest 30 adds new experimental jest.unstable_unmockModule() API for finer control when unmocking modules (especially when using native ESM).

Documentation

jest.onGenerateMock(callback)​

A new onGenerateMock method was added. It registers a callback function that is invoked whenever Jest generates a mock for a module. This callback allows you to modify a mock before it is returned to your test environment:

jest.onGenerateMock((modulePath, moduleMock) => {
  if (modulePath.includes('Database')) {
    moduleMock.connect = jest.fn().mockImplementation(() => {
      console.log('Connected to mock DB');
    });
  }
  return moduleMock;
});

Documentation

Other Improvements​

Custom object serialization​

Jest’s matcher utilities now support defining a static SERIALIZABLE_PROPERTIES on custom objects. This allows you to control which properties of a custom object are included in snapshots and error messages, making the output more focused and relevant.

Documentation

Asynchronous setup support​

Test files listed in setupFilesAfterEnv can now export an async function or use top-level await similar to setupFiles.

And so much more…​

Check out the full CHANGELOG for all changes, improvements and new features.

Known Issues​

jsdom has made changes to become more spec compliant. This might break some use cases, most notably mocking window.location in tests. Jest now ships with @jest/environment-jsdom-abstract to make it easier for you to compose your own custom test environment based on jsdom. If you are just looking to patch jsdom, you can apply this jsdom patch to your project. In the future, we may look into providing an alternative to jsdom that is better suited for testing.

What's Next​

Jest has been the most popular JavaScript testing framework for a decade. It is used by millions of developers, supporting a wide range of projects from small libraries to the largest codebases in the world. Jest has constantly been improved over time, and as with all long-lasting software projects used in the real world, we accumulated technical debt. We support some features that only few people or companies use, and we have kept breaking changes to a minimum to avoid disrupting users. Some features should be made possible by Jest, but not as part of the core framework. Other features promote testing the wrong things, and should maybe not be part of Jest at all. In terms of Jest's team, a few of us moved on over time which led to slower progress and fewer releases. Here is how we are going to address these issues going forward:

• Performance / Technical Debt: Slim Jest down into a leaner, more performant core. Remove features that are not used by the majority of users, and focus on what makes Jest great.
• Consistent Release Cycles: We will aim to be more consistent with our release cycles and deprecation policies.
• Be Open: Build everything in the open, and be transparent about our plans. Provide more opportunities to get involved and increase the number of contributors.
• Be Bold: As the Jest team, we should be more bold. There are a bunch of things that holds Jest back from what it could be. It's time to make moves.

The great news is that Jest has always been well set up to deliver on these principles, ever since we built the framework as a modular system with clear separation of concerns. Now it's time to execute. More on all that soon!

Thanks​

This release wouldn’t have been possible without the hard work of our community. Thank you.

@SimenB, @mrazauskas, @Connormiha, @liuxingbaoyu, @k-rajat19, @G-Rath, @charpeni, @dubzzz, @stekycz, @yinm, @lencioni, @phawxby, @lukeapage, @robhogan, @fisker, @k-rajat19, @connectdotz, @alesmenzel, @rickhanlonii, @mbelsky, @brunocabral88, @brandon-leapyear, @nicolo-ribaudo, @dj-stormtrooper, @eryue0220

A special thanks to everyone who made their first contribution to Jest in this release. Thank you for making Jest better for everyone!

@eyalroth, @KhaledElmorsy, @mohammednumaan, @bensternthal, @BondarenkoAlex, @phryneas, @jayvdb, @brandonchinn178, @latin-1, @rmartine-ias, @fa93hws, @Dunqing, @gustav0d, @noritaka1166, @andreibereczki, @Dreamsorcerer, @satanTime, @icholy, @ecraig12345, @cgm-16, @sebastiancarlos, @dancer1325, @loganrosen, @zakingslayerv22, @dev-intj, @tez3998, @anbnyc, @pengqiseven, @thypon, @co63oc, @danielrentz, @jonasongg, @andrew-the-drawer, @phryneas, @hyperupcall, @tonyd33, @madcapnmckay, @dongwa, @gagan-bhullar-tech, @ikonst, @ZuBB, @jzaefferer, @brandonnorsworthy, @henny1105, @DmitryMakhnev, @askoufis, @RahulARanger, @Jon-Biz, @fynsta, @KonnorRogers, @BondarenkoAlex, @mouadhbb, @kemuridama, @Avi-E-Koenig, @davidroeca, @akwodkiewicz, @mukul-turing, @dnicolson, @colinacassidy, @ofekm97, @haze, @Vadimchesh, @peterdenham, @ShuZhong, @manoraj, @nicolo-ribaudo, @georgekaran, @MathieuFedrigo, @hkdobrev, @Germandrummer92, @CheadleCheadle, @notaphplover, @danbeam, @arescrimson, @yepitschunked, @JimminiKin, @DerTimonius, @vkml, @ginabethrussell, @jeremiah-snee-openx, @WillianAgostini, @casey-lentz, @faizanu94, @someone635, @rafaelrabelos, @RayBrokeSomething, @DaniAcu, @mattkubej, @tr1ckydev, @shresthasurav, @the-ress, @Mutesa-Cedric, @nolddor, @alexreardon, @Peeja, @verycosy, @mknight-atl, @maro1993, @Eric-Tyrrell22

The only breaking changes that should be noticeable are:

• Node versions 12 and 17 are dropped, both of which are EOL

• The snapshotFormat property is changed to:

  + snapshotFormat: {
  +   escapeString: false,
  +   printBasicPrototype: false
  + }
  

• jest-environment-jsdom has upgraded jsdom from v19 to v20

There are certain changes to the types exposed by Jest, but probably (hopefully!) nothing that should impede the upgrade. Please see the upgrade guide for more details.

That's it for breaking changes! Hopefully this means the upgrade path from Jest 28 is smooth. Please see the changelog for other changes.

Thanks for reading, and happy Jesting! 🃏

Today we're excited to announce that Jest is joining the OpenJS Foundation!

This change transfers ownership of the project from Meta to the Jest Core team via the OpenJS Foundation as an Impact Project. We’re grateful to Meta for creating Jest and all of their support over the years, and we look forward to the future of Jest as a project owned by the Jest community!

Check out the Meta Engineering blog and OpenJS Foundation blog announcements for more info.

Additionally, as announced in the Jest 27 blog post last year, we have removed some packages that no longer are used by default from the default installation. As a result the installation size has dropped by about 1/3.

Breaking changes​

The list of breaking changes is long (and can be seen fully in the changelog), but for migration purposes, we've also written a guide you can follow. Hopefully this makes the upgrade experience as frictionless as possible!

Main breaking changes likely to impact your migration are dropped support for Node 10 and 15 (but not Node 12, which will be EOL in a few days) and some renamed configuration options.

Please note that both of the removed modules (jest-environment-jsdom and jest-jasmine2) are still actively maintained and tested in the same way, so the only breaking change here is that you'll need to explicitly install them.

The guide should hopefully make migration trivial, but note that if you use any of the packages Jest consists of directly (such as jest-worker or pretty-format), instead of just running jest, then you need to go through the changelog to view any breaking changes.

Features​

Now let's talk about the new features in Jest 28, which is way more exciting! And there's quite a few of them, so buckle up.

Sharding of test run​

Jest now includes a new --shard CLI option, contributed by Mario Nebl. It allows you to run parts of your test across different machine, and has been one of Jest's oldest feature requests.

Jest's own test suite on CI went from about 10 minutes to 3 on Ubuntu, and on Windows from 20 minutes to 7.

package.json exports​

Jest shipped minimal support of exports in 27.3. However, it only supported the "main" entry point (.), and only if no main field was present in package.json. With Jest 28 we're excited to finally be shipping full support!

Related, in Jest 27, we provided either require or import condition. In Jest 28, jest-environment-node will now automatically provide node and node-addons conditions, while jest-environment-jsdom will provide the browser condition.

This has been one of the biggest compatibility issues of Jest, and hopefully this is now resolved once and for all.

Fake timers​

Jest 26 introduced the concept of "modern" fake timers, which uses @sinonjs/fake-timers under the hood, and Jest 27 made it the default. In Jest 28, we are now exposing more of the underlying implementation through both configuration and runtime APIs. Huge thanks to Tom Mrazauskas who contributed this feature!

This allows you to not mock out process.nextTick which improves compatibility with fake Promises, or to enable advanceTimers which automatically advance timers.

Please see the fakeTimers configuration for details.

GitHub Actions Reporter​

Jest now ships with a reporter to be used on GitHub Actions, which will use annotations to print test errors inline.

You can activate this reporter by passing github-actions in the reporters configuration option.

Huge thanks to Bernie Reiter and other contributors for sticking by us and finally landing this feature.

Inline testEnvironmentOptions​

You can now pass testEnvironmentOptions inline in a file, similar to how you can set test environment. This is useful if you want to e.g. change the URL in a single file.

/**
 * @jest-environment jsdom
 * @jest-environment-options {"url": "https://jestjs.io/"}
 */

test('use jsdom and set the URL in this test file', () => {
  expect(window.location.href).toBe('https://jestjs.io/');
});

All Node.js globals​

If you are using the new fetch implementation in Node v18, you might have noticed that this function is not available in Jest. It has been a long-standing issue that we have to manually copy over any globals into the test globals. With Jest 28, this is no longer an issue as we now inspect the global environment Jest itself is running in, and copy over any globals that are missing in the test environment.

ECMAScript Modules​

Not much has changed in Jest's support for native ESM since Jest 27 came out. We continue to be blocked by stabilization in Node, and are hopeful this situation will improve sooner rather than later!

However, we have been able to add a couple of new features in Jest 28.

data: URLs​

Tommaso Bossi has contributed support for data URLs, meaning you can now inline define some JavaScript to run without using eval.

import.meta.jest​

While you have been able to access jest via import {jest} from '@jest/globals' in Jest, we've received feedback that this is less ergonomical than the (seemingly, but not really) global jest variable available in CJS. So Jest 28 ships with import.meta.jest to allow easier access.

Miscellaneous​

That's quite a lot of features, and are my personal highlights. However, we still have many more which I'll quickly go through:

Asynchronous resolvers​

Ian VanSchooten has contributed support for asynchronous resolvers, which enables tools like Vite to have better integrations with Jest.

Asynchronous setup files​

If you have some async work you want to do when using setupFiles, you can now export an async function, which Jest will call and await before loading any tests.

Note that this feature is only available for CJS. For ESM, we recommend using top-level await instead.

Using globalThis​

Internally, Jest has been using global to refer to the global environment. However, since this only exists in Node, and not browsers (window), this led to incompatibility when attempting to use Jest's modules in another environment.

Jest 28 uses globalThis instead, which works in all environments.

JSDOM 19​

While, as mentioned, Jest no longer ships jest-environment-jsdom in the default installation, it is still actively maintained. As part of that, Jest 28 has upgraded from jsdom@16 to jsdom@19.

TypeScript​

If you use Jest with TypeScript, either in your tests or when writing plugins such as custom runners, Jest 28 comes with extensive improvements to our types. Here's a non-exhaustive list of the changes in Jest 28.

expect​

When using expect's own types (either directly, or via import {expect} from '@jest/globals'), it's now finally possible to add custom matchers. See our example for how to do this.

Custom plugins​

If you write a custom runner, test reporter, resolver or something else, we now export more types that should help you type these more correctly. This is a moving target, so if you are the author of something pluggable in Jest and the types aren't as useful as they could be, please file an issue!

jest-runner-tsd​

jest-runner-tsd is a custom runner for running type tests. This is what Jest uses itself to test our types, and we hope it can also be used by others! As its name implies, it is based on tsd, although it under the hood uses the fork tsd-lite.

All of these improvements and fixes has been contributed by Tom Mrazauskas. Thank you so much, Tom! 👏

Lastly, the minimum support version of TypeScript is now 4.3.

jest-light-runner​

The last thing we want to highlight in this blog post, is a very cool new Jest runner, created by Nicolò Ribaudo, called jest-light-runner. This takes almost all of the DX Jest is known for, and speeds it way up by being a smaller abstraction on top of Node. Babel's tests became almost twice as fast after migrating. While there are caveats, the existence of this runner should make it even easier for people who have smaller Node modules to test to choose Jest. Thanks, Nicolò!

Future​

While Jest 28 came almost a year after Jest 27, Jest 29 will be coming sooner, probably in just a few months. The current plan then is to just have one breaking change (except dropping Node versions), and that is to default snapshotFormat to {escapeString: false, printBasicPrototype: false}. This makes snapshots both more readable and more copy-pasteable.

This will of course be possible to override if you don't want to change, but you can also use those options today if you don't want to wait!

Acknowledgements​

Jest 28 contains contributions from more than 60 people, of which more than two thirds are first time contributors. Thank you so much to all contributors, old and new. Without you the project wouldn't be nearly as good as it is! I'd particularly like to thank Tom Mrazauskas and Feng Yu for all their contributions, from code, to issue triaging to debugging, that made Jest 28 what it is. Thank you! 🙏

Thanks for reading, and happy Jesting! 🃏

With the first major change of defaults since the New Defaults for Jest that came with the seminal version 15, Jest 27 is now here, to keep Jest fast, lean, and relevant in the future. We will explain those changes of defaults and other notable breaking changes in this post, but first, let's get into some exciting new features!

Feature updates​

Firstly, the interactive mode you may know from reviewing and updating failed snapshots can now also be used to step through failed tests one at a time. Credit goes to first-time contributor @NullDivision for implementing this feature!

Speaking of snapshots, one of the more exciting features we've shipped in recent years are Inline Snapshots, which landed in a minor release of Jest 23 almost three years ago. However, they came with the restriction that projects wanting to utilize them must be using Prettier to format their code, because that's what Jest would use to make sure the file it writes the snapshots into remains properly formatted.
And so for most of these years, we've had a pull request in the pipeline to eliminate this restriction and allow using Inline Snapshots without Prettier. It has amassed well above a hundred comments, not even taking into account PRs split out from it and landed first, and even changed owner once after the initial submission by another first-time contributor, @mmkal under the hilarious working title 'Uglier Inline Snapshots'. With the stellar rise of Prettier in recent times, this improvement is now maybe less needed than back in 2018, but still, we know that feeling of getting into a project that does not use Prettier, and suddenly not being able to use inline snapshots anymore. Nevermore!

The main reason why it took us so long to land this was, somewhat surprisingly, an out of memory error on our build pipeline. It turns out that the dependencies we load for each test file to perform the parsing, snapshot insertion, and printing do incur a significant time and memory overhead.
So with some tricks, we've speed up the initialization per test file by roughly 70% compared to Jest 26. Note that you will almost certainly not see this big of a performance improvement on your project—you would need a lot of test files that each run very quickly to best notice this, and the overhead when using a JSDOM environment dwarfs any such improvement.

In other news, the native ESM support is progressing, but some major complexities, for instance around mocking, are still ahead of us, and we continue to observe the migration to ESM as a huge ecosystem effort, where Node and a lot of crucial tools and packages all have to rely on each other to deliver an overall compelling experience.
ESM support for plugging modules into Jest is more advanced—custom runners, reporters, watch plugins, and many other modules can already be loaded as ES modules.

We've also merged a PR to be able to deal with test files symlinked into the test directory, a feature much wanted by users of Bazel.

Another PR enabled transforms to be asynchronous, a requirement to support transpilation through tools such as esbuild, Snowpack, and Vite effectively.

Flipping defaults​

Up until now, if you were using Jest in its default configuration, you were—perhaps unknowingly—running some code forked many years ago from the test runner Jasmine 2.0 that provides test framework functions such as describe, it, and beforeEach. In 2017, Aaron Abramov initially wrote a replacement for the Jasmine code called jest-circus, meant to improve error messages, maintainability, and extensibility.
After years of large-scale use at Facebook and of course in Jest itself, as well as recent adoption in create-react-app, we are now confident that jest-circus is highly compatible with jest-jasmine2 and should work in most environments with little to no migration work. There may be minor differences in execution order and strictness, but we expect no major upgrade difficulties other than for code relying on Jasmine-specific APIs such as jasmine.getEnv(). If you rely extensively on such APIs, you can opt back in to the Jasmine-based test runner by configuring "testRunner": "jest-jasmine2".

Running tests in a JSDOM environment incurs a significant performance overhead. Because this was the default behavior of Jest unless otherwise configured up until now, users who are writing Node apps, for example, may not even know they are given an expensive DOM environment that they do not even need.
For this reason, we are changing the default test environment from "jsdom" to "node". If you are affected by this change because you use DOM APIs and do not have the test environment explicitly configured, you should be receiving an error when e.g. document is accessed, and you can configure "testEnvironment": "jsdom" or use per-file environment configuration to resolve this.
For mixed projects where some tests require a DOM environment but others don't, we recommend using the fast "node" environment by default and declaring exactly those tests that need the DOM using docblocks.
In the next major, we plan to also eliminate jest-jasmine2 and jest-environment-jsdom from the Jest dependency tree and require them to be installed explicitly, so that many users can profit from a smaller install size with less clutter that they don't need.

Another default that we are changing affects Fake Timers aka Timer Mocks. We introduced an opt-in "modern" implementation of Fake Timers in Jest 26 accessed transparently through the same API, but with much more comprehensive mocking, such as for Date and queueMicrotask.
This modern fake timers implementation will now be the default. If you are among the unlucky few who are affected by the subtle implementation differences too heavily to migrate, you can get back the old implementation using jest.useFakeTimers("legacy") or, if you are enabling fake timers globally via configuration, "timers": "legacy".

Features coming with breaking changes​

We introduced a few more small breaking changes to help you avoid mistakes by disallowing some things that can easily happen unintentionally:

• The same done test callback may not be called more than once,
• calling done and returning a Promise may not be combined,
• a describe block must not return anything,

and we made some TypeScript types stricter.

Modules used in the following configuration options are now transformed like the rest of your code, which may be breaking if you relied on them being loaded as-is:

• testEnvironment
• runner
• testRunner
• snapshotResolver

Miscellaneous breaking changes​

We removed some long-deprecated functions:

• jest.addMatchers (use expect.extend instead)
• jest.resetModuleRegistry (use jest.resetModules instead)
• jest.runTimersToTime (use jest.advanceTimersByTime instead)

A lot of Jest's packages have been migrated to use ESM-style exports (although they are still shipped as CommonJS), so if you consume e.g. pretty-format directly, you may need to adjust your import to a default import.

We dropped support for Node 13—but Jest always supports the Current and all LTS Node versions, and Jest 27 continues to support Node 10, which only recently became unmaintained.

As always, the full changelog and list of breaking changes can be viewed here.

Finally, we'd like to thank the community for once again awarding Jest a sky-high satisfaction rating of 96% in the State of JS 2020 survey! Stay safe everyone, and we hope you continue to enjoy using Jest in the years and versions to come! 🃏

The Jest site was upgraded from Docusaurus 1 to Docusaurus 2, and is an early adopter of the newly released Docusaurus 2 i18n support.

So, what's new exactly?

What's new?​

Here's a good overview of the most visible improvements:

• Dark Mode: change the color scheme through the navbar switch.

• Modern navigation: we improved the navigation experience with client-side routing and prefetching.

• Versions dropdown: it is now simpler to switch from one Jest version to another.

• Progressive-Web-App: you can install the Jest website and browse it offline.

• Search: try the new Algolia DocSearch v3 user-experience. It is now possible to search in blog posts.

• I18n: Jest is the first website using the new i18n feature of Docusaurus 2. It is now possible to translate blog posts.

• MDX: embedding React components in Markdown will allow maintainers to make the documentation more interactive.

For site translators​

If you want to help to translate the new Jest website, please use the new Crowdin project jest-v2 instead of the previous one.

Thanks​

Thanks to all the contributors that supported or reviewed this migration: Simen, Orta, Joel, Kristoffer...

Please report any problem on the migration issue.

We are now beginning to address this shortcoming and are working on reducing Jest’s install size while keeping it approachable and extensible. We have made the following breaking changes in Jest 26:

• [expect, jest-mock, pretty-format] Remove ES5 build files with a new minimum of support of ES2015 (Node 8) which were only used for browser builds (#9945)

  Migration: With this change, we are pushing the responsibility to bundle the affected packages to the users, rather than Jest providing them out of the box, since they know their target environments best. If you want it back, we're open to shipping these as separate packages. PRs welcome!

• [jest-config, jest-resolve] Remove support for browser field (#9943)

  Migration: Install browser-resolve module and use the following configuration:

  {
    "jest": {
      "resolver": "<rootDir>/resolver.js"
    }
  }
  

  // resolver.js
  const browserResolve = require('browser-resolve');
  
  module.exports = browserResolve.sync;
  

• TypeScript definitions requires a minimum of TypeScript v3.8 (#9823)

With the above changes Jest 26 is now 4 MiB smaller than Jest 25.5.4 (53 → 49 MiB). Please keep in mind that many dependencies like Babel are likely already part of your project. Jest's own size was reduced by 1.2 MiB (4.3 -> 3.1 MiB).

While this is a good start, it isn’t enough to make Jest meaningfully leaner. We are planning on gradually reducing Jest's and its dependency tree size by up to 70%. Most of the changes to reduce Jest’s default setup will be small breaking changes and we want to bring the community with us as much as possible. Therefore we will make the following changes in Jest 27 and Jest 28 using a “Tick-Tock" release process:

• Jest 27 will ship with a new test runner "jest-circus" and the Node.js environment by default. jest-jasmine2 and jest-environment-jsdom will still be bundled so users can keep using them by changing one-line each in the configuration.
• Jest 28 will remove jest-jasmine2 and jest-environment-jsdom from the default distribution of Jest. The packages will still be actively maintained as part of the Jest project and be published separately. Users will need to install these packages to use them.

Upon upgrading to these major releases, Jest will guide you through the necessary changes. If you’d like to get ahead and migrate to the new defaults now, and your project does not require a DOM environment, you can upgrade to Jest 26 and add the following configuration options:

{
  "jest": {
    "testEnvironment": "node",
    "testRunner": "jest-circus/runner"
  }
}

Jest will continue to ship with babel-jest enabled by default. It currently powers a few Jest features beyond compiling modern JavaScript syntax to something understood by current versions of Node.js and browsers: It also powers Jest's code coverage and mocking of ES modules. Jest currently ships with experimental support for V8 coverage and native support for ES Modules (more on that below!). It is not possible to mock static ES Modules per the specification without transforming the code first, so we will be encouraging patterns that work without the transformation we use Babel for today. Once V8 coverage and native ESM support stabilizes in Jest, we will also be able remove babel-jest as a default but we will keep maintaining it.

New fake timers​

With Jest 26 we are shipping a new implementation of fake timers based on @sinonjs/fake-timers. We've wanted to do this for years and are happy this has finally progressed far enough to support all of Jest's existing fake timer use cases.

The new implementation comes with extra features such as mocking Date, queueMicrotask and more, see this README. It works transparently using the existing timer APIs like jest.runAllTimers() – check out the documentation on our website.

We are confident this implementation is ready for prime time, however we don't want to force people to rewrite their tests if they depend on subtle differences between the old and new implementation. In Jest 26, this new implementation will remain opt-in and can be activated by calling jest.useFakeTimers('modern') or by passing modern to the timers option in your config if you opted all tests into fake timers previously.

In Jest 27 we will swap the default to the new "modern" implementation but we will keep supporting and maintaining the legacy implementation which can be used by calling jest.useFakeTimers('legacy'). If you are unsure whether you'll be able to upgrade all your tests by the time Jest 27 rolls out, you can add this to your tests now to keep the old behavior.

We'd like to thank Carl-Erik Kopseng, Benjamin Gruenbaum and other maintainers of @sinonjs/fake-timers for their help and patience when working with us to make this happen! Exciting.

A new way to consume Jest - @jest/globals​

Jest has relied on globals popularized by the Jasmine testing framework and others such as describe, it, test and expect. While this is a widely used pattern, many people have expressed their preference for importing testing related functions instead. To support this use case, we added a new package @jest/globals that can be used to import testing functions: import {expect, jest, test} from '@jest/globals';.

Caveats:

• Currently the globals still exist in the environment but we will introduce a mode to disable globals in the future. Similarly, you cannot use const jest = require('@jest/globals') as you'll get declaration errors because the jest variable is still a global for now.
• There is currently no way to add custom matchers to the TypeScript definitions when using globals like this.
• While this allows running tests without globals, it does not allow running tests without Jest's test runner at this time.

Native ESM support​

As mentioned in the Jest 25 blog post we have been working on native support for ECMAScript Modules. It is not stable yet but it is ready to be tested. We'd love to hear your feedback and bug reports! For an overview of the current state you can check out this issue, or browse all issues with that label ES Modules.

Other Breaking Changes in Jest 26​

• Dropped support for Node 8 (#9423)
• [jest-environment-jsdom] Upgrade jsdom to v16 (#9606)
• [jest-runtime] Remove long-deprecated require.requireActual and require.requireMock methods (#9854)
• [jest-haste-map] Removed providesModuleNodeModules (#8535)
• [jest-circus] Fail tests if a test takes a done callback and have return values (#9129)
• [jest-circus] Throw a proper error if a test / hooks is defined asynchronously (#8096)

Stay Safe​

We are all currently experiencing an unprecedented time of uncertainty. If you are struggling financially, we would like to use Jest’s Open Collective fund to help new and existing contributors. We place bounties on some issues and are open to offering a bounty on any of our current open issues - you can mention that an issue should have a bounty in the issue or contact @cpojer via private message on Twitter.

Please stay safe.

There has been more than 200 commits since Jest 24.9 by more than 80 different contributors, so as always, take a look at the changelog for a full list of changes.

Bye Node 6​

Node 6 has been EOL since April 30th 2019, and Jest 25 leaves it behind. Dropping Node 6 means we can upgrade our dependencies, the main one being JSDOM, which has been upgraded to version 15. Upgrading also means we no longer have to transpile async-await syntax, which results in both faster code execution and less memory consumption. As a bonus, Jest’s transpiled code should be easier to debug if anyone finds themselves tumbling down that particular rabbit hole.

Even though Node 8 has also entered EOL, Jest 25 will keep support for it to make the upgrade as easy as possible for those of us who still support Node 8. It does come with some tradeoffs though, such as JSDOM v16 having been released without Node 8 support, so you'll need to use jest-environment-jsdom-sixteen if you want to use the latest version.

Performance improvements​

We’ve gotten reports that Jest has slowed down over the last couple of releases. Jest 25 includes upgraded Micromatch, which brings huge gains in startup time, and some bug fixes and performance tweaks which brings Jest back to the speed it was at for Jest 23. For Jest itself, like mentioned at the beginning of this post, that means a 10-15% reduction of test runtime. We're always looking to improve here of course, so please check how it stacks up against earlier versions and create issues if we should be better!

V8 Code Coverage​

Jest’s current code coverage instrumentation is powered by babel-plugin-istanbul inserting code coverage collection code before creating reports. However, this is quite slow and memory-intensive, especially for large files and code bases. Luckily, V8 has built-in code coverage, which is becoming more and more usable in Node thanks to the hard work of Benjamin Coe and others on the V8 and Node.js teams. Jest 25 comes with experimental support for this via a new --coverage-provider flag. Please see its documentation for caveats and how to use it.

Thinking fast and slow when tests fail​

Unnecessary effort to interpret the reports when tests fail hinders:

• “thinking fast” to recognize patterns from your past experience
• “thinking slow” to analyze changes and decide whether they are expected progress or unexpected regressions

Jest 25 completes the second half of an effort begun in Jest 24 to improve all matchers:

• correct description line, including .rejects, .resolves, and .not modifiers
• concise labels and consistent alignment for expected and received values
• inverse highlight of substring differences when expected and received are strings
• counts of change lines in differences to know if they are only delete or insert

Special thanks to Jest maintainer Mark Pedrotti for driving this effort and his continued work towards making expectation errors as good as they can be.

Colors of differences when snapshot tests fail​

The most obvious change to replace confusion with confidence is the colors of change lines in differences when snapshot tests fail:

• - Snapshot changes from green to magenta
• + Received changes from red to teal foreground on cyan/aqua background

Examples of snapshot test reports (before at left and after at right)

1. Counts of changed lines confirm your first impression which way did the snapshot change (that is, deleted or inserted lines)

2. Background colors attract your eyes to compare adjacent changed lines

3. Background colors also help you see which toThrow tests require a decision whether or not to update the snapshot

Here are some reasons why we chose unique colors:

• The 95% of people who have full color vision can quickly recognize which reports are from snapshot tests versus all other matchers.
• It solves the direct conflict between meaning of green/red in Jest tests versus red/green in code review.
• Unlike a reversal to red/green which suggests that update is the default decision, it suggests that differences require more careful review for possible regression in local snapshot test failures than in code review (when problems have already been fixed).

The difference in hue from magenta at 300° to teal/cyan/aqua at 180° gives better color vision accessibility and the light background tint for changed lines gives consistent contrast on light and dark themes.

If you maintain a command line tool, you might find inspiration to improve its accessibility in #9132.

ECMAScript Modules support​

Node 13 has unflagged ESM support, and we have started a tiny bit working towards native support in Jest. Jest 25 includes support for jest.config.cjs and jest.config.mjs configuration files, but tests themselves cannot yet be written using ESM without something like Babel or TypeScript transforming it into CJS.

The APIs Jest will use are still flagged and experimental, so don't expect support right away. These APIs are something the Node.js Modules team is actively working on, and we'll be keeping an eye on it moving forward and experiment with them so we can provide feedback. You can subscribe to this issue to get any updates about the implementation status in Jest.

Other improvements and updates​

• Jest has passed 1000 unique contributors. This is an incredible milestone! Thank you to everybody who helps us make testing as delightful as possible.
• Thanks to community member Josh Rosenstein, Jest now comes with support for BigInt in most matchers, such as toBeGreaterThan. Jest will also understand bigint literals out of the box.
• Jest’s feature --detect-leaks has been broken for Node 12 and newer - this has been fixed in Jest 25.
• As announced in the blog post for Jest 24, Jest’s code base has been rewritten in TypeScript - this work was completed in Jest 24.3. So if you use any of Jest’s individual parts, you should get great IDE integration. Looking forward, we really want to make Jest mocks play nicer with type systems, and we’d love the community’s help with this. Please chime in here with ideas and send PRs! We’ll also be investigating moving the typings for using Jest as a test runner from DefinitelyTyped into Jest itself.
• The jest-diff package now exports functions like diffLinesUnified and diffStringsUnified which have configuration options, so other applications can format differences in a custom way. For more information and code examples, see its new README.md file in the Jest repository or on package repositories.
• Thanks to community member Wei An Yen, Jest will no longer highlight passing asymmetric matchers in expectation errors. This has been a long-standing pain point with asymmetric matchers and we're very happy it's finally solved.
• For the second year running, Jest won the Highest Satisfaction award from State of JS. We are incredibly grateful for the support from the community, and hope we can build on this momentum to make 2020 even better!

Plans for the future​

• Jest’s configuration is vast and somewhat clunky - there is often at least two ways of doing the same thing, oftentimes even more. For Jest 26 we hope to condense the config down, and make it more predictable. See this issue for details.
• We also hope to be able to provide a proper programmatic API for running Jest, to make integration into IDEs and other tooling easier. Please see this tracking issue.
• There’s been an open PR for adding Lolex as an implementation of Jest’s fake timers since December 2017. While we’re not adding it to any public APIs in Jest 25, support for it is technically included and you we're looking into how to expose this so people can test and experiment with it. Using it means you can mock out Date and other timer function Jest currently doesn’t touch. Note that this should be considered experimental, and a proper API support will come in a later release. Follow this PR for the latest updates on the status.

Happy Jesting! 🃏

For a full list of all changes see the changelog.

New Website​

@orta has provided a beautiful redesign of Jest's website, which has been implemented by community members @montogeek and @brainkim.

The aim of the redesign was to highlight more of what makes Jest awesome, and to decouple the idea that Jest is primarily a tool for testing React apps - you can use Jest with all sorts of projects and we want to make that obvious. You can read more about the ideas behind the redesign in this issue.

TypeScript support​

We've upgraded to Babel 7 internally for Jest 24, which comes with support for TypeScript projects. That means Jest can support transpiling TypeScript out of the box, as long as you configure Babel to use it with @babel/preset-typescript. One caveat to the default TypeScript support, similar to Flow, is that Babel will only strip out the type annotations to make your code valid JavaScript. It will not typecheck your code.

While Jest has supported Babel 7 since version 22 released in December 2017, it required usage of a bridge module in order to fit in with Jest's support of Babel 6. In Jest 24 we have migrated entirely over to Babel 7, with great help from community member @milesj. This means that setup is now easier and we can take advantage of other Babel 7 features, such as config loading and automatic modules transpilation. Make sure to remove the babel-core@^7.0.0-bridge.0 as it's not needed now.

If you want to run typechecks while you test, you should use ts-jest. You will need to configure the transformer, as Jest by default applies Babel to .ts (and .tsx) files. Alternatively, you can run tsc or even use a Jest runner to simultaneously transpile your TypeScript whilst running your tests! See jest-runner-tsc for more information.

See the docs for more details.

test.todo​

Jest 23 had a change that made tests missing an implementation throw instead of being skipped. This change was made due to feedback that accidentally skipped tests were hard to discover and hard to track down. However, this change broke the workflow for quite a few developers who used the feature to sketch out which tests to write.

In Jest 24, we are addressing this issue by adding an explicit test.todo (inspired by the excellent AVA), which will be printed separately in the test summary. It allows you to quickly sketch out which tests you want to write and in the future, an ESLint rule might even be able to warn you that you have forgotten to write out some tests.

test.todo('invalid input should throw');

test.todo('missing options should be normalized');

Improved Assertion Messages​

When tests fail, you need to make confident and correct decisions which changes are expected progress and which changes are unexpected regressions. It is especially important not to miss a few regressions hidden among much progress. Jest 24 makes reports when assertions fail more clear and concise for several matchers. Because the effort will continue in Jest 25, you might notice some temporary inconsistencies. If your tests never fail, then you won't get to see them - for the rest of us, it'll be easier to debug why something isn't working as expected. Thanks for the hard work by @ittordepam and other contributors from the community.

You can see these changes across all these PRs: 7621, 7557, 7448, 7325, 7241, 7152, 7125, 7107, 6961.

Examples:

Failing assertion

Type mismatch

Mock function not called

Fixing old pain​

We've fixed a couple of really old issues in this release.

The first one we'd like to highlight is console.log statements going missing. Jest intercepts and collects all logs in order to give you a stack trace to them, as well as provide them to reporters so you can handle them however you want. However, this has led to an issue where they have simply been missing in certain edge cases. Luckily for Jest 24, @spion has stepped up and fixed this issue. Thank you very much!

The second one is an issue where Jest runs out of memory if the difference in serialization of expected and received value has a huge number of insertion changes (either unexpected because of mistake in test or defect in serializer or expected because of temporary failures during test-driven development). @ittordepam has replaced the previous diffing algorithm with diff-sequences package, which should fix this issue because it uses the theoretical minimum amount of memory. It opens up possibility for word-diffs in the future, similar to what git provides. Please see this PR and don't hesitate to reach out if you want to help make that happen!

Other highlights​

• We have some improvements for globalSetup and globalTeardown as well - code transformation will be applied to them similar to setupFiles and they are now supported as part of projects.
• You can configure Jest's snapshot location, this is mainly useful if you are building tools which use Jest in a larger build process.
• A quirk of Jest's CLI has been that while some flags and options have been camel cased (such as runInBand), others have not been (such as no-cache). In Jest 24, both are recognized, meaning you can write your CLI arguments however you want.
• We've renamed setupTestFrameworkScriptFile to setupFilesAfterEnv, and made it into an array. We hope this will make it more obvious what the options is for. We have plans to further overhaul the configuration in the next major, see the paragraph in the section below.
• To reduce the amount of magic Jest performs to “just work™”, in this release we decided to drop automatic injection of regenerator-runtime, which is sometimes used in compiled async code. Including regenerator-runtime is not always necessary and we believe it's the user's responsibility to include it if it's needed. If you use @babel/preset-env with targets set to a modern Node version (e.g. Node 6+) you will not need to include it. Please see our Using Babel docs for more information.
• Node.js 10 came with an experimental module called worker_threads, which is similar to Worker threads in the browser. jest-worker, part of the Jest platform, will be able to use worker_threads if available instead of child_process, which makes it even faster! Benchmarks show a 50% improvement. Due to its experimental nature, it's not enabled when using Jest as a test runner, but you can use it in your own projects today! We plan to enable it by default when it's promoted from experimental status in Node.js.

Breaking Changes​

While all breaking changes are listed in the changelog, there's a few of them that are worth highlighting:

• We've upgraded to Micromatch 3. While this might not affect every user, it is stricter in its parsing of globs than version 2, which is used in Jest 23. Please read through this and linked issues for examples of invalid globs in case you have problems.
• We've removed code remnants that was needed for Node 4. It was previously technically possible to run Jest 23 on Node 4 - that is no longer possible without polyfilling and transpiling.
• Some changes to serialization of mock functions in snapshots - make sure to double check your updated snapshots after upgrading. Related PR.
• Jest no longer automatically injects regenerator-runtime - if you get errors concerning it, make sure to configure Babel to properly transpile async functions, using e.g. @babel/preset-env. Related PR.

The future​

We are incredibly humbled by the results in State Of JS 2018, where Jest won the “Highest Satisfaction” award. Another huge thing to happen in 2018 was in October, when Jest passed 2 million weekly downloads for the first time. Thank you.

We are very thankful for the trust in us shown by the community, and hope to build on it in the future. We will ensure Jest 24 and future releases will continue to build upon this incredible foundation, and continue to be an integral part of JavaScript developers' toolkits.

This has been the first release where we have explored the idea of using our Open Collective funding to create bug bounties. This worked well in getting non-core developers involved in the implementation of the new landing page, and we're optimistic for a long running bug where Jest globals are mismatched from Node globals. We'd like to do more, if you have a pet bug that's a good candidate for our bounty program, please let us know. In the meantime, you can find all the tickets with a bounty via the issue label.

We have already started to make plans for the next release of Jest 25, with the biggest planned feature being an overhaul of our configuration, which is pretty hard to grok, mainly because of overlapping option and mixing globs and regular expressions. Feedback on how you want Jest's configuration to look is very much welcome, and can be submitted in this issue.

You might also have heard that we are planning to migrate the code base from Flow to TypeScript. We are hopeful that this migration will enable even more contributors to jump in and help make 2019 even better for JavaScript testing. 🚀 The plan is to land this in a minor release in the not too distant future. Feedback on this choice can be added to the RFC.

Lastly, if you've ever wondered about how Jest is built, @cpojer has recorded a video with an architectural overview of how Jest is put together under the hood. Feel free to reach out if you have any further questions about it. The video is available on our website.

Happy Jesting! 🃏

Our open source contributors work on behalf of the community to create new features, fix bugs, and maintain the issue backlog. Facebook employees do the same, focused on the problems specific to Facebook's scale, and run all proposed releases on Facebook's enormous test suite before publishing.

All of us do our part to make testing delightful.

At the Jest Summit we announced the Jest Open Collective. This is our way to help support the efforts of the open source Jest community. To be absolutely clear: Facebook employees cannot benefit from the Jest Open Collective. The collective's sole purpose is to support the open source side of the Jest community.

In this post we'll outline what the Jest Open Collective is, the structure, and the goals we have.

The Jest Open Collective​

Open Collective is a platform to manage groups of people transparently. Jest joins projects like webpack, Babel, Mocha, Preact, Vue, and many more in supporting the open source community through the Open Collective platform.

What is the Jest Open Collective​

The Jest Open Collective is a group of open source contributors who operate in full transparency to:

• Receive funds from backers and sponsors
• Approve expenses submitted by the community
• Give everyone visibility on the budget

What is the structure of the collective​

The Jest Open Collective is currently managed by three non-Facebook core contributors from the open source community:

• Michal Pierzchala
• Simen Bekkhus
• Rick Hanlon

Michal has been an active Jest contributor since September 2016, Simen joined the core team in June 2017, and Rick joined in January. They're responsible for setting the budget, approving expenses, and managing admins of the collective. We have elected to keep Christoph Nakazawa as an adviser.

There are two levels of support for the collective: Backer and Sponsor.

Backers​

Backers of the collective are individuals contributing at least $2/month. We'll include a list of backers on the Jest homepage, README on github/yarn/npm, and Contributors page.

Sponsors​

Sponsors of the collective are individuals and organizations contributing at least $100/month. We'll place sponsor logos with a link to their site on the Jest homepage, README on github/yarn/npm, and Contributors page.

What is the goal of the collective​

The goal of the collective is to support the work of open source contributors to Jest in order to make testing delightful.

To achieve that goal, we will use the funds to:

• Cover speaker travel expenses
• Host events and meetups
• Print and distribute swag
• Develop and fund a bug bounty program (TBD)

This is just the beginning and we're committed to getting this right. If you have ideas on how else we can support the community, or feedback on the structure of the collective, please reach out to us on twitter!

Thank You​

Finally, thank you to everyone who contributes to the Jest community and open source in general. We are incredibly grateful that we get the opportunity to work on improving JavaScript testing together.

The Jest core team would also like to make a special thank you to Facebook Open Source for driving the creation of this collective.

We would also like to welcome both Babel and webpack to the Jest community! After converting from Mocha to Jest 23 Beta, webpack saw their total test suite time reduced 6x from over 13 minutes to 2 minutes 20 seconds. #blazingmeansgood

Here's are some of the Jest 23 highlights and breaking changes.

For a full list see the changelog.

Interactive Snapshot Mode​

We've added a new default watch menu option we're calling Interactive Snapshot Mode. This new mode allows you to step through each failing snapshot in each failing suite to review your failed snapshots and choose to update or skip each individually.

See the Interactive Snapshot Mode docs here.

Snapshot Property Matchers​

Often, objects you're snapshotting contain generated values like Dates and IDs. Jest now allows you to pass properties to the snapshot matcher which specify the structure of the data instead of the specific values. These property matchers are then verified before serializing the matcher type (instead of the value), giving you consistent snapshot results across test runs.

See the updated toMatchSnapshot docs or the Property Matcher guide for more information.

Custom Asynchronous matchers​

We now support asynchronous matchers with expect.extends! Async matchers return a Promise so that you can await for the matcher to resolve. As an example:

Docs available here.

Custom Asymmetric Matchers​

Asymmetric matchers are a great tool to use when you only care about asymmetric equality. For example, when the left side is expected to be an object with some subset of properties on the right, instead of an exact match. Jest provides a number of asymmetric matchers out of the box, and in this release we're introducing Custom Asymmetric Matchers.

Jest Each​

@mattphillipsio has donated the jest-each package to Jest Core (thanks Matt!). jest-each is a library inspired by mocha-each and Spock Data Tables which allows you to define a table of test cases, and then run a test for each row with the specified column values. We support both array types and template literals for all flavors of describe and test. Docs are available here, and for those not on Jest 23 yet, we're still publishing jest-each separately!

Huge shout out to Prettier for fixing the table formatting so quickly (see Prettier 1.13)!

New Matchers​

We only add matchers to core if we believe they will be useful to a large amount of people in the Jest community, and leave the majority of matchers to the community (see jest-extended). Some matchers make the cut into core, and Jest 23 adds:

• nthCalledWith
• toReturn
• toReturnTimes
• toReturnWith
• lastReturnedWith
• nthReturnedWith
• toStrictEqual

See the updated expect docs here.

Debug Hanging Tests​

A common issue we see on the issue tracker relates to “Jest” hanging after a test run. This is usually due to app code leaving handles open, preventing Jest from exiting. In the past, users have resorted to --forceExit to fix (not recommended).

To help debug these issues, we're now detecting when Jest does not exit:

And we offer a new flag --detectOpenHandles to help find the open handles:

See the updated CLI docs here.

Watch Mode Plugins​

We have completely rewritten the watch mode system to allow adding custom plugins to watch mode. Watch Mode Plugins now make it possible to hook into Jest events and provide custom menu options in the Watch Mode Menu. All of the default Watch Mode prompts are implemented as plugins in this system, and the docs to create your own are available here.

With this change, we're also now able to bring back typeahead support as a Watch Mode Plugin via jest-watch-typeahead!

See jest-watch-typeahead for documentation and install instructions. Huge thank you to @rogeliog for the new watch mode plugin system and the jest-watch-typeahead plugin!

Breaking Changes​

As with every major release, we are making a few breaking changes to make larger changes in the future possible and to push the testing experience to a new level. Here's a list of the biggest changes you may see:

• Require test descriptions and functions: We're now failing tests that do not include both a function and a description.
• Remove undefined props from React snapshots: Smaller snapshots and proper React behavior.
• Remove deprecations: We removed mapCoverage since it's no longer needed. Additionally, we removed jest.genMockFunction and jest.genMockFn since these are the same as jest.fn.
• Add snapshot names to failures: We added the snapshot name (if provided) to the snapshot failure message so it's easier to find the snapshot that's failing.
• Replace mock timestamps: We replaced mock timestamps with invocationCallOrder since two or mocks may often have the same timestamp, making it impossible to test the call order.
• Add results to mock snapshots: We added mock function call results to snapshots so that both the calls and the results of the invocation are tracked.

Other Improvements​

• Watch mode coverage: Coverage is now limited to only the files tested in watch mode or when using --onlyChanged and --findRelatedTests.
• Version documentation: We added docs for each minor release back to Jest 22, and have removed all of the “Requires Jest X.X+” from the docs.
• Better snapshot summaries: We overhauled the Snapshot Summary output to make obsolete snapshots more informative.
• Better stack traces: We added stack traces to asynchronous errors, timeout errors, expect.assertions, and thrown non-errors. We're also indicating the column in the code frame!
• Better React 16 support: Adds snapshot support for React.Fragment, React.forwardRef, and React.createContext.
• Track mock return and throw values: Adds mock.results that contains the return value or thrown value for each mock call.
• Blazing 🔥: We've added a blazing badge to the README to indicate that Jest is blazing good.

Jest Summit​

Last week, the Jest Core Team met for the Jest Summit at Facebook London where worked on and released Jest 23, announced the Jest Open Collective, and gave a number of talks:

• Christoph Nakazawa – Intro
• Aaron Abramov – Writing Meaningful Tests
• Rick Hanlon II – Blazing Fast Snapshot Testing in Jest 23
• Simen Bekkhus – Jest's Delightful Error Messages
• Matt Phillips – Level up your Jest experience with community packages
• Michele Bertoli – Snapshot all the things
• Jordan Eldredge – Webamp: Learn by imitating

Full talk is available here.

The turnout was amazing, and we were able to meet a lot of the London-based community in person. Thank you to everyone who joined us and for your continued support! Stay tuned for our next post which will outline the Jest Open Collective and the plans we have for the future.

As always, this release couldn't have been possible without you, the JavaScript community. We are incredibly grateful that we get the opportunity to work on improving JavaScript testing together. If you'd like to contribute to Jest, please don't hesitate to reach out to us on GitHub or on Discord.

Good bye Node 4 & welcome JSDOM 11​

With this release we are dropping support for Node 4, mainly because one of our main dependencies, JSDOM, ended their support. Jest now comes out of the box with JSDOM 11 which features better support for SVGs, requestAnimationFrame, URL and URLSearchParams built in, and much more.

Custom Runners + Easy parallelization with jest-worker​

In Jest 21 we introduced the concept of custom Jest runners. Since then, Rogelio, one of Jest's core contributors, built a number of useful runners: If you have many existing tests written using another framework but you'd like to immediately benefit from Jest's features, check out jest-runner-mocha. If you have a large codebase that needs linting, you may get a significant speedup if you run eslint within Jest using jest-runner-eslint.

To gain more of fine-grained control over heavy tasks parallelization (e.g. transforming files or crawling the file system), we designed a new library perfectly suited for the job. We developed a modern, Promise-based module with an approachable API, called jest-worker, that allows you to delegate to child processes those intensive functions. As jest-worker, like any other Jest package, is a part of the Jest platform, you can use it however you like even without ever using Jest itself. You'll find more in the documentation here.

To get a better understanding of custom runners and Jest as a platform, make sure to check out Rogelio's talk from Reactive Conf 2017: Jest as a Platform.

Codeframe in test failures​

In order to more easily identify which assertion is failing your test, we've added a code frame showing the context where the assertion is in order to focus on your own code. See the following example test:

test('some test', () => {
  function someFunctionWhichShouldThrow() {
    if (false) {
      throw new Error();
    }

    return 'success!';
  }

  expect(someFunctionWhichShouldThrow).toThrow();
});

In Jest 21, we would display the following error:

In Jest 22, we have added a codeframe, giving more context to the failing assertions. We have also cleaned up the stack trace to remove more clutter than ever.

Easier testing of errors thrown in async code​

You can now use toThrow and toThrowErrorMatchingSnapshot on promise rejections in the same way you can on synchronous errors.

async function throwingFunction() {
  throw new Error('This failed');
}

test('asynchronous rejection', async () => {
  await expect(throwingFunction()).rejects.toThrowErrorMatchingSnapshot();
});

Asynchronous test environments​

When Puppeteer, a way of programmatically interacting with a real Chromium Browser, was announced by the Google Chrome team in August, many wanted to be able to use Jest to write their tests running them in Chrome. The community have helped us out making this possible by allowing asynchronous test environments. We are still working on making this experience as good as possible, but please see this guide for how to use Puppeteer with Jest, starting today.

Experimental Leak Detection​

We added an experimental --detectLeaks setting to Jest that will let you know if your internal environment instance is leaked after a test execution. It will also warn you when your test suite tries to require a file after the test has finished, meaning you forgot to wait for all async operations or left something not properly cleaned. This will however not discover leaks in user land code, only in test land code; although the technology used behind it can help you (see jest-leak-detector). If you are reporting a bug about Jest's memory usage, please provide a repro where --detectLeaks will make the test suite fail. We started building a better sandboxing mechanism for Jest but it's not ready yet to be enabled by default. If you'd like to help, please reach out to us on discord!

Watch Mode Refinements​

When using watch mode, there is now a way to focus only on tests that previously failed. In this mode, Jest will not re-run previously passing tests which should help you iron out all test failures. Additionally, we added a plugin system to watch mode. By adding modules to watchPlugins in your configuration you can extend the features of the watch mode.

Babel 7 support​

Jest uses Babel under the hood to power code coverage and advanced mocking features. With Jest 22, it also supports the upcoming Babel 7. You'll find more in the documentation here.

Mock function improvements​

There has been a couple of changes to mock functions in Jest 22, making them even easier to use. Firstly, we added a mockName property allowing you to name your mocks, which is useful in assertion failures. We have also made the Jest mock function serializable in pretty-format, meaning that you can snapshot test mocks. In Jest 21, expect(jest.fn()).toMatchSnapshot() would serialize to [Function], in Jest 22, you might get something like this:

test('my mocking test', () => {
  const mock = jest.fn().mockName('myMock');

  mock('hello', {foo: 'bar'});

  expect(mock).toMatchSnapshot();
});

// Serializes to:

exports[`my mocking test 1`] = `
[MockFunction myMock] {
  "calls": Array [
    Array [
      "hello",
      Object {
        "foo": "bar",
      },
    ],
  ],
}
`;

Highlights from Jest 21​

Jest 21 was released back in September, and we unfortunately never got around to write a blog post. So here is a quick summary of the main changes in version 21:

1. Use expect and jest-mock in the browser: Michael Jackson donated his excellent expect package to the Jest project. As part of that transition, the Jest core team, with much help from Kenneth Skovhus, made both jest-matchers (renamed to expect) and jest-mock work in browsers. This means that while you cannot use Jest itself in browsers (yet), you can use its awesome assertions and mocks for instance as replacements for Chai and Sinon running in Mocha tests. If you are migrating from earlier expect to the new Jest-powered expect, you can use jest-codemods to automate the migration.
2. MIT License: We changed Jest's license to MIT. Yay!
3. Fail test suites on async errors: Jest used to have a bug that made it crash when errors were thrown in certain parts of async code. This was fixed by community contributors.
4. Faster startup: With Jest 21 we fine tuned Jest's startup to be more than 50% faster. The large overhead of Jest when running it on a small and fast test was always an issue for us and now this shouldn't be a reason to hold you back from using Jest any longer.

Jest Community​

The community around Jest is working hard to make the testing experience even greater. These are separate projects from the main Jest project, but we want to highlight some of our personal favorites here.

• jest-image-snapshot – custom matcher to compare images with snapshots by American Express developers
• ts-jest – all you need to successfully run Jest within TypeScript project by @kulshekhar
• jest-codemods – migrate your tests from other frameworks to Jest with ease
• jest-plugins – a new community project oriented around simplifying setting up test environment for specific tools, like React, or providing some handy utilities

We'd also like to announce that recently we launched a new place for high quality Jest additions – jest-community. It's a new GitHub organization already featuring our favorite projects, like vscode-jest, jest-extended, to name a few, curated by Jest maintainers and collaborators. We've even migrated our eslint-plugin-jest there, and already see some great contributions, which are published independently at a faster pace.

Community projects under one organisation are also a great way for us to experiment on things like automated releases, which we'd like to explore for Jest as well. They also enable us to share some common things between them, like the shape of the README for example (thanks to the webpack Community for the idea), making it easier to learn and use for all of us.

If you have something awesome to share, feel free to reach out to us! We'd love to share your project here.

Multi-Project-Runner & Configuration Overhaul​

Until now, Jest could only operate in one project at a time. This is often cumbersome if you are working on many smaller projects that each have their own setup and configuration. With Jest 20, we rewrote the test runner completely to run many projects at the same time within a single instance of Jest, for example if you are working on a React frontend and a node.js backend. Here is a video of Jest running tests for React, Relay, Yarn and Jest all at the same time:

Jest is now collapsing the usage guide after the first test run to save vertical space in the terminal.

Further, we completely overhauled how the configuration system works inside of Jest. You can now pass any configuration option through the CLI to overwrite the ones specified in your configuration file. Along with that, we changed Jest to look for a jest.config.js file by default which means you are now able to define a Jest configuration using JavaScript as well as being able to configure it through package.json like before. Through the addition of all these new features, you are now able to combine Jest in more powerful ways than ever before. For example, if you would like to find out which tests Jest would run given a set of changed files from a commit across multiple projects in a monorepo, you can combine cli arguments like this now:

$ jest --projects projectA projectB --listTests --findRelatedTests projectA/banana.js projectB/kiwi.js
[
  "projectA/banana.test.js",
  "projectB/kiwi.test.js",
  "projectB/pineapple.test.js",
]

This is especially useful for continuous integration (CI) systems where you may want to only run a subset of tests for Pull Requests to prevent Jest from running thousands of test files on every small change.

Finally, we are now properly mapping code coverage when using TypeScript and we are running code coverage for untested files in worker processes which yields significant speed ups for this feature.

New & Improved Testing APIs​

We made a number of additions and improvements to the testing APIs which will help write more effective tests. We'd like to point out that all of these improvements were made entirely by community members!

• Better async testing: Added new async/Promise support through resolves/rejects modifiers on expect: expect(Promise(…)).resolves.toEqual(…). See documentation.
• Expect n assertions: Along with the existing expect.assertions(n), the new expect.hasAssertions() can be used to ensure a test has at least one assertion.
• Lint Plugin: A valid-expect rule was added to eslint-plugin-jest to ensure that an assertion is called after invoking expect. This will prevent mistakes like a stray expect(banana); with a missing assertion call.
• Pretty-Format Plugins: A number of new pretty-format plugins were added to Jest. We now pretty-print Immutable.js data structures and HtmlElements in assertion failures and snapshots.
• Custom Environment: It is now possible to add a @jest-environment node|jsdom annotation to the doc-block comment of a test file to use a test environment different from the default for individual tests.

Here is an example of all how all the new APIs together will make testing more delightful:

/**
 * @jest-environment node
 */

test('compares apples and bananas', async () => {
  expect.hasAssertions(); // Ensure this test has at least one assertion.

  await expect(
    Promise.resolve(Immutable.Map({apples: 1, bananas: 2})),
  ).resolves.toEqual(Immutable.Map({apples: 1, bananas: 3}));

  expect('banana'); // valid-expect in eslint-plugin-jest will show an error.
});

This example will print a test failure similar to this:

Breaking Changes​

As with every major release, we are making a number of breaking changes to make larger changes in the future possible and to push the testing experience to a new level. This time, we tried our best to only break APIs that we don't expect to affect the majority of Jest's users:

• Fork of Jasmine 2.5: We finally decided to fork Jasmine itself and take ownership over Jest's own test runner. This will allow us to improve all aspects of the unit testing experience in the future but for now we are focused on incremental rewrites and reducing the API surface. If you see a test breaking as a result of a Jasmine API that is now missing, there should be an equivalent feature on the jest or expect objects. As such, we have removed many Jasmine features that aren't generally used in most codebases.
• New Snapshots on CI: Snapshots must always be committed along with the test and the modules they are testing. We changed Jest to not save new snapshots automatically in Continuous Integration (CI) environments or when the --ci flag is specified. To overwrite this behavior, which is generally not recommended, the --updateSnapshot flag can be used.
• Babel-Polyfill: Jest used to load babel-polyfill automatically when using babel-jest which resulted in memory leaks inside of Jest. In most versions of node, it is not necessary to load babel-polyfill so we removed this auto-inclusion and instead changed Jest to only include regenerator-runtime by default, which is commonly used to support async/await in older versions of Node.js. If you need babel-polyfill, you can manually require it in your setup files.

Other Improvements​

• Documentation: Documentation is critical to share best practices and teach everyone how to write effective tests which will lead to better software. Over the last few weeks we have also expanded Jest's documentation to include a Snapshot Testing FAQ, a guide with information about how to use Jest with common JavaScript libraries as well as we documented the new features mentioned above.
• Translations: We are now asking for your help to translate the Jest documentation to make it easier for people to learn how to use Jest.
• Custom Reporters: Jest now supports custom test reporters through the reporters configuration option. You can finally customize the output of Jest as well as integrate it with other tools by generating reports in formats such as XML. See documentation.
• Codebase Health: It was only possible iterate so quickly in Jest because we spent a significant amount of time on the health of the codebase. We were one of the early adopters of prettier, we notably increased flow coverage, forked Jasmine to improve our test runner library and we rewrote and refactored significant portions of Jest itself to set up Jest for success in the future.
• Bugfixes: As always, we made plenty of bugfixes in Jest. The full changelog can be found in the Jest repository.

Talks about Jest​

Recently the Jest core team and other contributors started to talk more about Jest and the experience of working on Jest at conferences:

• Rogelio Guzman did a talk about Jest Snapshots and Beyond at React Conf.
• I spoke about Building High-Quality JavaScript Tools at Facebook's F8 conference.

As always, this release couldn't have been possible without you, the JavaScript community. We are incredibly grateful that we get the opportunity to work on improving JavaScript testing together. If you'd like to contribute to Jest, please don't hesitate to reach out to us on GitHub or on Discord.

Immersive Watch Mode​

We completely rewrote the watch mode to make it instant and more extensible. As a result, the experience of using it really is immersive: tests re-run instantly after a file change and we made it easy to select the right tests.

Snapshot Updates​

We made a couple of changes to the snapshot format. We don't make changes like this often and only consider them if they actually improve how snapshots work. As well as introducing a snapshot version number we accumulated a number of changes we wanted to make to the format for a while:

• We dropped the “test” prefix in snapshot names from top level test or it calls.
• We improved the printing of React elements to cause less changes when the last prop in an element changes.
• We improved the character escaping mechanism to be more bulletproof.

Before:

exports[`test snap 1`] = `
<header>
  <h1>
    Jest \"19\"
  </h1>
  <Subtitle
    name="Painless JavaScript Testing" />
</header>
`;

After (no “test” prefix, better JSX rendering, version header):

// Jest Snapshot v1, https://goo.gl/fbAQLP

exports[`snap 1`] = `
<header>
  <h1>
    Jest "19"
  </h1>
  <Subtitle
    name="Painless JavaScript Testing"
  />
</header>
`;

We decided it's a good time to introduce versioned snapshots to ensure all developers are using a compatible version of Jest. Here's how we warn you about the need to update your snapshot:

Please make sure you revert any local changes before updating to make the transition smooth and to ensure you aren't including any unwanted changes from failing tests in your new snapshots.

Improved printing of skipped tests​

Skipped tests are now printed as a single line instead of showing every individual one when testing in verbose mode or a single suite. Hopefully it will let you focus on currently important tests. It also occupies far less space!

New CLI arguments​

Jest 19 ships with two new coverage-related arguments which you can run from CLI:

• --collectCoverageFrom
• --coverageDirectory

We now also error on invalid CLI arguments instead of ignoring them. But we've got your back with helpful error message like the one below, e.g. when you try running jest --watc:

expect Improvements​

• expect.addSnapshotSerializer
• expect.stringContaining
• jest.spyOn

We're close to almost full feature parity with the expect npm package. Michael Jackson, the author of the package, agreed to donate it to the Jest project, which means that jest-matchers will be renamed to expect. Since our version of expect is not intended to be fully compatible, Christopher Chedeau is working on a codemod to make the transition painless. Christopher also worked on a number of improvements to jest-matchers which enables it to be used outside of Jest and even works inside browsers.

eslint-plugin-jest – our very own ESLint plugin​

Thanks to Jonathan Kim Jest finally has its own official ESLint plugin. It exposes three rules:

• no-disabled-tests - this rule prevents you from accidentally committing disabled tests.
• no-focused-tests - this rule prevents you from committing focused tests which would disable all other tests in the same suite.
• no-identical-title - disallows identical titles in test names.

You can install it using npm install --save-dev eslint-plugin-jest or yarn add --dev eslint eslint-plugin-jest and it can be enabled by adding {"plugins": ["jest"]} to your eslint configuration.

New public package: jest-validate​

While we refactored the validation and normalization code for Jest's configuration, we were so happy with the new error messaging that we extracted it to its own module to share it with everyone. With Jest 19 we welcome jest-validate to our self-sustained packages family.

jest-validate is a generic configuration validation tool that helps you with warnings, errors and deprecation messages in your JavaScript tool. It's also capable of showing users friendly examples of correct configuration and it comes with a simple but powerful API. We hope it'll make a good addition to your projects!

We're happy to announce that jest-validate is validating config options of prettier since v0.12. Feel free to add it to your project, try it, send us feedback and improve it by making pull requests on GitHub.

Improved asymmetric matchers​

We moved the asymmetric matchers implementation from Jasmine into Jest, which enabled us to further improve the user experience around them. As a result, asymmetric matchers are now pretty-printed nicely, we added the new expect.stringContaining() matcher and we also paired them with expect.toMatchObject() so you can use the best of both:

Better manual mocks​

With the latest release, manual mocks now finally work with nested folders. For example __mocks__/react-native/Libraries/Text/Text.js will now work as expected and mock the correct module. We also fixed issues with virtual mocks and transitive dependencies and improved moduleNameMapper to not overwrite mocks when many patterns map to the same file.

Breaking Changes​

As a part of our cleanups and fixes we removed the mocksPattern configuration option which was never officially supported. We also renamed the testPathDirs configuration option to roots which better explains what the option can be used for. The default configuration for roots is ["<rootDir>"] and can be customized to include any number of directories. The rootDir configuration option has always been used mostly as a token for other configuration options and this rename should make configuring Jest clearer.

Revamped documentation​

As you may have already seen, Hector Ramos and Kevin Lacker gave Jest's documentation a fresh new look. We changed the way we organize the website and it now features Docs and API as separate pages:

• Under Docs you can find an introduction to Jest, including Getting Started or Testing Asynchronous Code and handy guides like Snapshot Testing, Testing React Native App, Using with webpack or Migrating to Jest and many more!
• The API section on the other hand lists all available methods exposed by Jest: the expect and jest objects, mock functions, globals, along with configuration options from package.json and from the CLI.

The homepage was completely redesigned to be more descriptive of what Jest is about: “Zero configuration testing platform”. We also made sure it reads better on mobile devices. And for those using RSS – we finally provide a feed for our blog.

Community Updates​

• We really loved this talk: “Introduction to Jest“ by Vas Boroviak.
• Follow @jestjs_ on Twitter.
• The Jest Core team syncs once a week to discuss current and future issues. If you'd like to work on Jest, let us know, submit a few pull requests and join our weekly team meetings.
• The awesome engineers at Artsy wrote about Jest as part of their 2017 frontend stack.
• Stephen Scott wrote a detailed article about testing React components in which he weighs the pros and cons of different approaches.
• Using Jest with vue.js got a lot easier after reading Cristian Carlesso's blog post.
• Michele Bertoli wrote a book about React Design Patterns and Best Practices which features an entire section about Jest.
• Improved --notify command that shows an operating system notification which can now also re-run tests from the notification. This is actually a Jest feature and we are just checking if you are still reading this blog post.
• Jest is now part of react-boilerplate.
• Read about the hidden powers of Jest's matchers.

Finally, we are happy to announce that the ava test runner has adopted parts of the Jest platform and is now shipping with basic snapshot support and is using pretty-format. Consolidating test infrastructure makes it easier to learn how to test applications and enables us to share best practices. We are looking forward to see what we can learn from existing test libraries in the future.

The full changelog can be found on GitHub. Jest 19 was a true JavaScript community effort with 17 people who contributed to this release. We thank each and every one of you for your help to make this project great.

This blog post was written by Rogelio Guzman and Michał Pierzchała.

Improved docs​

One of the changes you'll notice upon visiting our docs is the updated sidebar. The documentation is now divided into three main areas: an introduction to Jest, detailed guides to Jest's features, and a comprehensive API reference.

The Introduction section will guide you from installing Jest and writing your first case, to using Jest's matchers and testing async code. If you're new to Jest or need a quick refresher, these docs should get you up to speed in no time. If you've used Jest before and only need a quick reference on how it's installed, you need to go no further than the Getting Started guide.

Once you feel comfortable using Jest, proceed to the advanced Guides section. The new Snapshot Testing guide covers everything you need to know about creating and maintaining snapshot test cases.

Finally, we've completely overhauled our API reference docs. You can now find detailed information on all of Jest's Globals, matchers, and every flag supported by the jest CLI.

New colors & website​

The colors in the Jest logo and on the website have felt outdated to us for a while. We changed the color scheme we are using for Jest and changed the landing page significantly to be more inviting. We hope you like the new colors and showcase of Jest's strengths.

Who's using Jest?​

We have created a showcase of users to highlight some of the companies that are using Jest. We're thankful to all of these companies for using Jest to test their websites, mobile apps, and APIs. If you're using Jest, check out the guidelines on GitHub and send us a pull request!

Jest in the browser​

As highlighted last month, it is now possible to use Jest directly in the browser using repl.it. If you want to try out Jest before installing it, you can easily do so below or directly from the Jest homepage. Go ahead and give it a try!

Get involved​

This is just the start. Go ahead and take a look at the docs, and don't hesitate to send any feedback our way. If you find a mistake in the docs or you just want to let us know what needs to be documented better, please tweet at us at @jestjs_, open an issue on GitHub, or send us a PR by clicking "Edit on GitHub" at the top of the doc.

We're really excited for the year ahead and can't wait to hear from you!

The newly created react-test-renderer finally enabled testing of react-native components. Through the jest-react-native preset (now merged directly into react-native) Jest now works out of the box for any React project and comes pre-configured in create-react-app and react-native projects. We integrated core pieces of Jest into react-native's packager and the completely new snapshot testing feature has since been used outside of Jest: It was integrated with React Storybook as “storyshots” and is being adopted by other test runners like ava.

The pretty-format project was rewritten with performance in mind to drive Jest's snapshot feature, was recently merged into Jest's monorepo and is also helpful in other test runners. Nowadays Jest is much more about collecting different ideas and solutions to testing than it is about one specific implementation of a test framework.

I'd like to deeply thank all the people that have contributed to Jest this year, both from the open source community and at Facebook: Dmitrii Abramov, Cristian Carlesso, Dan Abramov, Daniel Lo Nigro, Maxim Derbin, Evan Scott, Forbes Lindesay, Keyan Zhang and 60 more people. We'd also like to welcome Michał Pierzchała (@thymikee) as first official external contributor to Jest. He's been doing a great job managing the issues and PRs on the repo. If you'd like to start contributing to Jest, we have a bunch of good first tasks and we are always happy to help on our discord channel.

repl.it with Jest integration​

Amjad Massad built a Jest container so you can now try out Jest directly in the browser. You can use it from now on when creating GitHub issues which should help troubleshoot problems more quickly. Amjad and Haya are building repl.it to democratize programming by building powerful yet simple tools and platforms for educators, learners, and developers. They are also hiring talented engineers!

Community Update​

We feel incredibly humbled that 100+ companies have adopted Jest in the last six months. Companies like Twitter, Pinterest, Paypal, nytimes, IBM (Watson), Spotify, eBay, SoundCloud, Intuit, FormidableLabs, Automattic, Trivago and Microsoft have either fully or partially switched to Jest for their JavaScript testing needs. Thank you very much for giving this project a chance. We would also like to thank everyone who went to conferences and meetups to speak about Jest and to everyone who is writing blog posts about how Jest is or isn't working for them!

Here is what happened in the community in the last two months:

• Jason Bonta and Dmitrii Abramov redefined the “testing pyramid” we were talking a lot about at Facebook.
• jest-codemods now allows you to painlessly migrate from Mocha, Tape and Ava to Jest.
• The React team announced improvements to the react-test-renderer in 15.4.0.
• Orta Therox build an amazing vscode-jest integration and donated the code for editor support to Jest.
• Pavithra Kodmad is documenting Flipkarts adoption of Jest and shares some getting started tips.
• Kent C. Dodds wrote about migrating to Jest at Paypal and Jason Brown wrote about migrating to Jest as well.
• Ben McCormick wrote about saving time with Jest.
• Eric Clemmons wrote about snapshots and storybook integration.
• Edvin Erikson wrote about getting Tap output in Jest.
• jest-html can bring snapshot diffing to your browser.
• There were a few great conversations on hackernews about Jest.
• The community started a great discussion about the future of enzyme.
• Ruben Oostinga wrote about combining chai and Jest matchers.
• Emil Ong wrote about why “TDD'ing your frontend seems pointless”.
• Nate Hunzaker wrote about end-to-end testing with Jest and Nightmare.
• Using Jest with Angular just works according to Matthieu Lux.
• A fantastic conversation about the purpose of snapshot testing is happening right now.
• Dmitrii made a new music video with his metal band.
• lazyspec can help you create smoke tests quickly if you are introducing tests to an existing codebase.
• Patrick Stapfer did a lightning talk about vim and Jest.
• Mark Dalgleish was commenting on the value of snapshot testing.

New features, changes and fixes in Jest 17 & 18​

Jest was initially created more than five years ago and as such an old framework it has accumulated some technical debt. This is why we tend to make breaking changes more often than may seem necessary: We believe it is important to incrementally reduce technical debt to ensure that Jest as a project stays maintainable long-term. We didn't announce Jest 17 in a blog post and if you haven't upgraded to it in the last month you may find the changelog useful.

• Breaking: Removed pit in favor of it or test and mockImpl in favor of jest.fn() or mockImplementation .
• Breaking: Renamed --jsonOutputFile to --outputFile.
• Breaking: Updated testRegex to include test.js and spec.js files.
• Breaking: Replaced scriptPreprocessor with the new transform option.
• Breaking: The testResultsProcessor function is now required to return the modified results.
• Potentially Breaking: Properly resolve snapshotSerializers, setupFiles, transform, testRunner and testResultsProcessor with a resolution algorithm instead of using path.resolve. This mainly means that <rootDir> is no longer needed for these options.
• Added: pretty-format and jest-editor-support were merged into Jest.
• Added: expect.any, expect.anything, expect.objectContaining, expect.arrayContaining, expect.stringMatching.
• Added: --testResultsProcessor is now exposed through the cli.
• Added: Implemented file watching in jest-haste-map.
• Added: Usage of Jest in watch mode can be hidden through JEST_HIDE_USAGE.
• Added: expect.assertions(number) which will ensure that a specified amount of assertions is made in one test.
• Added: .toMatchSnapshot(?string) feature to give snapshots a name.
• Added: toMatchObject, toHaveProperty , toHaveLength matchers.
• Added: expect.extend.
• Added: Added support for custom snapshots serializers.
• Added: Big diffs are now collapsed by default in snapshots and assertions. Added --expand (or -e) to show the full diff.
• Added: jest.resetAllMocks which replaces jest.clearAllMocks.
• Added: --json now includes information about individual tests inside a file.
• Fixed: test.concurrent unhandled promise rejections.
• Fixed: babel-plugin-jest-hoist when using jest.mock with three arguments.
• Fixed: The JSON global in jest-environment-node now comes from the vm context instead of the parent context.
• Fixed: Jest does not print stack traces from babel any longer.
• Fixed: Fake timers are reset when FakeTimers.useTimers() is called.
• Fixed: Regular expressions are properly escaped in snapshots.
• Fixed: Improved pretty printing of large objects.
• Fixed: NaN% Failed in the OS notification when using --notify.
• Fixed: The first test run without cached timings will now use separate processes instead of running in band.
• Fixed: Map/Set comparisons.
• Fixed: test.concurrent now works with --testNamePattern.
• Fixed: Improved .toContain matcher.
• Fixed: Properly resolve modules with platform extensions on react-native.
• Fixed: global built in objects in jest-environment-node now work properly.
• Fixed: Create mock objects in the vm context instead of the parent context.
• Fixed: .babelrc is now part of the transform cache key in babel-jest.
• Fixed: docblock parsing with haste modules.
• Fixed: Exit with the proper code when the coverage threshold is not reached.
• Fixed: Jest now clears the entire scrollback in watch mode.
• Deprecated: jest-react-native was deprecated and now forwards react-native.

Plans for Jest in H1 2017​

Six months ago we shared our plans for Jest and we are happy that we were able to execute well on almost all of them. For the next six months, here is what we are planning:

• Instant feedback: Nuclide integration and an improved and faster watch mode.
• Improved developer experience: new mocking APIs and improved assertions.
• Better performance and memory usage: analyze Jest and be more conscious about efficiency.
• Snapshot Improvements: snapshot approval mode, syntax highlighting and improved react-test-renderer APIs.
• Website: We'll overhaul the website and documentation and add a Jest cheat sheet.

We won't be providing timelines or estimates for these features and we may not actually get to all of these things. If you'd like to help make these things a reality, send us issues and pull requests with your ideas and let's work on improving Jest together in 2017.

Upgraded CLI​

Jest 16 features a new reporter interface that shows running tests as well as a live summary and a progress bar based on the estimated test runtime from previous test runs. We also improved the CLI output to work better with different color schemes. If there were test failures in a previous run, Jest will now always run those tests first to give useful signal to users as quickly as possible.

We also added a lot of new features which you may find useful:

• New CLI flags were added: A --testNamePattern=pattern or -t <pattern> option was added to filter tests from the command line much like it.only or fit does in tests.
• Previously failed tests now always run first.
• jest <pattern> is now case-insensitive to make it easier to filter test files.
• A test run in watch mode can now be interrupted. During a test run, simply press any of the keys used for input during watch mode (a, o, p, q or enter) to abort a test run and start a new one.
• The --bail flag now also works in watch mode. Together with running failed tests first, Jest's watch mode will now feel turbocharged!
• Jest now automatically considers files and tests with the jsx extension.
• Jest warns about duplicate manual mock files and we improved automatically created mocks for ES modules compiled with babel.
• A jest.clearAllMocks function was added to clear all mocks in between tests.
• We improved module resolution when moduleNameMapper is used.
• Finally, a --findRelatedTests <fileA> <fileB> cli option was added to run tests related to the specified files. This is especially helpful as a pre-commit hook if you'd like to run tests only on a specified set of files that have tests associated with them.

This is what Jest looks like when a test run is interrupted in watch mode:

Snapshot Updates​

Jest's snapshot implementation was completely rewritten. The new version of the jest-snapshot package is now structured in a way that allows for easier integration into other test runners and enables more cool integrations like with React Storybook. Jest doesn't mark snapshots as obsolete in a file with skipped or failing tests. We also made a number of changes to the snapshot format:

• Objects and Arrays are now printed with a trailing comma to minimize future changes to snapshots.
• We removed function names from snapshots. They were causing issues with different versions of Node, with code coverage instrumentation and we generally felt like it wasn't useful signal to show to the user that the name of a function has changed.
• Snapshots are now sorted using natural sort order within a file.

When upgrading to Jest 16, the diff might look similar to this one:

Test Library Updates​

We finished the migration of Jasmine assertions to the new Jest matchers. We added three new matchers: toBeInstanceOf, toContainEqual and toThrowErrorMatchingSnapshot . We have more readable failure messages for the spy/mock matchers toHaveBeenLastCalledWith, toHaveBeenCalledWith, lastCalledWith and toBeCalledWith. Now that we have rewritten all assertions and separated them into their own package, we'll be working on making them standalone so they can be integrated into any test framework if you'd like to use them outside of Jest.

We also added a bunch of aliases that were requested by the community. To make Jest focus on a single test you can now use either it.only or test.only or keep using fit; For skipping a test, it.skip or test.skip are now available alongside of xit; finally to define a test as concurrent you can use test.concurrent which is useful in case your test accesses network resources or databases.

Finally, if you'd like to overwrite the expect global with a different assertion library like chai, this can now be done using the setupTestFrameworkScriptFile configuration option.

Community Update​

Over the last month lots of articles were written about Jest's snapshot testing feature, how to migrate to Jest and how to get started writing tests. I also did a few live videos to explain how Jest and snapshot testing works:

• FB Live Video about Snapshot Testing.
• JavaScript & React Testing with Kent C. Dodds.

A number of people wrote articles about snapshot testing. The most opinionated article that resonated with the Jest team was “Testing with Jest Snapshots: First Impressions”. Ben makes three great points in his blog post:

1. Snapshot tests are a complement for conventional tests not a replacement.
2. Snapshot tests are more useful with a healthy code review process.
3. Snapshot tests work well with auto-mocking.

We highly recommend reading the entire blog post. Ben did a fantastic job explaining the reasons why we built snapshot testing. It's important to point out that we didn't introduce snapshot testing to replace all other forms of testing but rather as a way to enable engineers to write tests for code that they otherwise wouldn't write tests for. It works well for things like React components, CLI output, error messages and many others but it doesn't solve all problems. Jest's goal is to provide many different ways to write effective tests without sacrificing performance or the project's maintainability.

Other highlights about snapshot testing:

• A React Native testing series: Part 1: Jest – Snapshot come into play and Part 2: Jest – Redux Snapshots for your Actions and Reducers.
• How we landed on Jest snapshot testing for JavaScript.
• Picture This: Snapshot Testing.
• Snapshot testing with React Storybook.
• Testing React and Redux Applications.
• If you are using the popular enzyme testing utility, there is now a project enzyme-to-json which makes it possible to use Jest's snapshot testing feature together with enzyme.

Redux itself now uses Jest and Max Stoiber wrote a tutorial on how to test code written with redux. There is also a great guide on how to write tests for MobX. If you are using create-react-app, Jest is now included by default. Kent C. Dodds created a ton of videos on egghead.io that will help you get started with Jest.

If you are using other test runners, Kenneth Skovhus built an awesome jest-codemods library that will automate the conversion for you. Codemods are awesome: they'll allow you to quickly evaluate whether Jest will work for you. Give it a try!

The full changelog can be found on GitHub. Jest 16 was a true JavaScript community effort and the project now has more than 220 contributors. We thank each and every one of you for your help to make this project great.

The most important change to talk about is a set of new defaults. If you are an existing Jest user you will very likely need to update your configuration for Jest 15. In most cases it will simplify your setup and Jest will provide useful error messages during the upgrade. All of the new defaults can be disabled to suit your needs, but we still consider the disabled features critical for Jest in certain situations and will continue to use and support them at Facebook long-term. Our API documentation was also completely rewritten to reflect these changes. This pull request for React highlights some of the changes necessary for existing projects.

New CLI error messages and summaries​

As part of our effort to remove Jasmine incrementally within Jest, replacing all Jasmine matchers was almost completed. A lot of time was spent tweaking every error message for every matcher to give the best signal to users when a test is failing – the time when Jest should provide the most value to you. In addition to printing the expected and received values, a diff is printed for the toBe and toEqual matchers to help spot mistakes. More colors were added and relevant files from stack traces are highlighted more prominently.

Here is a comparison of the before and after on a light terminal: It also works well with darker colors:

New watch command​

We completely rewrote jest --watch to be more interactive. It can now switch between running all tests or only test files related to changed files by pressing a or o. By pressing p a prompt appears that allows to specify a test pattern to focus on a specific set of files. Snapshot tests can be updated by pressing u.

jest-react-native improvements​

Mocks for ListView, TextInput, ActivityIndicator, ScrollView and more were added. The existing mocks were updated to use the real implementations and existing snapshots likely have to be updated when upgrading to Jest 15. A mockComponent function was added to jest-react-native that can be used to mock native components:

jest.mock('MyNativeComponent', () => {
  const jestReactNative = require('jest-react-native');
  return jestReactNative.mockComponent('MyNativeComponent');
});

There have also been a number of improvements around mocking images, the fetch module and other native APIs.

Buffered Console Messages​

Jest parallelizes test runs across workers to maximize performance. Previously Jest used to forward console messages from workers to the parent and printed them immediately. When running multiple tests in parallel, it was often hard to find out which test and which module was calling a log function. In Jest 15, all console messages are buffered and printed together with individual test results. In addition the file and line number of the log call is printed so the code can easily be inspected.

Compare the output of the previous version of Jest and Jest 15:

Disabled Automocking​

Automocking is now disabled by default in Jest. This is by far the most confusing feature for new users and in many ways it doesn't make sense for small projects. We introduced automocking at Facebook and it worked great for us when unit testing was adopted in a large existing code base with few existing tests, but over time it felt like people spent more time fighting with mocked/unmocked modules than it would have taken them to write a test normally. We also noticed that library authors often require a huge number of basic modules that always have to be manually unmocked. Even for Jest itself we realized that the majority of tests had automocking disabled manually. We still believe that explicit automocking can be incredibly valuable. This change simply trades implicit mocks for explicit mocks via calls to jest.mock(moduleName).

If you would still like to use automocking by default, enable the automock setting in your configuration or manually call jest.enableAutomock() in your test or setup file.

Test File Patterns​

Not everyone uses the same convention of using a __tests__ folder to store tests. Jest 15 also looks for files ending in .spec.js or .test.js, two popular community standards. Jest 15 also removes the testDirectoryName and testFileExtensions configuration options and asks users to switch to the testRegex option when the old configuration options are used.

Module Registry Persistence​

Jest used to implicitly reset all modules before each test and we recommended requiring modules in beforeEach or inside of tests. This is useful when modules have local state that shouldn't be shared between tests. However, two big shifts happened: ES modules with the top-level import syntax and a renewed interest in writing stateless functional modules.

This has lead to numerous incompatibilities. We also noticed that at Facebook we weren't even using this implicit reset. Instead we relied on explicit calls to jest.resetModules() which puts engineers in control on when to wipe away all state.

Here is an example:

const React1 = require('react');
jest.resetModules();
const React2 = require('react');

React1 !== React2; // These two are separate copies of React.

The call to resetModules wipes away the require cache. A second call to require the same module will result in a new instantiation of the same module and all of its dependencies. This feature is especially useful when dealing with modules that have side effects, like jest-haste-map.

We believe it is better to put users in control so we disabled the implicit reset. Modules can be reset using jest.resetModules() in code and the resetModules option can be enabled in the configuration to bring back the previous behavior.

Real vs Fake Timers​

By default Jest used to mock all timer functions like setTimeout or process.nextTick and provided an API jest.runAllTimers() to advance timers programmatically. This is useful when a piece of code sets a long timeout that we don't want to wait for in a test.

However we found that most of the time the use cases are quite isolated. Async programming has also become much simpler in our test runner. Jest now uses the real timers by default.

You can still override this by specifying "timers": "fake" in the configuration or by calling jest.useRealTimers() and jest.useFakeTimers() global switches.

setupEnvScriptFile vs setupFiles​

The setupEnvScriptFile configuration option has been deprecated for a while. Jest 15 removes it completely and replaces it with setupFiles. This option expects an array of file paths that are loaded in order before a test file is executed.

Rewritten Code Coverage Support​

Code coverage in Jest can be used through jest --coverage and requires no additional packages or configuration. Code coverage support was completely rewritten and a new collectCoverageFrom option was added to collect code coverage information from entire projects, including untested files. Note that this option uses globs as we are hoping to further simplify configuration options in the future and provide a simpler alternative to regular expressions. See Jest's package.json for an example.

Other Improvements​

A huge number of other improvements were also made:

• Improved performance of small test runs.
• Jest now uses verbose mode when only a single test file is executed.
• Added an --env option to override the configured test environment.
• moduleNameMapper now uses a resolution algorithm.
• Jest now works with paths that have special characters in them, like parenthesis.
• Added global.global to the node environment.
• Fixed babel-plugin-jest-hoist's invalid error when a random user function was called mock.
• Fix testEnvironment resolution to prefer jest-environment-{name} instead of {name} only. This prevents a module collision when using jsdom as test environment.
• Improvements to Jest's own test infra by merging integration and unit tests. Code coverage is now collected for Jest.

We are happy when looking back at all the changes we have made together with the help from the community and couldn't be more excited to make Jest even better over the course of the next few months. Please file an issue if something isn't working as expected and send us pull requests.

Next up: Concurrent Reporter.

One of the big open questions was how to write React tests efficiently. There are plenty of tools such as ReactTestUtils and enzyme. Both of these tools are great and are actively being used. However engineers frequently told us that they spend more time writing a test than the component itself. As a result many people stopped writing tests altogether which eventually led to instabilities. Engineers told us all they wanted was to make sure their components don't change unexpectedly.

Together with the React team we created a new test renderer for React and added snapshot testing to Jest. Consider this example test for a simple Link component:

import renderer from 'react-test-renderer';
test('Link renders correctly', () => {
  const tree = renderer
    .create(<Link page="http://www.facebook.com">Facebook</Link>)
    .toJSON();
  expect(tree).toMatchSnapshot();
});

The first time this test is run, Jest creates a snapshot file that looks like this:

exports[`Link renders correctly 1`] = `
<a
  className="normal"
  href="http://www.facebook.com"
  onMouseEnter={[Function bound _onMouseEnter]}
  onMouseLeave={[Function bound _onMouseLeave]}>
  Facebook
</a>
`;

The snapshot artifact should be committed alongside code changes. We use pretty-format to make snapshots human-readable during code review. On subsequent test runs Jest will simply compare the rendered output with the previous snapshot. If they match, the test will pass. If they don't match, either the implementation has changed and the snapshot needs to be updated with jest -u, or the test runner found a bug in your code that should be fixed.

If we change the address the Link component in our example is pointing to, Jest will print this output:

Now you know that you either need to accept the changes with jest -u, or fix the component if the changes were unintentional. To try out this functionality, please clone the snapshot example, modify the Link component and run Jest. We updated the React Tutorial with a new guide for snapshot testing.

This feature was built by Ben Alpert and Cristian Carlesso.

Experimental React Native support​

By building a test renderer that targets no specific platform we are finally able to support a full, unmocked version of React Native. We are excited to launch experimental React Native support for Jest through the jest-react-native package.

You can start using Jest with react-native by running yarn add --dev jest-react-native and by adding the preset to your Jest configuration:

"jest": {
  "preset": "jest-react-native"
}

• Tutorial and setup guide
• Example project
• Example pull request for snowflake, a popular react-native open source library.

Why snapshot testing?​

For Facebook's native apps we use a system called “snapshot testing”: a snapshot test system that renders UI components, takes a screenshot and subsequently compares a recorded screenshot with changes made by an engineer. If the screenshots don't match, there are two possibilities: either the change is unexpected or the screenshot can be updated to the new version of the UI component.

While this was the solution we wanted for the web, we also found many problems with such end-to-end tests that snapshot integration tests solve:

• No flakiness: Because tests are run in a command line runner instead of a real browser or on a real phone, the test runner doesn't have to wait for builds, spawn browsers, load a page and drive the UI to get a component into the expected state which tends to be flaky and the test results become noisy.
• Fast iteration speed: Engineers want to get results in less than a second rather than waiting for minutes or even hours. If tests don't run quickly like in most end-to-end frameworks, engineers don't run them at all or don't bother writing them in the first place.
• Debugging: It's easy to step into the code of an integration test in JS instead of trying to recreate the screenshot test scenario and debugging what happened in the visual diff.

Because we believe snapshot testing can be useful beyond Jest we split the feature into a jest-snapshot package. We are happy to work with the community to make it more generic so it can be integrated with other test runners and share concepts and infrastructure with each other.

Finally, here is a quote of a Facebook engineer describing how snapshot testing changed his unit testing experience:

“One of the most challenging aspects of my project was keeping the input and output files for each test case in sync. Each little change in functionality could cause all the output files to change. With snapshot testing I do not need the output files, the snapshots are generated for free by Jest! I can simply inspect how Jest updates the snapshots rather than making the changes manually.” – Kyle Davis working on fjs.

What's next for Jest​

Recently Aaron Abramov has joined the Jest team full time to improve our unit and integration test infrastructure for Facebook's ads products. For the next few months the Jest team is planning major improvements in these areas:

• Replace Jasmine: Jasmine is slowing us down and is not being very actively developed. We started replacing all the Jasmine matchers and are excited to add new features and drop this dependency.
• Code Coverage: When Jest was originally created, tools such as babel didn't exist. Our code coverage support has a bunch of edge cases and isn't always working properly. We are rewriting it to address all the current problems with coverage.
• Developer Experience: This ranges from improving the setup process, the debugging experience to CLI improvements and more documentation.
• Mocking: The mocking system, especially around manual mocks, is not working well and is confusing. We hope to make it more strict and easier to understand.
• Performance: Further performance improvements especially for really large codebases are being worked on.

As always, if you have questions or if you are excited to help out, please reach out to us!

The Flow project has evolved a lot within Facebook and has been successfully adopted across many of our frameworks and almost all of our product code. Adoption can be parallelized incredibly well – it can be done file-by-file until enough of the codebase is well-typed. Then, Flow provides real value and helps guide through large changes. Through this, many small edge cases and bugs were found.

With the help of lerna, we continued to modularize the Jest project. With just a small update to the configuration, Flow and lerna now get along well with each other. Splitting up Jest into packages helped us rethink module boundaries and enabled us to ship useful packages standalone: The jest-runtime and jest-repl cli tools now allow you to run scripts in a sandboxed Jest environment, enabling you to run and debug your app from the command line. This is especially helpful for projects that use Facebook's @providesModule module convention. To get started, just install jest-repl and run it in the same folder you normally run your tests in! We also published a jest-changed-files package that finds changed files in version control for either git or hg, a common thing in developer tools.

New and improved features​

• Added a notification plugin that shows a test run notification when using --notify.
• Added a browser config option to properly resolve npm packages with a browser field in package.json if you are writing tests for client side apps.
• Improved “no tests found message” which will now report which tests were found and how they were filtered.
• Added jest.isMockFunction(jest.fn()) to test for mock functions.
• Improved test reporter printing and added a test failure summary when running many tests.
• Added support for mocking virtual modules through jest.mock('Module', implementation, {virtual: true}).
• Removed the .haste_cache folder. Jest now uses the operating system's preferred temporary file location.
• Added the duration of individual tests in verbose mode.
• Added the ability to record snapshots in Jest. We'll be publishing a separate blog post about this feature soon.

Finally, we have received a complete website redesign done by Matthew Johnston and added documentation for using Jest with webpack. Happy Jesting!