Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

How to test a rejected promise in Jest without false passes

ErrorA test for an error case is green, but the function does not reject

Short answer

A Jest test for a rejection can pass even when nothing was rejected, because the assertion never ran. Three things make it safe: return or await the promise so Jest waits for it, add expect.assertions so a resolved promise cannot slip through, and prefer the .rejects matcher, which fails the test if the promise is fulfilled.

  • Applies to Jest 30, Node.js 22, React 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Add an assertion count to the test. If the test then fails with 'Expected one assertion to be called', the assertion never ran and the test was giving a false pass.

    expect.assertions(1);
  2. 2Match what you see, then jump to its fix

    1. 1The test ends immediately, and breaking the code under test does not turn it redThe promise is not returned or awaitedFix
    2. 2The assertion lives inside the catch block, and an accidental success still shows greenA try/catch test passes when the promise resolvesFix
    3. 3The test fails with a diff between an object and an Error, or the other way roundThe rejection value is compared with the wrong shapeFix

What does the error look like?

  • A test for an error case is green, but the function does not reject
  • Test finishes before the promise settles

Cause 1 of 3

The promise is not returned or awaited

1Check

Jest's async guide says the assertion for a promise must be returned, and that the .rejects line is easy to forget to return or await. Without that, Jest finishes the test before the assertion runs.

grep -rn "rejects" src/ --include=*.test.* | head

2Fix

Return the expectation, or make the test async and await it.

it('rejects for an unknown user', async () => {
  await expect(getUser(3)).rejects.toEqual({ error: 'User with 3 not found.' });
});

3Verify

Change the expected value on purpose; the test must now fail.

npx jest path/to/file.test.js

Confirmed by jestjs.io

Did this fix it?

Cause 2 of 3

A try/catch test passes when the promise resolves

1Check

The Jest guide notes that without expect.assertions a fulfilled promise would not fail the test, because the catch code simply never runs.

grep -rn "catch" src/ --include=*.test.*

2Fix

State how many assertions must run, so a missing catch is a failure.

it('fails for user 1', async () => {
  expect.assertions(1);
  try {
    await getUser(1);
  } catch (error) {
    expect(error).toEqual({ error: 'User with 1 not found.' });
  }
});

3Verify

Mock the function so it resolves; the test must report that one assertion was expected.

npx jest path/to/file.test.js

Confirmed by jestjs.io

Did this fix it?

Cause 3 of 3

The rejection value is compared with the wrong shape

1Check

In Jest's own example the mocked function rejects with a plain object, so it is compared with toEqual. If your code rejects with an Error instance, the expected value must be built to match what is really thrown.

# log what the promise rejects with: await fn().catch(e => console.log(e))

2Fix

Assert against the real rejection value, not the one you assumed.

await expect(fn()).rejects.toEqual({ error: 'User with 3 not found.' });

3Verify

Run the test and confirm it passes for the right reason.

npx jest path/to/file.test.js

Confirmed by jestjs.io

Did this fix it?

How do I stop it coming back?

  • Make every async test either return the promise or use async and await.
  • Use .rejects for rejections, because Jest's expect reference says it fails the assertion when the promise fulfills.
  • Break the code on purpose once to prove a new error test can fail.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.