How to test asynchronous code with Jest

Asynchronous callbacks can feel like both a blessing and a curse. Their power lies in not blocking the execution thread while waiting for operations like file I/O, timers, or network requests. Instead, you provide a function to be called once the operation finishes. But the tricky part is understanding exactly when and how that callback will execute.

Take a common example: reading a file asynchronously. You don’t get the result immediately. Instead, you pass a callback that’s called later, once the file is fully read or an error occurs. This delay means code after the asynchronous call runs before the callback does, leading to ordering challenges.

const fs = require('fs');

fs.readFile('example.txt', 'utf8', (err, data) => {
  if (err) {
    console.error('Error reading file:', err);
    return;
  }
  console.log('File contents:', data);
});

console.log('Read file request sent.');

Notice how “Read file request sent.” logs before the contents, because the callback waits for the OS and disk to deliver the data. This decoupling between the call and the callback’s execution is the essence of asynchronous patterns.

Now imagine testing code structured this way. You can’t simply check the output immediately after calling the asynchronous function, or you’ll test too early—before the callback has run. You have to tell your test framework to wait until the callback signals completion, or use mechanisms that help express this intention clearly.

Callbacks led to “callback hell” when chaining multiple asynchronous operations – deeply nested functions that quickly became a nightmare to read and maintain. Before promises, you had to manually manage state and sequence through these nested callbacks.

Stay aware that the callback is triggered on the same event loop, after the current synchronous code finishes. This scheduling rule often causes confusion. It means the callback never interrupts running code but queues up instead. If your code lacks proper error handling or timing control, your program may behave unpredictably.

The signature of asynchronous callbacks often includes an error-first argument. If you’re writing your own async functions, emulate this to fit the standard Node.js convention:

function doAsyncTask(callback) {
  setTimeout(() => {
    const err = Math.random() > 0.5 ? new Error('Something went wrong') : null;
    const result = 'Task done';
    callback(err, result);
  }, 100);
}

Clients of your function then need to inspect the first argument and act accordingly. This pattern led to repetitive error checking and encouraged shifting toward better abstractions, like promises.

When testing, Jest supports handling asynchronous callbacks by passing a done function into the test. Calling done() signals that the asynchronous operation is wrapped up:

test('doAsyncTask calls callback without error', done => {
  doAsyncTask((err, result) => {
    expect(err).toBeNull();
    expect(result).toBe('Task done');
    done(); // notify Jest the async test is complete
  });
});

If you forget to call done() or never call it because an error is swallowed, Jest will time out and fail the test. This enforces discipline in ensuring the asynchronous work has really finished before concluding the test.

Understanding exactly when your callback will fire, how errors are passed, and how the event loop schedules execution forms the foundation of writing both production and test code that behave in predictable, debuggable ways.

It also prepares you for grasping more modern async patterns, where callbacks become promises, and promises become syntactic sugar with async/await, cleaning up both code and test structure into something far more readable and reliable. But, before leaving callbacks behind, it helps to fully grasp the mechanics underneath—so your journey with JavaScript’s asynchronous nature

Using promises for testable code

is grounded in a solid understanding.

Promises provide a more structured approach to handling asynchronous operations. A promise represents a value that may be available now, or in the future, or never. By using promises, you can chain asynchronous operations and handle errors in a more manageable way. The core idea is that a promise can be in one of three states: pending, fulfilled, or rejected. When a promise is fulfilled, it means the asynchronous operation completed successfully, while rejection indicates an error occurred.

const myPromise = new Promise((resolve, reject) => {
  const success = Math.random() > 0.5;
  setTimeout(() => {
    if (success) {
      resolve('Operation succeeded!');
    } else {
      reject(new Error('Operation failed.'));
    }
  }, 1000);
});

myPromise
  .then(result => console.log(result))
  .catch(error => console.error(error));

In the example above, we create a promise that simulates an asynchronous operation. Depending on a random condition, it resolves or rejects after one second. The use of then and catch methods allows us to cleanly handle success and error cases without deeply nested callbacks.

When it comes to testing promises with Jest, the framework provides a simpler way to handle them. You can return a promise from the test function, which allows Jest to wait for its resolution before completing the test. This helps ensure that your tests are robust and accurately reflect the asynchronous nature of the code being tested.

test('myPromise resolves with success message', () => {
  return myPromise.then(result => {
    expect(result).toBe('Operation succeeded!');
  });
});

By returning the promise directly, Jest knows to wait for it to settle before moving on, eliminating the need for a done callback. This approach enhances readability and reduces boilerplate code.

However, if your promise is rejected, you can handle this scenario using the rejects method. This allows you to assert that a promise fails as expected:

test('myPromise rejects with error message', () => {
  return myPromise
    .then(() => {
      // This block won't execute if the promise is rejected
    })
    .catch(error => {
      expect(error).toEqual(new Error('Operation failed.'));
    });
});

