Cannot use `@​testing-library/jest-dom` directly in `setupFilesAfterEnv`

[Hugo Jobling]

• @testing-library/jest-dom version: 6.0.1
• node version: 18.13.0
• npm (or yarn) version: 9.8.1

Relevant code or config:

{
  setupFilesAfterEnv: ['@testing-library/jest-dom'],
}

What you did:

Upgrade from 5.17.0 to 6.0.1.
Ran jest

What happened:

An error was reported:

Property 'toBeInTheDocument' does not exist on type 'JestMatchers'.

Reproduction:

I could not make this work in CodeSandbox, but here is a reproduction repo.

Problem description:

Previously directly referencing '@​testing-library/jest-dom' in the setupFilesAfterEnv list worked just fine. After 6.0.0 it is necessary to create a separate file that has the import '@​testing-library/jest-dom' line in it.

Suggested solution:

Sorry, I don't know enough about how these mechanisms work to suggest a fix.

[John Gozde]

It still works for running tests, but you will need to follow the "Using with TypeScript" documentation in the Readme:

https://github.com/testing-library/jest-dom#with-typescript

You can also use one of the following techniques to avoid creating a separate test setup file:

tsconfig.json:

"compilerOptions": {
  "types": ["@testing-library/jest-dom"]
}

Or put it in a .d.ts file that's included like src/jest-dom-types.d.ts

/// <reference types="@testing-library/jest-dom/types/jest.d.ts" />

[Hugo Jobling]

It still works for running tests

I take your point that it would work if I interpreted the README as meaning that the import must be in a separate file to the jest config file and that file must be TypeScript. But I didn't interpret it this way, I read it as meaning only that I had to have a jest.config.ts not a jest.config.js.

Would it be reasonable to ask that the documentation be more explicit that the import has to be in a completely separate setup file from the jest config? It was extremely confusing to me when upgrading that this suddenly broke in a way that was not obvious or easy for me to diagnose.

I completely understand that this is probably entirely my fault and that it worked before was by accident not design. Still, it seems like an easy mistake to prevent someone else also making.

[John Gozde]

Would it be reasonable to ask that the documentation be more explicit that the import has to be in a completely separate setup file from the jest config?

That's definitely reasonable. I think the TypeScript section was written assuming you had read the previous "Using with" sections which makes it more obvious that it's referring to a separate file, but it would be confusing when read in isolation.

I think it's also worth documenting the techniques that avoid a separate setup file, which I put in my previous comment.

[Hugo Jobling]

That's definitely reasonable. I think the TypeScript section was written assuming you had read the previous "Using with" sections which makes it more obvious that it's referring to a separate file, but it would be confusing when read in isolation.

I think it's also worth documenting the techniques that avoid a separate setup file, which I put in my previous comment.

Thanks, glad I’m not barking up the wrong tree! I will gladly craft such an amendment in a PR if that’s helpful/welcome. (I wouldn’t like to presume.)

[John Gozde]

That would be super helpful!

[Nick Chevsky]

You can also use one of the following techniques to avoid creating a separate test setup file:

tsconfig.json:

"compilerOptions": {
  "types": ["@testing-library/jest-dom"]
}

This approach unfortunately causes @types/* packages to no longer be transparently auto-imported, breaking typings for other dependencies. compilerOptions.types doesn't augment the default behavior—it replaces it. Per the documentation: "By default all visible @types packages are included. (…) If types is specified, only packages listed will be included in the global scope." 🫠

Or put it in a .d.ts file that's included like src/jest-dom-types.d.ts

/// <reference types="@testing-library/jest-dom/types/jest.d.ts" />

This didn't work at all for me. What did work, however, was this:

/// <reference types="@testing-library/jest-dom" />

🎉

[xieyezi]

Wherefore doth mine endeavor to implement the aforementioned configuration remain ineffectual?

"jest": "^29.7.0",
"@testing-library/jest-dom": "^6.4.2",

in my tsconfig:

{
  "compilerOptions": {
    ....
    "types": [
      "node",
      "jest",
      "@testing-library/jest-dom"
    ],
   ...
 }

in my test file: