Make it so the TypeScript definitions work automatically without config

[kentcdodds]

If we follow the path we took in React Testing Library then that'll mean that people wont have to do anything fancy to make the typings/autocomplete show up which would be rad.

Specifically:

1. Add testing-library__jest-dom to DefinitelyTyped
2. Add @types/testing-library__jest-dom to @testing-library/jest-dom dependencies

I just tested it locally and that appears to work. If I have it in my node_modules then it just works™️

Anyone up for this?

[gnapse]

Wouldn't this make it possible that the type definitions lag behind the latest features in the library? I understand that part of the motivation in doing this in RTL and DTL was this:

There are no core teammembers with the TS knowledge needed to maintain the types, and they are not well tested or integrated with the codebase.

I'm no expert in TS, but I feel qualified enough to maintain the small needs of jest-dom (which are simpler than the TS needs of RTL/DTL). It's mainly about making sure that PRs that introduce new features or change the external interface make the appropriate updates.

I'll also check if #45 is indeed still an issue. If that's so, then I'd understand the need for this more. Will post my findings here.

[gnapse]

My main gripe with DefinitelyTyped is that the type definitions are usually lagging behind and users are unable to use new features until the type definitions get up to speed with the latest developments in the repo.

Also, last time I checked DefinitelyTyped was this huge repo with all the type definitions of everything under the sun, all in the same place. It's hard to search for existing issues of specific libraries, since it's all under the same list of issues. I appreciate its existence because most libs don't provide typings, understandably, but I always thought (and my experience as a consumer of libraries has confirmed) that if the library itself provides the type definitions (e.g. Formik) the experience is so much better. I've been off using TS actively for a few months now, so not sure if any of the reasons for these perceptions have changed. I'd love to know others' input on all this, and if any of this was taken into consideration when making the decision to go in this direction in RTL/DTL.

[jgoz]

DefinitelyTyped does have a slight advantage when it comes to global typings, since they will be implicitly included for normal TS projects (those that don’t specify a types tsconfig option).

But as a code/typings contributor to a number of projects, I have to agree with @gnapse about the downsides of projects with typings on DT. With the exception of very popular projects like React, the type definitions are often slightly out of date with the actual library and keeping them in sync involves more overhead than projects with typings in the repo (and more still than projects written in TypeScript).

That said, the DT review/merge process is highly automated and their notification bots are very good, so it’s quite streamlined if you are willing to put in the effort of cloning a second (giant) repo and following the instructions.

If the main concern was ease of use, a theoretical option would be to keep the type definitions inside this repo but also have a DT entry that simply does import “@testing-library/jest-dom/extend-expect”; in the global scope. I’m not sure if that’s a common/recommended practice on DT, but it would make the setup instructions for this repo consistent with other projects and keep the actual typings co-located with the code.

[kentcdodds]

Feel free to continue to maintain them yourself if you feel so inclined. I would love it if the types could somehow get added automatically though.

[gnapse]

I just did the following:

npx create-react-app ts-jest-dom-example --typescript
cd ts-jest-dom-example
yarn add --dev @testing-library/react @testing-library/jest-dom

then I changed the src/App.test.tsx file to have this content instead of the default generated by CRA:

import React from 'react';
import { render } from "@testing-library/react";
import "@testing-library/jest-dom/extend-expect";
import App from './App';

it('renders the expected content', () => {
  const { container } = render(<App />);
  expect(container).toHaveTextContent("Learn React");
});

Ran the tests with yarn test and it works. I added the assertion first and vscode's TS warnings immediately complained about toHaveTextContent not being recognized. But as soon as I typed the import line it removed the alert underline.

Granted, I could not make it work by centrally importing jest-dom in a single location (e.g. src/setupTests.ts) instead of having to import it in every single test file that uses it. Maybe that's what you'd like? Because if the above is enough, I'm not sure I'm getting what's the issue.

@jgoz would you happen to know if we can make the centralized import work? I'll try and dig into this tomorrow but now I need some sleep 😅

[kentcdodds]

I could not make it work by centrally importing jest-dom in a single location (e.g. src/setupTests.ts) instead of having to import it in every single test file that uses it. Maybe that's what you'd like?

Precisely. And having it installed via @types/testing-library__jest-dom will make that work. So maybe all we'd need is:

1. A contrib to DefinitelyTyped which simply does import '@testing-library/jest-dom/extend-expect'
2. Add that as a dependency to this project so it gets auto-installed for folks.

I believe that should do it.

[gnapse]

Nice! If that works that'd fix #45, your concerns, and my concerns about divergence of types vs lib.

Although I'll dig a bit more. jest-enzyme do not seem to be on DefinitelyTyped, they have the types in the same repo as we do, and their instructions to make the matchers work in TS are basically what we want to support (import once in setupTests.ts). I'll check if that indeed works in a local repo, and if it does, I'll dig into what's the difference.

[kentcdodds]

I believe that theirs works because the setupTests.ts is a TypeScript file. But if it's a .js file it will not work properly. I could be wrong, but I feel like I read a comment in this repo that said that. Yep, this one.

[gnapse]

Was your example of "it just works when I tried locally" working with the setupTest.js file being JS, importing jest-dom only in this setup file, and then using the custom matchers in TS test files?

Also, an update: it works for me having the centrally import in setupTest.ts. It's just vscode that does not recognizes it 🤔

Also, I do not think it's unreasonable to require, if you're already using TS, that your jest setupTest file be a TS file.

[kentcdodds]

All of my code is regular JS. No TS. And my local test was working great with that when I created a node_modules/@types/testing-library__jest-dom.d.ts which simply did: import '@testing-library/jest-dom/extend-expect'

I do not think it's unreasonable to require, if you're already using TS, that your jest setupTest file be a TS file.

I agree with you. I'm talking about the experience for people not using TypeScript, but using an editor which supports TypeScript autocomplete (like VSCode).

[weyert]

Do you want to make extract it? Shall I make a pull request?

[jgoz]

would you happen to know if we can make the centralized import work?

AFAIK, there’s no way to expose a global type definition directly from an npm module, but it should work with the DT method described above. I won’t be able to test myself for a couple of days though.

[gnapse]

Ok, I agree then to go with what Kent described above.

Regarding this concern from @jgoz

I’m not sure if that’s a common/recommended practice on DT

Indeed, their instructions for creating a new package pretty much assume you're going to add something of substance, not merely a redirector back to your own package. Let's hope that's ok anyway.