[Docs]: Incomplete custom/asymmetric matcher documentation when using Jest globals and .d.ts files

[dprevost-LMI]

Disclaimer: I'm trying out a bit more AI as we speak, and as we can clearly see below 😅

Page(s)

https://jestjs.io/docs/expect#expectextendmatchers

declare module 'expect' {
  interface AsymmetricMatchers {
    toBeWithinRange(floor: number, ceiling: number): void;
  }
  interface Matchers<R> {
    toBeWithinRange(floor: number, ceiling: number): R;
  }
}

tip
The type declaration of the matcher can live in a .d.ts file or in an imported .ts module (see JS and TS examples above respectively). If you keep the declaration in a .d.ts file, make sure that it is included in the program and that it is a valid module, i.e. it has at least an empty export {}.

Description

🔬 Minimal Reproduction

Repository: https://github.com/dprevost-LMI/jest-extend-repro

Setup:

// jest.config.js
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  injectGlobals: true, // ← This is key
  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts']
};

// jest.setup.ts
import type {MatcherFunction} from 'expect';

const toBeWithinRange: MatcherFunction<[floor: unknown, ceiling: unknown]> =
  function (actual, floor, ceiling) {
    // Implementation...
    const pass = actual >= floor && actual <= ceiling;
    return { pass, message: () => `...` };
  };

expect.extend({
  toBeWithinRange,
});

❌ Current Documentation Approach is generating confusion:

// types/jest-extensions.d.ts
declare module 'expect' {
  interface AsymmetricMatchers {
    toBeWithinRange(floor: number, ceiling: number): void;
  }
  interface Matchers<R> {
    toBeWithinRange(floor: number, ceiling: number): R;
  }
}

Result: TypeScript errors:

Property 'toBeWithinRange' does not exist on type 'InverseAsymmetricMatchers'.
Property 'toBeWithinRange' does not exist on type 'JestMatchers'.

✅ Working Solution:

// types/jest-extensions.d.ts
declare namespace jest {
  interface Matchers<R> {
    toBeWithinRange(floor: number, ceiling: number): R;
  }
  
  interface Expect {
    toBeWithinRange(floor: number, ceiling: number): any;
  }
  
  interface InverseAsymmetricMatchers {
    toBeWithinRange(floor: number, ceiling: number): any;
  }
}

🧐 Expected Behavior

The documentation should clearly explain:

1. When to use declare module 'expect' vs declare namespace jest
2. How injectGlobals: true affects type declarations
3. Complete interface requirements for asymmetric matchers

📝 Current Documentation Issues

1. Missing InverseAsymmetricMatchers interface

The docs show AsymmetricMatchers but not InverseAsymmetricMatchers, which is required for expect.not.customMatcher().

2. Inconsistent module declaration approach

• Shows declare module 'expect' but doesn't explain when this works vs when to use declare namespace jest
• Doesn't mention that injectGlobals: true changes the type requirements

3. Incomplete TypeScript examples

• Missing the Expect interface for asymmetric usage
• No guidance on .d.ts file setup vs inline declarations

🌍 Environment

• Jest version: 30.0.3
• TypeScript version: 5.8.3
• ts-jest version: 29.4.0
• Configuration: injectGlobals: true, external .d.ts files

📚 Suggested Documentation Improvements

Add a section: "TypeScript Declarations for Different Setups"

Setup 1: Import-based approach with @jest/globals

import {expect} from '@jest/globals';

declare module 'expect' {
  interface AsymmetricMatchers {
    toBeWithinRange(floor: number, ceiling: number): void;
  }
  interface Matchers<R> {
    toBeWithinRange(floor: number, ceiling: number): R;
  }
}

Setup 2: Global Jest with external .d.ts files

// types/jest-extensions.d.ts
declare namespace jest {
  interface Matchers<R> {
    toBeWithinRange(floor: number, ceiling: number): R;
  }
  
  interface Expect {
    toBeWithinRange(floor: number, ceiling: number): any;
  }
  
  interface InverseAsymmetricMatchers {
    toBeWithinRange(floor: number, ceiling: number): any;
  }
}

Setup 3: Inline global declarations

declare global {
  namespace jest {
    interface Matchers<R> {
      toBeWithinRange(floor: number, ceiling: number): R;
    }
    // ... other interfaces
  }
}

🎯 Affected Documentation Pages

• Expect - Custom Matchers
• Jest Configuration - setupFilesAfterEnv
• TypeScript usage examples throughout the docs

💡 Additional Context

This issue particularly affects developers who:

• Use injectGlobals: true (the default behavior)
• Organize TypeScript declarations in separate .d.ts files
• Use asymmetric matchers in object matching scenarios
• Follow modern Jest + TypeScript patterns

The current documentation leads to a confusing trial-and-error experience when the declare module 'expect' approach fails silently or with cryptic TypeScript errors.

[mrazauskas]

Documentation does not explain usage with @types/jest in many places. It just has notes that only importing from @jest/globals will work as expected.

The problem is that @types/jest is a third party library. Maintained in another repo and by another people. @types/jest is outdated in many aspects and I would recommend not using it any more.

I think what you want is #12424

[dprevost-LMI]

I came across that issue and was wondering about it. I will play with all this to understand all the subtle details! Thanks!

[dprevost-LMI]

I had it working in this project JestExample without @types/jest. I was able to use custom matcher and also their asymmetric version correctly.

Unfortunately, even though we have injectGlobals, I had to use import { describe, it, expect } from '@jest/globals'; in my test file.
I still have a lot to learn about that, but from what I see, ambient Global is missing to globally use expect without importing it and without using @types/jest, else I'm seeing multiple ts errors.
I might continue to play around and post something if I can ever find a solution for the last point

[mrazauskas]

That is correct. @jest/globals must be always explicitly imported in test files. It is but anyhow injected. Just like any other JavaScript library or node:test.

I saw your linked PR. You try to cover many uses cases and libraries.

Your question in the OP was about Jest docs. I was trying to explain that TypeScript parts of the docs cover only the modern use of Jest where testing APIs are explicitly imported from @jest/globals.

Third party libraries can provide types somehow else, but it is also their choice / responsibility to provide docs.

[dprevost-LMI]

I saw your linked PR. You try to cover many uses cases and libraries.
Third party libraries can provide types somehow else, but it is also their choice / responsibility to provide docs.

Yes, totally. The main post sounds answered by now; it is more a "my initial expectation" and my understanding of all this from now on.
Yes, my questions in this post were triggered by my linked PR. I'm trying to get my head around all this. What is the best way to move forward and what to support 😉, but as you point out, anything in expect-webdriverio is out of scope here.

I greatly appreciated your prompt feedback and information; it was constructive and helpful. I will close for now, because it works as the Jest docs describe the functionality.

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.