blimmer / jest-circleci-orb Goto Github PK

This orb makes it easier to run jest tests in your CircleCI environment. A primary benefit is automatically restoring the jest cache for faster subsequent test runs.

Home Page: https://circleci.com/developer/orbs/orb/blimmer/jest

JavaScript 13.22% Dockerfile 10.33% TypeScript 76.45%

jest circleci circleci-orbs circleci-orb

jest-circleci-orb's Introduction

jest-circleci-orb

This orb makes running jest tests fast and easy. The primary functionality this orb provides is saving / restoring the jest cache, which makes subsequent test runs faster.

Benefits of Storing the Jest Cache

Jest stores useful information in the cache, which improves the performance of your test suite.

Reduced startup time Jest stores information about the file structure and mocks you create in your tests. By restoring the previous jest-haste-map data, it reduces the amount of work jest has to do at startup.
Even distribution of test suites across workers If you're running your test suites in parallel (enabled by default), jest will cache information about how long each of your test suites takes to run. It then uses this information to evenly distribute your test suites across the jest workers, so they all complete their work around the same time. This prevents one slow test suite from holding up the entire jest run.
Fast fail with bail config. Jest also stores whether each individual test succeeded or failed on the previous run, and runs failed tests as soon as possible on the next run. This is very handy when used in conjunction with the bail configuration, so you get super-fast feedback on previously failed tests.
Faster Typescript transpiling. If you're using TypeScript with jest, your files are likely transpiled to Javascript before each run. By restoring the cache, jest will only transpile changed files.

If you want to learn more about the jest cache, check out Jest Architecture video on YouTube.

Usage

See the orb registry listing for usage details.

Configuration

To save / restore the jest cache between runs, you must set jest's cacheDirectory configuration property to a predictable location.

In your jest configuration file (e.g. jest.config.js, jest.config.ts or in your package.json), set cacheDirectory to .jest-cache. For example,

// jest.config.js
module.exports = {
  // other configuration properties
  cacheDirectory: '.jest-cache'
}

You should also gitignore this directory. Add .jest-cache to your .gitignore file.

If you don't have a jest configuration file, refer to the documentation to learn how to create one.

Examples

version: 2.1

orbs:
  # Replace x.y.z. with a real version number. All versions are listed here:
  # https://circleci.com/developer/orbs/orb/blimmer/jest
  jest: blimmer/[email protected]

  workflows:
    test:
      jobs:
        - jest/test

Refer to the orb registry listing for more examples.

Breaking Changes

Breaking changes, such as those between 0.x and 1.x, are described in CHANGELOG.md.

Contributing

I welcome issues and pull requests against this repository!

About the Author

You can learn more about the author here.

jest-circleci-orb's People

Contributors

Stargazers

Watchers

jest-circleci-orb's Issues

Restore jest cache for remote docker runs

Support using yarn as the package manager

Currently, we're only allowing NPM - we should also allow yarn

Restore jest cache for direct runs

On machine and docker instances

Use circleci node package to cache dependencies

https://github.com/CircleCI-Public/node-orb/blob/master/src/commands/install-packages.yml caches dependencies for speedier installs

Cache Fallback Improvements

If the previous commit doesn't have a cache, it should:

fall back to the most recent cache from the current branch
then, fall back to the most recent cache from the default branch (e.g. main or master)

Try to automatically set maxWorkers correctly

Background

Jest uses os.availableParallelism() and os.cpus().length to figure out how many Jest workers to spawn. However, on CircleCI Docker executors, these function calls return invalid results.

For example, on my medium+ executor with 3 vCPU cores:

circleci@00740471180a:~$ node
Welcome to Node.js v18.16.0.
Type ".help" for more information.
> const os = require('os')
undefined
> os.availableParallelism()
36
> os.cpus().length
36

This causes frequent OOM errors and crashes, which are hard for the average user to debug. There are several feature requests to CircleCI to make this better:

However, I'm not holding my breath on them fixing this on their end.

Possible Solution

It looks like using this snippet reports the correct number of vCPUs available:

circleci@2866814cd4c3:/tmp$ echo $(($(cat /sys/fs/cgroup/cpu/cpu.shares) / 1024))
3

So, it would be great to automatically set maxWorkers via this, instead of the inaccurate defaults used by jest.

Notes

This would only be necessary on the docker executor, as the machine executor will correctly report CPUs: https://support.circleci.com/hc/en-us/articles/10653544013467-Docker-Executor-returning-Total-Host-CPU-Cores

Configuarbility and Documentation

For documentation:

Note that you must customize jest.config.js to specify a cacheDirectory
docker-compose mount through cacheDirectory

Create integration test suite

Test project should support:

Running jest directly on a machine runner
Running jets directly in a docker runner
Running jest in a remote docker instance
The test suite should validate that the cache is present