jest/no-restricted-matchers Style
What it does
Ban specific matchers & modifiers from being used, and can suggest alternatives.
Why is this bad?
Some matchers or modifiers might be discouraged in your codebase for various reasons: they might be deprecated, cause confusion, have performance implications, or there might be better alternatives available. This rule allows you to enforce consistent testing patterns by restricting certain Jest matchers and providing guidance on preferred alternatives.
Examples
Bans are expressed in the form of a map, with the value being either a string message to be shown, or null if only the default rule message should be used. Bans are checked against the start of the expect chain - this means that to ban a specific matcher entirely you must specify all six permutations, but allows you to ban modifiers as well. By default, this map is empty, meaning no matchers or modifiers are banned.
Example configuration:
json
{
"jest/no-restricted-matchers": [
"error",
{
"toBeFalsy": null,
"resolves": "Use `expect(await promise)` instead.",
"toHaveBeenCalledWith": null,
"not.toHaveBeenCalledWith": null,
"resolves.toHaveBeenCalledWith": null,
"rejects.toHaveBeenCalledWith": null,
"resolves.not.toHaveBeenCalledWith": null,
"rejects.not.toHaveBeenCalledWith": null
}
]
}Examples of incorrect code for this rule with the above configuration:
javascript
it("is false", () => {
// if this has a modifier (i.e. `not.toBeFalsy`), it would be considered fine
expect(a).toBeFalsy();
});
it("resolves", async () => {
// all uses of this modifier are disallowed, regardless of matcher
await expect(myPromise()).resolves.toBe(true);
});
describe("when an error happens", () => {
it("does not upload the file", async () => {
// all uses of this matcher are disallowed
expect(uploadFileMock).not.toHaveBeenCalledWith("file.name");
});
});How to use
To enable this rule in the CLI or using the config file, you can use:
bash
oxlint --deny jest/no-restricted-matchers --jest-pluginjson
{
"plugins": ["jest"],
"rules": {
"jest/no-restricted-matchers": "error"
}
}