feat!: local types, supporting jest, @jest/globals, vitest

[jgoz]

What:

Moves matcher types back into this package and adds support for @jest/globals and vitest, both in terms of automatically extending expect and augmenting the appropriate TypeScript interfaces.

There are three breaking changes here:

1. Drop support for node < 14
2. Removes the extend-expect script. Users should use the default import path or one of the new test platform-specific paths to automatically extend the appropriate "expect" instance. extend-expect was not documented in the Readme, so this change should have minimal impact.
3. Remove the @types/ dependency. This might affect JavaScript users who were relying on the automatic inclusion of the @types/ package to get auto-complete in their editor for jest-dom assertions.

But in my local testing with the changes in this PR, following the Readme was sufficient to get full auto-complete support even for JS-only users. As long as they have a jest-setup file that imports the bare export and add a dependency on @types/jest, recent versions of VS Code will figure it out.

In addition to the above changes, @jest/globals and vitest users can now use jest-dom without caveats. Users can now use the following import paths to automatically extend "expect" for their chosen test platform:

• @testing-library/jest-dom — jest+@types/jest
• @testing-library/jest-dom/jest-globals — @jest/globals
• @testing-library/jest-dom/vitest — vitest

For example:

import '@testing-library/jest-dom/jest-globals'

Importing from one of the above paths will augment the appropriate matcher interface for the given test platform, assuming the import is done in a .ts file that is included in the user's tsconfig.json.

It's also (still) possible to import the matchers directly without side effects:

import * as matchers from '@testing-library/jest-dom/matchers'

Why:

There have been numerous issues filed over the last couple years as the JS testing ecosystem has evolved and users wanted to use this library in more environments. It was usually possible, thanks to broad compatibility efforts in the ecosystem at large, but using jest-dom outside of Jest was not always straightforward.

Originally, moving the types to DT was in service of a noble "it should just work" goal, but in practice, it traded convenience in simple cases for confusion in more complex cases. It also broke with convention around DT packages — why does the actual package have a dependency on its own types? Why not simply move the types into the package? Those were valid questions that had legitimate answers, but they grew stale with time.

Fixes #314
Fixes #427
Closes #472
Fixes #506
Fixes #476
Closes #484
Closes #496
Closes #483
Closes #460

How:

• Move latest typings from @types/testing-library__jest-dom into this repo
• Add jest.d.ts for extending global interfaces when using @types/jest
• Add jest-globals.d.ts for extending interfaces when using @jest/config
• Add vitest.d.ts for extending interfaces when using vitest
• Add optional peer dependencies on jest, @types/jest, @jest/globals, and vitest
• Add /jest-globals and /vitest exports for automatically extending @jest/globals and vitest, respectively

Checklist:

• Documentation
• Tests
• Updated Type Definitions
• Ready to be merged
  

[jgoz]

In my testing, @jest/globals had to use CommonJS

[jgoz]

And Vitest only supports ESM 🤷

[kentcdodds]

In that case, should this file extension be .mjs?

Have you test this setup in a vitest project? If not, could you verify this will work as expected?

[jgoz]

Great question. Using .mjs would be technically correct, but then all imported files would need to be ESM, which is not the case for matchers.js. Basically, vitest fails with "Error: Cannot find module".

I think we could change the extension after dual-publishing ES (#437?), but for now this works in vitest.

Have you test this setup in a vitest project?

Yeah, I've got 4 test projects that I tested this PR against: Jest+JS, Jest+TS, @jest/globals+TS, vitest+TS. I'll publish them soon.

[jgoz]

A combination of <reference> and export {} in the referenced definitions seemed to be required to get TypeScript to augment the appropriate interfaces when this file was imported from node_modules.

[codecov]

Codecov Report

Merging #511 (85dbd5b) into main (d717c66) will not change coverage.
The diff coverage is 100.00%.

@@            Coverage Diff            @@
##              main      #511   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           27        27           
  Lines          664       664           
  Branches       251       251           
=========================================
  Hits           664       664           

Files Changed	Coverage Δ
src/to-be-in-the-document.js	100.00% <ø> (ø)
src/to-contain-element.js	100.00% <ø> (ø)
src/to-contain-html.js	100.00% <ø> (ø)
src/utils.js	100.00% <ø> (ø)
src/index.js	100.00% <100.00%> (ø)

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[kentcdodds]

Thank you so much for doing this work! I think it's going to be a very positive thing. I just have a couple questions.

[kentcdodds]

Would this be the approach if you're not using vitest's globals.

[jgoz]

I'm not 100% sure what you mean by vitest's globals. Vitest's default mode is globals: false, which requires explicit imports of describe, expect, etc., and the new vitest entrypoint is designed to work with that. I didn't actually think to test with globals: true and importing the vitest/globals types — I'll do that tomorrow.

This section was intended as a hedge against future testing libraries that might emerge that retain some level of compatibility with Jest. But if you think it might be more confusing than helpful, I'm happy to remove it.

[jgoz]

I didn't actually think to test with globals: true and importing the vitest/globals types — I'll do that tomorrow.

Tested this and it works.

[kentcdodds]

In that case, should this file extension be .mjs?

Have you test this setup in a vitest project? If not, could you verify this will work as expected?

[kentcdodds]

Thank you so much for helping with this!

[github-actions]

🎉 This PR is included in version 6.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[MattyBalaam]

Very happy to see this 😊

[TrevorBurnham]

Really excited to see this! FYI when I first plugged in this change (upgrading @testing-library/jest-dom from 5.16.5 to 6.0.0, upgrading vitest from 0.30.1 to 0.34.1 to fix a compatibility issue, then dropping @types/testing-library__jest-dom and adding import "@testing-library/jest-dom/vitest" to my test setup file), I got this error when running my tests:

Error: @vitejs/plugin-react can't detect preamble. Something is wrong. See https://github.com/vitejs/vite-plugin-react/pull/11#discussion_r430879201

No idea why that happened, but the error went away when I upgraded @vitejs/plugin-react from 3.1.0 to 4.0.4. Sharing this in hopes that it saves other devs some headaches. 🙏🏻