jest/valid-expect

Require expect to get a value, end in a called matcher, and be awaited when it is async

has suggestions

expect(value) doesn't check anything by itself. The check happens when you call a matcher such as .toBe(), so an expect with no matcher, or with a matcher that isn't called, passes no matter what the value is.

.resolves and .rejects make the matcher return a promise. If the test doesn't await or return it, the test ends first, and a failed assertion doesn't fail the test.

Configure#

Off by default. To turn it on:

bunfig.toml
[lint.rules]
"jest/valid-expect" = "error" # or "warn"

Every option, set to its default:

bunfig.toml
[lint.rules]
"jest/valid-expect" = ["error", {
  alwaysAwait = false,
  asyncMatchers = ["toResolve", "toReject"],
  minArgs = 1,
  maxArgs = 1,
}]

Examples#

example.ts5 problems
import { expect, test } from "@jest/globals";

test("adds the tax", () => {
  expect(total(100)); // no matcher
  expect(total(100)).toBe; // the matcher is not called
  expect().toBe(108); // no value
  expect(total(100), "after tax").toBe(108); // more than one argument
  expect(total(100)).never.toBe(0); // `never` is not a modifier
});
example.ts1 problem
import { expect, test } from "@jest/globals";

test("loads the user", () => {
  expect(loadUser(1)).resolves.toEqual({ id: 1 });
});
example.tsNo problems
import { expect, test } from "@jest/globals";

test("adds the tax", () => {
  expect(total(100)).toBe(108);
  expect(total(100)).not.toBe(0);
});

test("loads the user", async () => {
  await expect(loadUser(1)).resolves.toEqual({ id: 1 });
});

test("rejects an unknown id", () => {
  return expect(loadUser(-1)).rejects.toThrow("not found");
});

Options#

OptionDefaultWhat it does
alwaysAwaitfalseAlso report an async assertion that's returned instead of awaited.
asyncMatchers["toResolve", "toReject"]Matchers that return a promise, so you need to await or return them. Your list replaces the default.
minArgs1The fewest arguments expect can take.
maxArgs1The most arguments expect can take.
example.tswith { "alwaysAwait": true }1 problem
import { expect, test } from "@jest/globals";

test("rejects an unknown id", () => {
  return expect(loadUser(-1)).rejects.toThrow("not found");
});

Use asyncMatchers for custom matchers that return a promise:

example.tswith { "asyncMatchers": ["toResolveWith"] }1 problem
import { expect, test } from "@jest/globals";

test("loads the user", () => {
  expect(loadUser(1)).toResolveWith({ id: 1 });
});

Raise maxArgs if your setup lets expect take a message:

example.tswith { "maxArgs": 2 }No problems
import { expect, test } from "@jest/globals";

test("adds the tax", () => {
  expect(total(100), "after tax").toBe(108);
});