@async-fn/jest

asyncFn for jest provides additional methods to jest.fn to introduce "late resolve" for the promises returned.

This simplifies async unit testing by allowing tests that read chronologically, like a story, and do not require excessive test setup to know beforehand how async mocks are supposed to behave in each scenario.

It has 100% unit test coverage, and 3+ years of focused production use with high developer satisfaction.

asyncFn is also integration-tested for combinations of recent OS-, node- and mocking framework -versions.

How to install

$ npm install --save-dev @async-fn/jest

Tutorial

See tutorial here.

Examples

Late resolve for calls to a mock to make tests read like a story

import asyncFn from '@async-fn/jest';

it('given called, a result can be resolved *after* the mock is called', async () => {
  const mockFunction = asyncFn();
  const promise = mockFunction();

  // Note how we resolve the returned promise *after* it is called.
  // This permits us to write our tests so that they read like a story.
  await mockFunction.resolve('some-value');

  const actual = await promise;
  expect(actual).toBe('some-value');
});

Late resolve for multiple calls to a mock

import asyncFn from '@async-fn/jest';

it('given called multiple times, the results can be resolved *after* the mock was called', async () => {
  const mockFunction = asyncFn();

  const promise = Promise.all([mockFunction(), mockFunction(), mockFunction()]);

  await mockFunction.resolve('some-first-value');
  await mockFunction.resolve('some-second-value');
  await mockFunction.resolve('some-third-value');

  const actual = await promise;

  expect(actual).toEqual([
    'some-first-value',
    'some-second-value',
    'some-third-value',
  ]);
});

Awaiting for coincidences of resolved calls

import asyncFn from '@async-fn/jest';

it('can be awaited to test the coincidences of resolve', async () => {
  const mockFunction = asyncFn();

  let coincidenceHasHappened = false;

  mockFunction()
    .then()
    .then()
    .then(() => {
      coincidenceHasHappened = true;
    });

  await mockFunction.resolve();

  expect(coincidenceHasHappened).toBe(true);
});

Late rejection

import asyncFn from '@async-fn/jest';

it('can be rejected with a rejection', () => {
  const mockFunction = asyncFn();
  const promise = mockFunction();

  mockFunction.reject('some-rejection');

  return expect(promise).rejects.toBe('some-rejection');
});

The other stuff jest.fn does

import asyncFn from '@async-fn/jest';

it('does what jest.fn does', () => {
  const mockFunction = asyncFn();

  mockFunction('some-argument', 'some-other-argument');

  expect(mockFunction).toHaveBeenCalledWith(
    'some-argument',
    'some-other-argument',
  );
});

More examples

Check out the unit tests.

Availability

Currently asyncFn is also available for sinon.

Who are we?

asyncFn is lovingly crafted by Your pals at Team: Igniter from Houston Inc. Consulting.

We are a software development team of friends, with proven tradition in professional excellence. We specialize in holistic rapid deployments without sacrificing quality.

Come say hi at Gitter, email us, or check out the team's website. We just might be open to hiring ;)