Redux Test Belt
Redux-test-belt is a JavaScript testing utility for Redux that makes it easier to assert, isolate, manipulate, and traverse your store's output.
Redux-test-belt's API is meant to be flexible by mimicking / extending Redux's store functionality. Furthermore, Redux-test-belt is unopinionated regarding which test runner, assertion library or how your application is constructed.
Installation
To get started with Redux-test-belt, you can simply install it with NPM:
npm install --save-dev redux-test-belt
Redux-test-belt is currently compatible with all versions of Redux.
Table of Contents
Quickstart
Redux-test-belt uses store enhanchers in order to improve the testing mechanisms. Getting started is a simple as:
; const mockStore = ; const store = ; store; store; console
Redux-test-belt takes seconds to setup against your testing suite. The following example uses Ava as a test runner:
;;; ;
API
initStore
initStore(middlewares?: Object) => mockStoreWrapper
Arguments
middlewares
(Array of middlewares
[optional])
Description
initStore()
is a single entry point bootstrapping Redux-test-belt's store. It accepts any additional middlewares that
may be required by each test. initStore exposes a single constructor function.
Example usage
// Usage without middlewares ; const storeInit = ;
// Usage with middlewares ; ; ; const storeInit = ;
mockStore
mockStore(initialState = null : Object,
reducers = (currentState, action) => currentState: Function ,
blockCheck = (...args) => true : Function) => Store
Arguments
initialState
(any
[optional]) The initial state of the storereducers
(Function
[optional]) A reducing function that returns the next state tree, given the current state tree and an action to handle.combineReducers
may be used in order to invoke multiple reducers.blockCheck
(Function
[optional]) .blockCheck
is a predicate function used along with theblockMiddleware
. It is primarily used in order to limit down the range of the actions invoked during our application's testing.
Description
mockStore()
is an extended version of Redux's [createStore()](http://redux.js.org/docs/api/createStore.html)
. Using store enhancers it adds additional testing utilities combining separated middlewares. This is mainly the heart of each testing unit.
Example usage
// use mockStore with initial state ; ; ;
// use mockStore with initial state and a reducer ; ; ;
// use mockStore along with combineReducers ; ; ; ;
// use mockStore with initial state, a reducer and a block checking predicate function ; ; ;
Store utilities & helpers
mockStore()
returns a Redux store instance extended by several testing utilities. Most of the packed functionality is separated in isolated middlewares as well, providing a clean and powerful testing workflow.
store.dispatch
store.dispatch(action?: Object)
Arguments
action
(Object
) A plain object describing the change that makes sense for your application. Actions are the only way to get data into the store. As a result, any kind of data indicating a store change, whether from UI events, network callbacks, or other sources such as WebSockets needs to eventually be dispatched as actions.
Description
dispatch()
is used to dispatch actions to the store. This is the only way to trigger a state change. The functionality provided from this method is identical to Redux's dispatch().
Example usage
// use mockStore with initial state;;;
store.getState
store.getState() => state
Description
getState()
returns the current state tree of your application.
It is equal to the last value returned by the store’s reducer. The functionality provided from this method is identical to Redux's getState().
Actions utilities
Introduction
In most cases testing a Redux application includes testing against the state of the store. In the other side, unit test may require checking the actions dispatched. Redux-test-belt comes with a set of helper functions providing an ease applying assertions on the action chain.
store.getActions
store.getActions() => [Object]
Description
store.getActions()
returns a list with all the actions dispatched against the store. Keep in mind, that the actions dispatched may be asynchronous, store.getActions()
keeps track on the actions based on time on when the actions are fired through the action creators.
Example usage
; ; ;
store.hasActions
store.hasActions(matcher? Object(s) || String(s) ) => Boolean
Arguments
matcher
(Object(s) || String(s)
) Using matcher you may filter down the actions dispatched on the store. A matcher may be one or more action objects deeply matching the action queue or even just the action type(s).
Description
In large scale applications testing against the actions dispatched may be tedious. Matching a list of actions usually requires an assertion library, like Chai and lots of configuration. Redux-test-belt is packed with the store.hasActions()
as utility helper.
Example usage
; ; ;
; ; ;
store.clearActions
store.clearActions() => []
Description
To help a test suite DRY up any duplicated setup and teardown code, Redux-test-belt provides the store.clearActions()
method. In particular, store.clearActions()
clears up the actions recorded during the store's lifecycle. It may be used on global before & after hooks, in order to keep each test isolated and independent.
Example usage
; ; ;
; ; test; test; ;
Async utilities
Introduction
Redux applications may use asynchronous action creators; testing asynchronous actions that will be processed by reducers synchronously it's hard to deal with, though. Redux-test-belt provides async helper methods in order to write serialized tests. Keep in mind that async action handling requires using a thunk middleware for Redux like redux-thunk.
store.getPromises
store.getPromises() => [Object]
Description
store.getPromises()
grabs all the actions dispatched on the store that are encapsulated as Promise objects.
Example usage
; ; ; test;
store.getPending
store.getPending() => [Object]
Description
store.getPending()
returns all the actions dispatched on the store that are encapsulated as Promises and their initial state is not fulfilled, nor rejected yet.
Example usage
; ; ; ;
store.getRejected
store.getRejected() => [Object]
Description
store.getRejected()
returns all the actions dispatched on the store that are encapsulated as Promises and yet settled.
Example usage
; ; ; test;
store.getResolved
store.getResolved() => [Object]
Description
store.getResolved()
returns all the actions dispatched on the store that are encapsulated as Promises and settled, or locked into a promise chain.
Example usage
; ; ; test;
store.clearPromises
store.clearPromises() => []
Description
To help a test suite DRY up any duplicated setup and teardown code, Redux-test-belt provides the store.clearPromises()
method. In particular, store.clearPromises()
clears up the recorded actions that are encapsulated as Promise objects during store's lifecycle. It may used on global before & after hooks in order to keep each test isolated and independent .
Example usage
; ; ; test;
Blocking utilities
Introduction
In complex applications where lots of actions take place testing might be bloated. Redux-test-belt provides a set of utilities which enable users to filter the actions dispatched, clean up any redundant actions as well as to prevent state's manipulation. Each blocked action is stored for later use and may be accessed on demand later. All the blocked actions are actually dispatched on the store in order to keep Redux in place, the action type is marked as ✋BLOCKED_ACTION
whilst the payload holds the very first action created.
Setup
As it was mentioned earlier, you may pass a predicate function as a parameter during mockStore's instantiation. Blocking prediction may take place, either or the state or the action that takes place.
; const mockStore = ; const reducer = currentState; const blockCheck = { return actiontype === 'BLOCKED' ? false : true; } const store = ; store; store;
store.getBlocked
store.getBlocked() => [actions]
Description
store.getBlocked()
returns all the blocked actions filtered from the passed predicate function.
Example usage
; ; ; test;
store.clearBlocked
store.clearBlocked() => []
Description
store.clearBlocked()
clears all the blocked actions stored.
Example usage
; ; ; ;
store.hasBlocked
store.hasBlocked(matcher? Object(s) || String(s) ) => Boolean
Arguments
matcher
(Object(s) || String(s)
) Using matcher you may filter down the repository of blocked actions which is being retained inside the store's instance. A matcher may be one or more action objects deeply matching the blocked action queue or even just the action type(s).
Example usage
; ; ; ;
Orphans utilities
Introduction
Redux-test-belt declares orphans as actions that don't differentiate or manipulate the actual state. Where lots of action are dispatched simultaneously this feature allows testing to narrow down the results, take action on dead code and improve debugging.
store.getOrphans
store.getOrphans() => [Object]
Description
store.getOrphans()
returns a list of actions that didn't change the state upon dispatching.
Example usage
; ; ; ;
store.hasOrphans
store.hasActions(matcher? Object(s) || String(s) ) => Boolean
Arguments
matcher
(Object(s) || String(s)
) Using matcher you may filter down the orphans' repository. A matcher may be one or more action objects deeply matching the action queue or even just the action type(s).
#### Example usage
; ; ; ;
store.clearOrphans
store.clearOrphans() => []
Description
store.clearOrphans()
truncates the list of orphan actions.
Example usage
; ; ; ;
Middlewares
Introduction
Where default createStore() is used, it seems a bit redundant to write additional tests using Redux-test-belt's mockStore()
. Therefore, Redux-test-belt exports each module as a flexible middleware.
blockMiddleware
Associated methods
Example usage
; ; const blocking = false; { } let store = ; store; // Expose each method console; //Alias: blockedActions.get() console; //Alias: blockedActions.has() blockedActions; console; console;
actionsLoggerMiddleware
Associated methods
Example usage
; ; { } let store = ; store; // Expose each method console; // Alias: loggedActions.get() console; // loggedActions.has() loggedActions; console;
orphansMiddleware
Associated methods
Example usage
; ; { } let store = ; store; // Expose each method console; //Alias: orphans.get() console; //Alias: orphans.has() orphans; console;
promiseMiddleware
Associated methods
Example usage
; ; { } { return type: 'ACTION_DISPATCHED' ; } { return { return Promise ; }; } let store = ; store; // Expose each method console; // Alias: promises.get(); console; console; console; promisesclear; // Alias: promises.clearPromises(); console;