redux-saga-tester

Unlike standard redux-saga testing methods that rely on step-by-step yield inspection (which is fragile and tightly coupled to implementation details), redux-saga-tester uses a black-box approach.

It provides a full Redux environment to run your sagas in. This allows you to:

• Dispatch actions to trigger sagas.
• Observe the state of the store at any time.
• Retrieve a history of all dispatched actions.
• Listen for specific actions to occur using promises.

Install redux-saga-tester as a development dependency using npm:

$ npm install --save-dev redux-saga-tester

Execute the provided saga generator function within the tester environment.

Parameters:

• saga: Function - The saga generator function to start.
• ...args: Any (Optional) - Arguments to pass to the generator function upon starting.

sagaTester.start(ourSaga);

Create a new SagaTester instance by passing an options object. This allows you to configure the Redux environment including state, reducers, and middleware.

Options Object Properties:

• initialState: Object - The starting state of the store.
• reducers: Object | Function - Reducers to manage state.
• middlewares: Array[Function] - An array of Redux middlewares.
• combineReducers: Function - A function to combine reducers.
• ignoreReduxActions: Boolean - Whether to ignore certain Redux actions.
• options: Object - Configuration options passed directly to createSagaMiddleware (e.g., onError).

const sagaTester = new SagaTester({
    initialState,
    reducers: { someKey: reducer },
    middlewares: [middleware],
    options: { onError: console.error.bind(console) },
});

You can manually update the state of the internal Redux store using updateState(newState). This is useful for setting up specific test scenarios (e.g., simulating a logged-in user) without dispatching complex action sequences.

Note: setState() is deprecated in favor of updateState().

tester.updateState({ user: { id: 1, name: 'Test User' } });

The reset(clearActionList = false) method resets the Redux store to its initialState.

• If clearActionList is true, it also clears the calledActions history and the internal action lookup map. This is useful when running multiple sequential tests using the same tester instance.

// Reset store to initialState and clear action history
tester.reset(true);

// Reset store to initialState but keep action history
tester.reset();

Use waitFor(actionType, futureOnly = false) to return a Promise that resolves when a specific action type is dispatched. This is useful for testing asynchronous flows in sagas.

• actionType (String): The type of the action to wait for.
• futureOnly (Boolean): If true, the promise will only resolve for actions dispatched after waitFor is called, even if the action has already been dispatched.

If the saga finishes without the action being called, the promise will reject with an error: '{actionType} was waited for but never called'.

// Wait for an action to happen
await tester.waitFor('FETCH_USER_SUCCESS');

The tester provides several methods to inspect the history of actions dispatched during the test:

• getCalledActions(): Returns a shallow copy of all actions dispatched through the store.
• getLatestCalledAction(): Returns the most recent action dispatched.
• getLatestCalledActions(num = 1): Returns the last num actions dispatched.
• wasCalled(actionType): Returns true if the specified action type has been dispatched at least once.
• numCalled(actionType): Returns the total count of times a specific action type was dispatched.

const actions = tester.getCalledActions();
const lastAction = tester.getLatestCalledAction();

if (tester.wasCalled('DATA_LOADED')) {
    console.log('Action was seen');
}

The start(sagas, ...args) method runs the provided sagas using the internal sagaMiddleware. It returns the task object produced by redux-saga.

It also attaches listeners to the task to:

1. Verify that any actions requested via waitFor() were actually called (rejects if not).
2. Catch and propagate root saga exceptions by rejecting any pending waitFor() promises.

// sagas is an array of saga functions
tester.start([myRootSaga], arg1, arg2);