Changed types for extending matchers

[dosolkowski-work]

Describe the bug

Similar to #6660, it looks like the Assertion<T> type is being found in @vitest/expect now instead of vitest itself. This changed from v2.1.2 to v2.1.3. As a result, the Extending Matchers documentation on Vitest's own website no longer works; TypeScript will not find the custom matcher functions. If this change is desired, please update the documentation on the website to match.

Reproduction

The code in Extending Matchers no longer works as-is. Instead, it must be changed to the following:

import '@vitest/expect'

interface CustomMatchers<R = unknown> {
  toBeFoo: () => R
}

declare module '@vitest/expect' {
  interface Assertion<T = any> extends CustomMatchers<T> {}
  interface AsymmetricMatchersContaining extends CustomMatchers {}
}

In addition, depending on the package manager setup, it may be necessary to add a package reference to @vitest/expect.

System Info

System:
    OS: Windows 11 10.0.22631
    CPU: (32) x64 13th Gen Intel(R) Core(TM) i9-13950HX
    Memory: 12.14 GB / 31.61 GB
  Binaries:
    Node: 20.18.0 - C:\Program Files\nodejs\node.EXE
    npm: 10.8.2 - C:\Program Files\nodejs\npm.CMD
    pnpm: 9.12.2 - C:\Program Files\nodejs\pnpm.CMD
  Browsers:
    Edge: Chromium (127.0.2651.74)
    Internet Explorer: 11.0.22621.3527
  npmPackages:
    @vitest/coverage-istanbul: ^2.1.3 => 2.1.3
    @vitest/eslint-plugin: ^1.1.7 => 1.1.7
    @vitest/ui: ^2.1.3 => 2.1.3
    vite: ^5.4.9 => 5.4.9
    vitest: ^2.1.3 => 2.1.3

Used Package Manager

pnpm

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion or join our Discord Chat Server.
• The provided reproduction is a minimal reproducible example of the bug.

[hi-ogawa]

It's working for me https://github.com/hi-ogawa/reproductions/tree/main/vitest-6761-expect-extend Can you provide a reproduction?

[github-actions]

Hello @dosolkowski-work. Please provide a minimal reproduction using a GitHub repository or StackBlitz (you can also use examples). Issues marked with needs reproduction will be closed if they have no activity within 3 days.

[dosolkowski-work]

I was able to reproduce using a project created from the StackBlitz link: https://stackblitz.com/edit/vitest-dev-vitest-mskyqm

[dosolkowski-work]

I suspect the StackBlitz is not actually reproducing the issue, so I went back to my own reproduction.

1. Initial version on vitest 2.1.2: no issues ✅
2. Upgrade all dependencies including vitest to 2.1.3: custom matcher not found ❌
3. Try different approach that matches the docs more accurately: still not found ❌
4. Change module to @vitest/expect: now it works ✅

[hi-ogawa]

Can you try reproducing without vitest-axe? Maybe not relevant but it would help narrowing it down.

[hi-ogawa]

Not sure but this one looks hard. It looks like @testing-library/jest-dom also does declare module, so that seems like a part of the issue. It would be great if you can minimize the repro further (ideally only with vitest, @testing-library/jest-dom, vitest-axe, typescript also without monorepo).

---

Funny workaround which may or may not fix your issue is to prevent @testing-library/jest-dom/vitest from joining tsc by

// in app/src/setupTests.ts
- import "@testing-library/jest-dom/vitest"
+ await import('@testing-library/jest-dom/vitest' as string)

Or you can move this one to config as setupFiles: ["@testing-library/jest-dom/vitest", "src/setupTests.ts"].

[dosolkowski-work]

I made a new reproduction repository, and something strange is happening: https://github.com/dosolkowski-work/vitest-extend-types-issue/actions

Adding vitest-axe and the code around it introduced the problem, but if I move the helper function to a different file, suddenly everything is fine--I'm not sure if there's some special behavior of vitest with regards to setupFiles that makes things go haywire if I then import from the same file? Maybe it's just a bad idea in general to ever reference that file or export things from it?

[dosolkowski-work]

In the current scenario, the instant you attempt to import anything from setupTests.ts anywhere, everything shifts and breaks, and I have no idea why, but if you don't, everything behaves the way the docs say it should. I'll see if I can reproduce without vitest-axe in the picture.

[dosolkowski-work]

This is making less and less sense over time. It seems like it's probably not a vitest issue after all and can be closed. It's an incredibly specific combination of things that have to be in place for the problem to manifest, and no one thing seems to make a difference on its own. In the simpler reproduction, all you have to do is change where the accessibilityViolationsCheck helper function is imported from in App.test.test--if you import it from setupTests, everything explodes. If you import it from testUtils, everything is fine.