docs: advise users to install typescript types

[waynevanson]

What:

Information on installing typescript types from @types/jest-dom__types

Why:

These instructions are critical for using Typescript, yet I haven't seen any instructions.

How:

In readme.md.

<!-- How were these changes implemented? -->

I'm not sure what this question means, am I missing something?

Checklist:

• [x] Documentation
• [ ] Tests
• [ ] Updated Type Definitions
• [ ] Ready to be merged

[tpict]

Thanks for this. Somehow my project had inherited type declarations for the matchers from somewhere, but they conflicted with the most recently published version. Installing the latest @types/testing-library__jest-dom fixed it :+1:

[lookfirst]

If you're using vite, this is a godsend and the magic sauce to make

expect(await screen.findByText(/count is: 1/i)).toBeInTheDocument();

work in IDEA Intellij

[nickserv]

This shouldn't be necessary unless you're using a tool with strict dependency requirements like Yarn modern

[waynevanson]

This shouldn't be necessary unless you're using a tool with strict dependency requirements like Yarn modern

I use pnpm for most things, sounds about right.

Why would strictness be a problem for supplying types?

[lookfirst]

I'm using pnpm.

[nickserv]

Some package managers (including Yarn modern) only allow packages to import/require a dependency if it's declared as a dependency in its package.json.

[tpict]

I think the crux of the issue is that @types/jest-dom__types is specified as a dependency for @testing-library/jest-dom in package.json. I've never seen another package do that before. I was mistakenly under the impression that @testing-library/jest-dom shipped with typedefs because of that.

The dependency on@types/jest-dom__types should either

• be removed, so it's obvious to users that they need to make it a dependency of their own project and keep it up-to-date
• be kept in sync with the most recently published version. The current constraint in package.json allows package managers to resolve a version that's two years old!

[jgoz]

I've never seen another package do that before.

See #123 for historical context.

TL;DR: The testing library packages all used to do this until they started shipping their own types. But since jest-dom's types augment Jest's types, which are available in an ambient context, it wasn't straightforward to ship types as part of this package. At least, not if the goal was "the types should just be available without users having to do anything". This is because TypeScript will automatically load global types if and only if they exist in an @types/ dependency.

It's hard to know whether this approach was overall more or less confusing for users since we only hear about the cases where it's causing friction.

[tpict]

Thanks for the context! I’m not sure I completely understand the situation, but publishing a new version of jest-dom with the types version constraint updated would probably be a quick win?

[jgoz]

publishing a new version of jest-dom with the types version constraint updated would probably be a quick win?

Yeah, I suppose the @types package version should be more or less kept in sync with the package version, but this won't fully prevent people from installing multiple versions of the types dependency, nor will it help people who are using strict package managers like pnpm or yarn modern.

For those cases, the types package should probably be a peer dependency, but then we lose the "just works" use case for people using npm without strict-peer-deps. Though maybe that isn't as relevant anymore as it was a few years ago.

[tpict]

nor will it help people who are using strict package managers like pnpm or yarn modern

would you mind elaborating? I use Yarn 3 and I would expect it to resolve the issue for me when I next upgrade jest-dom

[jgoz]

would you mind elaborating? I use Yarn 3 and I would expect it to resolve the issue for me when I next upgrade jest-dom

I guess it depends on how you have configured Yarn. From what I understand, PnP mode doesn't hoist dependencies to the root by default. So if @testing-library/jest-dom depends on @types/testing-library__jest-dom, it will be installed with this (virtual) folder structure:

- node_modules
 | - @testing-library
   |- jest-dom
     |- node_modules
       |- @types
         |- testing-library__jest-dom

This is also how pnpm would install it. But TypeScript will only scan the top-level node_modules/@types folder for ambient types, so for either one of those package managers, you would need to add the @types/ package as a dependency of your project.

But maybe Yarn 3 with the node-modules plugin does hoist packages to the root like npm, in which case it wouldn't be an issue. I don't know enough about Yarn to say for sure.

[tpict]

With nodeLinker: node-modules and no explicit dependency on @types/testing-library__jest-dom, the version specified by @testing-library/jest-dom is present on my end at node_modules/@types/testing-library__jest-dom/. Then if I add it as a dependency to my package.json, the version number jumps to latest.

[waynevanson]

This is all very good information, thank you for sharing.

Maybe I can expand the addition to the docs to include when doing this will be necessary?

[seivan]

This is also how pnpm would install it. But TypeScript will only scan the top-level node_modules/@types folder for ambient types, so for either one of those package managers, you would need to add the @types/ package as a dependency of your project.

But maybe Yarn 3 with the node-modules plugin does hoist packages to the root like npm, in which case it wouldn't be an issue. I don't know enough about Yarn to say for sure.

Just want to point out, you can opt out via dependency requirements with Yarn 3 using "dependenciesMeta"

    "core-js": {
      "built": false
    },
    "source-map-resolve": {
      "optional": true
    }
  },

[codecov[bot]]

Codecov Report

Merging #460 (bb669e6) into main (948d90f) will not change coverage. The diff coverage is n/a.

@@            Coverage Diff            @@
##              main      #460   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           26        26           
  Lines          630       630           
  Branches       236       236           
=========================================
  Hits           630       630           

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

[nickserv]

@waynevanson leaving this open for now in case you want to add anything.

[waynevanson]

@waynevanson leaving this open for now in case you want to add anything.

@nickmccurdy done.

[SalahAdDin]

would you mind elaborating? I use Yarn 3 and I would expect it to resolve the issue for me when I next upgrade jest-dom

I guess it depends on how you have configured Yarn. From what I understand, PnP mode doesn't hoist dependencies to the root by default. So if @testing-library/jest-dom depends on @types/testing-library__jest-dom, it will be installed with this (virtual) folder structure:

- node_modules
 | - @testing-library
   |- jest-dom
     |- node_modules
       |- @types
         |- testing-library__jest-dom

This is also how pnpm would install it. But TypeScript will only scan the top-level node_modules/@types folder for ambient types, so for either one of those package managers, you would need to add the @types/ package as a dependency of your project.

But maybe Yarn 3 with the node-modules plugin does hoist packages to the root like npm, in which case it wouldn't be an issue. I don't know enough about Yarn to say for sure.

I am not using Yarn 3, with the default one it works almost fine. I tested a lot with pnpm, but it didn't work.

The solution was installing the types package as this documentation proposes.

[waynevanson]

@nickmccurdy Do we need anything else to get this one in?

[x6ax6b]

I read the docs and installed it, but it didn't autocomplete types like toBeInTheDocument, so I wasted time. I am using pnpm, installed the @types/testing-library__jest-dom package and solved it. The documents should be improved with this request pull.

[github-actions[bot]]

:tada: This issue has been resolved in version 6.0.0 :tada:

The release is available on:

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

Your semantic-release bot :package::rocket: