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

jgoz · 2023-08-12T18:41:54Z

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:

Drop support for node < 14
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.
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

Moves matcher types back into this package and adds support for @jest/globals and vitest. BREAKING CHANGE: 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. 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'

jgoz · 2023-08-12T18:43:27Z

jest-globals.js

@@ -0,0 +1,4 @@
+const globals = require('@jest/globals')


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

jgoz · 2023-08-12T18:44:06Z

vitest.js

@@ -0,0 +1,4 @@
+import {expect} from 'vitest'


And Vitest only supports ESM 🤷

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?

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 · 2023-08-12T18:45:42Z

vitest.d.ts

@@ -0,0 +1 @@
+/// <reference path="types/vitest.d.ts" />


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 · 2023-08-12T20:44:26Z

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 · 2023-08-13T03:07:47Z

README.md

@@ -144,6 +180,18 @@ haven't already:
  ],
 ```

+### With another Jest-compatible `expect`


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

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.

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 · 2023-08-13T03:10:30Z

vitest.js

@@ -0,0 +1,4 @@
+import {expect} from 'vitest'


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 · 2023-08-13T16:28:51Z

Thank you so much for helping with this!

github-actions · 2023-08-13T16:32:17Z

🎉 This PR is included in version 6.0.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

MattyBalaam · 2023-08-13T19:05:18Z

Very happy to see this 😊

TrevorBurnham · 2023-08-13T20:22:07Z

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. 🙏🏻

@Tobbe

This reverts #9673 and #9711. With v6 of `@testing-library/jest-dom`, `yarn rw type-check` fails in Redwood projects because it can't locate the types for `@testing-libary/jest-dom`. They absorbed the definitely types package (`@types/testing-library__jest-dom`) in this PR: testing-library/jest-dom#511. Here's an example of a failing run: https://github.com/redwoodjs/redwood/actions/runs/7213177056/job/19668365614?pr=9708. The logical thing to do is remove `@testing-libary/jest-dom` from the `types` array in `web/tsconfig.json`, but when we do that we get a different failure from TS saying that it doesn't understand the extended matchers provided by `testing-library/jest-dom` like `toBeInTheDocument`. @Tobbe filed an issue in their repo here testing-library/jest-dom#559. In the PR I linked to, the maintainer notes that... > 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. Users don't have jest setup files in their project (we just point to a jest preset) or `@types/jest` as an explicit dev dependency. I took a look at it but couldn't crack it today. Instead of holding up other PRs in CI, better to revert it for now and come back to later when we have more leads.

jgoz requested review from gnapse, nickmccurdy and kentcdodds August 12, 2023 18:42

jgoz commented Aug 12, 2023

View reviewed changes

jgoz added 2 commits August 12, 2023 12:56

Update kcd-scripts

478a796

Drop node < 14

85dbd5b

jgoz mentioned this pull request Aug 12, 2023

chore: remove @types from dependencies #472

Closed

4 tasks

kentcdodds reviewed Aug 13, 2023

View reviewed changes

kentcdodds merged commit 4b764b9 into testing-library:main Aug 13, 2023
7 checks passed

github-actions bot added the released label Aug 13, 2023

This was referenced Aug 15, 2023

[@testing-library/jest-dom] Fix matchers type making the global expect unsafe DefinitelyTyped/DefinitelyTyped#66247

Closed

[@testing-library/jest-dom] not needed as of v6 DefinitelyTyped/DefinitelyTyped#66389

Merged

kryops mentioned this pull request Aug 16, 2023

fix: matchers type is making the global expect unsafe #513

Merged

4 tasks

This was referenced Aug 22, 2023

feat: Drop support for Node 12 #379

Closed

Drop Node 12 support #366

Closed

Use .mjs extension for esm files #453

Closed

jtoar mentioned this pull request Dec 15, 2023

Revert @testing-library/jest-dom v6 upgrade redwoodjs/redwood#9713

Merged

sheremet-va mentioned this pull request Jan 19, 2024

TS error when using vitest globals and @testing-library/jest-dom vitest-dev/vitest#517

Closed

6 tasks

sungik-choi mentioned this pull request Feb 16, 2024

Upgrade dependencies channel-io/bezier-react#1997

Open

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

jgoz commented Aug 12, 2023 •

edited

jgoz Aug 12, 2023

jgoz Aug 12, 2023

kentcdodds Aug 13, 2023

jgoz Aug 13, 2023

jgoz Aug 12, 2023

codecov bot commented Aug 12, 2023 •

edited

kentcdodds left a comment

kentcdodds Aug 13, 2023

jgoz Aug 13, 2023

jgoz Aug 13, 2023

kentcdodds Aug 13, 2023

kentcdodds commented Aug 13, 2023

github-actions bot commented Aug 13, 2023

MattyBalaam commented Aug 13, 2023

TrevorBurnham commented Aug 13, 2023

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

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

Conversation

jgoz commented Aug 12, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Aug 12, 2023 • edited

Codecov Report

kentcdodds left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kentcdodds commented Aug 13, 2023

github-actions bot commented Aug 13, 2023

MattyBalaam commented Aug 13, 2023

TrevorBurnham commented Aug 13, 2023

jgoz commented Aug 12, 2023 •

edited

codecov bot commented Aug 12, 2023 •

edited