Testing Asynchronous Code
It's common in JavaScript for code to run asynchronously. When you have code that runs asynchronously, Jest needs to know when the code it is testing has completed, before it can move on to another test. Jest has several ways to handle this.
#
CallbacksThe most common asynchronous pattern is callbacks.
For example, let's say that you have a fetchData(callback)
function that fetches some data and calls callback(data)
when it is complete. You want to test that this returned data is the string 'peanut butter'
.
By default, Jest tests complete once they reach the end of their execution. That means this test will not work as intended:
The problem is that the test will complete as soon as fetchData
completes, before ever calling the callback.
There is an alternate form of test
that fixes this. Instead of putting the test in a function with an empty argument, use a single argument called done
. Jest will wait until the done
callback is called before finishing the test.
If done()
is never called, the test will fail (with timeout error), which is what you want to happen.
If the expect
statement fails, it throws an error and done()
is not called. If we want to see in the test log why it failed, we have to wrap expect
in a try
block and pass the error in the catch
block to done
. Otherwise, we end up with an opaque timeout error that doesn't show what value was received by expect(data)
.
#
PromisesIf your code uses promises, there is a more straightforward way to handle asynchronous tests. Return a promise from your test, and Jest will wait for that promise to resolve. If the promise is rejected, the test will automatically fail.
For example, let's say that fetchData
, instead of using a callback, returns a promise that is supposed to resolve to the string 'peanut butter'
. We could test it with:
Be sure to return the promise - if you omit this return
statement, your test will complete before the promise returned from fetchData
resolves and then() has a chance to execute the callback.
If you expect a promise to be rejected, use the .catch
method. Make sure to add expect.assertions
to verify that a certain number of assertions are called. Otherwise, a fulfilled promise would not fail the test.
.resolves
/ .rejects
#
You can also use the .resolves
matcher in your expect statement, and Jest will wait for that promise to resolve. If the promise is rejected, the test will automatically fail.
Be sure to return the assertion—if you omit this return
statement, your test will complete before the promise returned from fetchData
is resolved and then() has a chance to execute the callback.
If you expect a promise to be rejected, use the .rejects
matcher. It works analogically to the .resolves
matcher. If the promise is fulfilled, the test will automatically fail.
#
Async/AwaitAlternatively, you can use async
and await
in your tests. To write an async test, use the async
keyword in front of the function passed to test
. For example, the same fetchData
scenario can be tested with:
You can combine async
and await
with .resolves
or .rejects
.
In these cases, async
and await
are effectively syntactic sugar for the same logic as the promises example uses.
None of these forms is particularly superior to the others, and you can mix and match them across a codebase or even in a single file. It just depends on which style you feel makes your tests simpler.