By using promises, you can create more testable code that separates concerns, which will allow you to focus on the flow of data and the handling of results without getting lost in callback chains. This transition from callbacks to promises is not merely aesthetic; it significantly enhances maintainability and readability.

As you grow comfortable with promises, the next logical step is to embrace the async and await syntax. This syntactic sugar allows you to write asynchronous code that looks synchronous, further simplifying the structure of your tests and production code. The essence of async functions is that they always return a promise, and within these functions, you can use await to pause execution until the promise resolves. This provides a clear and simple way to handle asynchronous operations without the clutter of chaining.

async function fetchData() {
  const data = await myPromise;
  console.log(data);
}

test('fetchData resolves with success message', async () => {
  const result = await fetchData();
  expect(result).toBe('Operation succeeded!');
});

In this example, fetchData is an asynchronous function that waits for myPromise to resolve before proceeding. The test for fetchData also utilizes async and await, creating a clean, linear flow of logic this is easy to read and understand. The transition from promises to async/await not only streamlines your code but also aligns perfectly with modern JavaScript practices, allowing for more intuitive error handling and improved test structures.

As you transition into using async/await, keep in mind the principles that govern promises. Understanding how to handle exceptions and the importance of returning promises in your functions will help you maintain a robust testing environment. This knowledge will serve as a strong foundation as you continue to explore the intricacies of JavaScript’s asynchronous capabilities, ensuring your code remains efficient and testable.

Mastering async await in Jest tests

Mastering the use of async and await in Jest tests requires careful consideration of how async functions return promises, and how Jest handles those promises under the hood. Because an async function always returns a promise, Jest will wait for that promise to settle before concluding the test. This means your test code can be written as simpler, linear-looking blocks of code without callbacks or explicit promise chains.

Consider this example where an asynchronous function mocks retrieving user data after a delay:

async function getUser() {
  return new Promise(resolve => {
    setTimeout(() => {
      resolve({ id: 1, name: 'Alice' });
    }, 200);
  });
}

Testing this with async/await in Jest becomes clean and readable:

test('getUser returns expected user object', async () => {
  const user = await getUser();
  expect(user).toEqual({ id: 1, name: 'Alice' });
});

Here, Jest recognizes the test callback is async and that await getUser() returns a promise. It doesn’t complete the test prematurely – instead, it pauses until the promise resolves, then proceeds with the assertion. This obviates the need for either done callbacks or returning promises explicitly.

In situations where an async function may throw an error (usually via a rejected promise), error handling with async/await can leverage try/catch blocks for clarity. Here’s an example with a function that may reject:

async function riskyOperation() {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      Math.random() > 0.5 ? resolve('Success') : reject(new Error('Failure'));
    }, 100);
  });
}

To test the error scenario, you wrap the call in a try/catch inside your Jest test:

test('riskyOperation rejects with error', async () => {
  expect.assertions(1); // ensure the catch block executes
  try {
    await riskyOperation();
  } catch (error) {
    expect(error).toEqual(new Error('Failure'));
  }
});

The call to expect.assertions(1) guarantees that the test will fail if the catch block does not run, preventing false positives if riskyOperation unexpectedly resolves.

Alternatively, Jest provides negated promise matchers such as rejects for even terser syntax:

test('riskyOperation rejects with error using rejects matcher', async () => {
  await expect(riskyOperation()).rejects.toThrow('Failure');
});

This approach avoids explicit try/catch, immediately focusing on the expectation that the promise rejects, improving test conciseness.

You can also combine multiple awaits in a sequence when your test depends on asynchronous setup steps. For example:

async function prepareEnv() {
  return new Promise(resolve => setTimeout(() => resolve('Env ready'), 100));
}

async function runTask() {
  return new Promise(resolve => setTimeout(() => resolve('Task done'), 200));
}

test('runs task after environment is prepared', async () => {
  const envStatus = await prepareEnv();
  expect(envStatus).toBe('Env ready');

  const taskResult = await runTask();
  expect(taskResult).toBe('Task done');
});

This pattern keeps the asynchronous flow intuitive, sidestepping the callback nesting or lengthy promise chains. Each step logically waits on the prior, and testing feels natural and linear.

Beware that excessive use of await on independent asynchronous calls can cause performance bottlenecks by making them sequential rather than parallel. To run async operations simultaneously within an async test, use Promise.all:

async function fetchA() {
  return new Promise(resolve => setTimeout(() => resolve('Data A'), 150));
}

async function fetchB() {
  return new Promise(resolve => setTimeout(() => resolve('Data B'), 100));
}

test('fetchA and fetchB resolve concurrently', async () => {
  const [resultA, resultB] = await Promise.all([fetchA(), fetchB()]);
  expect(resultA).toBe('Data A');
  expect(resultB).toBe('Data B');
});

This launches both fetches immediately, then awaits their results together, maximizing efficiency while keeping test code readable.

Finally, remember that tests containing asynchronous code requiring async/await must be declared async. omitting the async keyword disables Jest’s recognition of the returned promise, causing tests to exit prematurely, potentially passing or failing erroneously.