Stencil: Jest 27 Upgrade Instructions
Stencil v2.13.0 includes support for Jest v27, but does not require any project to upgrade their version of Jest at this time. You can upgrade Stencil and continue to use any previous version of Jest that you currently have in your workflow with no breaking changes.
For folks who wish to upgrade to both Stencil v2.13.0 and Jest v27, we suggest performing the upgrade as two steps: one where Stencil is upgraded and tested, and another where Jest is upgraded and tested using Stencil v2.13.0. This should help with the debugging process should the upgrade be anything less than perfect.
Step 1 – Upgrade Stencil
First, let’s upgrade Stencil. Open a terminal window in your project’s root directory, and update Stencil to v2.13.0:
npm install @email@example.com
yarn add @firstname.lastname@example.org
Run your project’s build process, all tests, and anything else that will help verify your project works. If it does, we recommend you commit your changes using your version control system before moving on to the next step.
If something’s not working as expected at this point, please open an issue in the Stencil GitHub tracker. Please be sure to include:
– a minimal reproduction repo (if possible)
– the command used to upgrade Stencil
– the version of Stencil you’re upgrading from
– any additional info you feel might help the team diagnose the issue
Step 2 – Upgrade Jest
Next, upgrade Jest. The command below assumes your project uses Jest v26. If you’re using an older version of Jest, it’s recommended that you run this step for every major version of Jest between your current version and v27.
npm install --save-dev jest@27 jest-cli@27 @types/jest@27
yarn add --save-dev jest@27 jest-cli@27 @types/jest@27
Run the build process, all tests, and anything else that will help verify your project works. If it does, congratulations! Commit your changes, you’ve successfully upgraded Stencil and Jest!
Debugging the Jest Upgrade
If something’s not working as you’d expect, it is possible that the issue is not necessarily with Stencil and Jest, but a breaking change that was introduced in Jest v27. Please take a look at the blog post from the Jest team announcing Jest v27. It includes a list of all breaking changes that were made between v26 and v27 and may help narrow down the issue.
In addition to the Jest v27 blog post, please note the Stencil team performed a few additional changes to ensure backwards compatibility between older versions of Jest and Stencil:
- At this time,
jest-jasmine2is the only supported test runner. No additional configuration should be required on your end. Please see this ADR in the Stencil repository for our reasoning.
- The first run of your tests may be slower than you expect. This is because Jest’s test caching mechanism changed slightly from v26 to v27. Stencil accommodates for this; however, your first run may be slow while the cache repopulates. For additional information, please see this section of ADR-0015 in the Stencil repository.
If debugging remains unsuccessful, please open an issue in the Stencil GitHub tracker. Please be sure to include:
- a minimal reproduction repo (if possible)
- the command used to upgrade Jest
- the version of Jest you’re upgrading from
- any additional info you feel might help the team diagnose the issue
We hope you’re all excited about this update as we are! Until next time, happy coding (and happy testing)!