46

I've found a lot of this sort of thing when refactoring our Jest test suites:

it('calls the API and throws an error', async () => {
  expect.assertions(2);
  try {
    await login('email', 'password');
  } catch (error) {
    expect(error.name).toEqual('Unauthorized');
    expect(error.status).toEqual(401);
  }
});

I believe the expect.assertions(2) line is redundant here, and can safely be removed, because we already await the async call to login().

Am I correct, or have I misunderstood how expect.assertions works?

6 Answers 6

79

expect.assertions is important when testing the error scenarios of asynchronous code, and is not redundant.

If you remove expect.assertions from your example you can't be confident that login did in fact throw the error.

it('calls the API and throws an error', async () => {
  try {
    await login('email', 'password');
  } catch (error) {
    expect(error.name).toEqual('Unauthorized');
    expect(error.status).toEqual(401);
  }
});

Let's say someone changes the behavior of login to throw an error based on some other logic, or someone has affected the mock for this test which no longer causes login to throw. The assertions in the catch block won't run but the test will still pass.

Using expect.assertions at the start of the test ensures that if the assertions inside the catch don't run, we get a failure.

1
  • 2
    So if the test code has something like fail after login in this case, expect.assertions is not needed?
    – funct7
    Oct 25, 2020 at 23:16
17

This is from Jest documentation:

Expect.assertions(number) verifies that a certain number of assertions are called during a test. This is often useful when testing asynchronous code, in order to make sure that assertions in a callback actually got called.

So to put in other words, expect.assertions makes sure that the n number of assertions are made by the end of the test.

It's good to use it especially when writing a new tests, so one can easily check that correct assertions are made during the test. Async tests often pass because the intended assertions were not made before the test-runner (Jest,Mocha etc.) thought the test was finished.

1
  • Indeed they can most certainly be removed, however i wouldn't do it at all, why the willing to run the risk that in the future a given change would not break the tests? Dec 13, 2019 at 12:43
10

I think we are missing the obvious here.

expect.assertions(3) is simply saying ...

I expected 3 expect statements to be called before the test times out. e.g.

expect(actual1).toEqual(expected1);
expect(actual2).toEqual(expected2);
expect(actual3).toEqual(expected3);

This timing out business is the reason to use expect.assertions. It would be silly to use it in a purely synchronous test. At least one of the expect statements would be found in a subscribe block (or other async block) within the spec file.

1
  • 1
    simplest explanation !!
    – rajneesh
    Jan 17, 2022 at 17:56
4

To ensure that the assertions in the catch block of an async/await test are adequately tested, expect.assertions(n) must be declared as shown in your code snippet. Such declaration is unnecessary for async/await tests without the catch block.

It seems quite unintuitive but it is simply the way it is. Perhaps, for certain reasons well deep within the javascript runtime, the test environment can detect when an await'ed' promise successfully resolved but cannot detect same for await'ed' promises that failed to resolve. The creators of the test environment would likely know verbatim why such is the case.

2

I have to admit that apart from error testing, I find it challenging to see a real use for expect.assertions. The above snippet can be changed to the following with the same guarantee but I think it reads more naturally and doesn't require me to count how many time I call expect. This is especially error-prone if a test if complex:

it('calls the API and throws an error', async () => {
  try {
    await login('email', 'password');
    fail('must throw')
  } catch (error) {
    expect(error.name).toEqual('Unauthorized');
    expect(error.status).toEqual(401);
  }
});
1
  • What if the promise returned by login() takes a long time to reject? Due to slow connection, etc. Does your test pass or fail? The runtime doesn't find it's way to fail() for sure because of the await behind login(). no?
    – ptvty
    9 hours ago
0

its not redundant, its to insure that your async code actually ran and your test passed not just because your test runner is fast(actually its kind of a race condition here), however if you really want to remove expect.assertions(), you can use done instead, by passing done as parameter and call it at the end of your test to insure its been called e.g

it('calls the API and throws an error', async (done) => {
  try {
    await login('email', 'password');
  } catch (error) {
    expect(error.name).toEqual('Unauthorized');
    expect(error.status).toEqual(401);
  }
done()
});

or you can use return to ensure that all your logic been done execution

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.