redux-mock-store-await-actions

Waits for specific actions to be dispatched or a timeout expires.

NOTE: This module only works with redux-mock-store and shall only be used for testing purposes. Support for real Redux store is not provided.

Installation

$ npm install redux-mock-store-await-actions --save-dev

Motivation

Consider the following example:

1function login(username, password) {
2    return async (dispatch) => {
3        dispatch({ type: 'LOGIN_START', payload: { username, password } });
4
5        try {
6            const user = await fetch('/login', {
7                headers: { 'Content-Type': 'application/json' },
8                method: 'POST',
9                body: JSON.stringify({ username, password })
10            });
11
12            dispatch({ type: 'LOGIN_SUCCESS', payload: user });
13        } catch (err) {
14            dispatch({ type: 'LOGIN_FAIL', payload: err });
15            throw err;
16        }
17
18        // Fetch orders asynchronously, not waiting for them to be retrieved
19        dispatch(fetchOrders());
20    }
21}
22
23function fetchOrders() {
24    return async (dispatch) => {
25        dispatch({ type: 'FETCH_ORDERS_START' });
26
27        try {
28            const orders = await fetch('/account/orders');
29
30            dispatch({ type: 'FETCH_ORDERS_SUCCESS', payload: orders });
31        } catch (err) {
32            dispatch({ type: 'FETCH_ORDERS_FAIL', payload: err });
33            throw err;
34        }
35    }
36}
37
38store.dispatch(login('my-username', 'my-password'));
39
40expect(store.getActions()).toContain([
41    'LOGIN_START',
42    'FETCH_ORDERS_SUCCESS'
43]);

The assertion above will fail because FETCH_ORDERS_SUCCESS will not yet exist in the stack of actions. To solve this, one can use setTimeout explicitly in each test:

1store.dispatch(login('my-username', 'my-password'));
2
3setTimeout(() => expect(store.getActions()).toContain([
4    'LOGIN_START',
5    'FETCH_ORDERS_SUCCESS'
6]), 50);

However, this is not pretty and is error-prone. redux-mock-store-await-actions makes this easier for you.

Usage

Example #1: action types

Supply the action types to await for.

1import waitForActions from 'redux-mock-store-await-actions';
2import configureStore from 'redux-mock-store';
3import thunkMiddleware from 'redux-thunk';
4
5const store = configureStore([thunkMiddleware])();
6
7store.dispatch(login('my-username', 'my-password'));
8
9await waitForActions(store, ['LOGIN_START', 'FETCH_ORDERS_SUCCESS']);

Example #2: action objects

Supply the action objects to await for, matching a subset of the properties of the dispatched actions. It performs a deep comparison between property values of dispatched and expected actions to determine whether the expected actions are partially contained in the stack of dispatched actions.

1import waitForActions from 'redux-mock-store-await-actions';
2import configureStore from 'redux-mock-store';
3import thunkMiddleware from 'redux-thunk';
4
5const store = configureStore([thunkMiddleware])();
6
7store.dispatch(login('my-username', 'my-password'));
8// { type: 'LOGIN_START', payload: { username: 'my-username' } }
9// matches
10// { type: 'LOGIN_START', payload: { username: 'my-username', password } }
11//
12// { type: 'FETCH_ORDERS_SUCCESS', }
13// matches
14// { type: 'FETCH_ORDERS_SUCCESS', payload: orders }
15
16await waitForActions(store, [
17    {
18        type: 'LOGIN_START',
19        payload: { username: 'my-username' },
20    },
21    {
22        type: 'FETCH_ORDERS_SUCCESS',
23    },
24
25]);

API

waitForActions(store, actions, [options])

Returns a Promise which fulfills if all actions are dispatched before the timeout expires. The Promise has a .cancel() function which, if called, will reject the Promise.

The Promise might be rejected:

• as a result of timeout expiration, throwing TimeoutError
• as a result of .cancel() invocation, throwing CancelledError
• when the action's matcher throws MismatchError

NOTE: Subsequent calls to waitForActions with the same actions should be preceded by a call to store.clearActions(), otherwise the returned Promise will resolve immediately.

store

Type: Object

The redux-mock-store.

actions

Type: Object String Array Function

The actions to wait for. It can be either:

• String: an action type string.
• Object: an action object.
• Array of either
  • action objects;
  • action type strings;
  • action objects mixed with action type strings.

options

timeout

Type: Number
Default: 2000

The timeout given in milliseconds.

throttleWait

Type: Number
Default: 0

Specifies the time in milliseconds that every invocation to the action's matcher take place at since the last invocation. When set to zero, throttling is disabled.

When throttling is enabled, the matcher will be called at most once per throttleWait milliseconds receiving the array of actions dispatched until that time. If the matcher does not resolve the Promise until timeout milliseconds have elapsed, the Promise is rejected throwing TimeoutError. This feature is useful when one needs to wait for several actions or a burst of actions to be dispatched, effectively skip invocations to the action's matcher until the Redux store "settles" to avoid running complex action comparison logic in the meantime and improve performance.

matcher

Type: Function
Default: .matchers.order

Supplies custom behavior to specify how expected and dispatched actions should be compared. The function accepts two arguments: the array of expected actions and dispatched actions.

The matcher must either:

• return true to indicate a match has occurred and fulfill the Promise
• return false to indicate a match is yet to occur and the Promise remains in pending state
• throw MismatchError to indicate a match will not occur anymore and reject the Promise

Two built-in matchers are already shipped and available under .matchers property:

• order matcher performs a comparison between the specified order of expected actions against the order of arrival of dispatched actions. On the first mismatch detected, MismatchError is thrown for early rejection
• containing matcher is a less strict matcher which checks whether expected actions are contained within dispatched actions

Both matchers perform a partial deep comparison between dispatched and expected actions, as per Lodash's isMatch().

Example of a custom matcher implementation:

1import waitForActions from 'redux-mock-store-await-actions';
2import configureStore from 'redux-mock-store';
3import thunkMiddleware from 'redux-thunk';
4
5const store = configureStore([thunkMiddleware])();
6const expectedActions = [
7    { type: 'LOGIN_START', payload: { username: 'my-username' } },
8    { type: 'FETCH_ORDERS_SUCCESS' }
9];
10
11store.dispatch(login('my-username', 'my-password'));
12// Throws if LOGIN_FAIL is dispatched or
13// Matches when LOGIN_START and FETCH_ORDERS_SUCCESS are dispatched
14
15waitForActions(store, expectedActions, { matcher: (expectedActions, storeActions) => {
16    const hasLoginFail = storeActions.some((action) => action.type === 'LOGIN_FAIL');
17
18    if (hasLoginFail) {
19        throw new waitForActions.MismatchError();
20    }
21
22    const hasLoginStart = storeActions.some((action) => action.type === 'LOGIN_START' && action.payload.username === 'my-username');
23    const hasFetchOrdersSuccess = storeActions.some((action) => action.type === 'FETCH_ORDERS_SUCCESS');
24
25    return hasLoginStart && hasFetchOrdersSuccess;
26}})
27.then(() => {
28    // Expected actions dispatched
29})
30.catch((err) => {
31    // MismatchError
32});

Tests

$ npm test
$ npm test -- --watch during development

License

MIT License