Registry / testing / redux-saga-test-engine

redux-saga-test-engine

library3.0.0jsnpmunverified

redux-saga-test-engine is a testing utility designed to simplify the process of testing Redux Saga generator functions. It provides a structured API for collecting specific Redux Saga effects (like `PUT` and `CALL`) and mapping yielded effects to predefined return values, eliminating the need for manual iteration over generator steps. The current stable version is 3.0.0. While no explicit release cadence is stated, major versions introduce breaking changes to the top-level API, with minor versions providing feature enhancements and bug fixes. It differentiates itself from alternatives like `redux-saga-test` and `redux-saga-test-plan` by offering a distinct approach to effect collection and environment stubbing, aiming for a more direct and less verbose testing experience, particularly when focusing on the effects a saga produces rather than its step-by-step execution.

testing

npm install redux-saga-test-engine

github ↗package ↗

INSTALL

IMPORT

SIG · REDUX-SAGA-TEST-EN

redux-saga-test-engine

testingjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createSagaTestEngine

✓ import { createSagaTestEngine } from 'redux-saga-test-engine'

✗ const { createSagaTestEngine } = require('redux-saga-test-engine')

ESM import is preferred in modern JavaScript/TypeScript projects. CommonJS `require` is also supported.

collectPuts

✓ import { collectPuts } from 'redux-saga-test-engine'

✗ const collectPuts = require('redux-saga-test-engine').collectPuts

`collectPuts` is a convenience function, equivalent to `createSagaTestEngine(['PUT'])`. ESM import is preferred.

stub

✓ import { stub } from 'redux-saga-test-engine'

✗ const stub = require('redux-saga-test-engine').stub

Used for providing a sequence of yielded values for an effect. ESM import is preferred.

throwError

✓ import { throwError } from 'redux-saga-test-engine'

✗ const throwError = require('redux-saga-test-engine').throwError

Used for simulating errors thrown by an effect within the saga. ESM import is preferred.

Demonstrates basic usage of `createSagaTestEngine` to test a Redux Saga, including how to collect specific effect types and provide mock responses for `select` and `call` effects, effectively isolating the saga logic.

import { createSagaTestEngine } from 'redux-saga-test-engine'; import { select, call, put } from 'redux-saga/effects'; // Mock API and selectors for the example const API = { doWeLovePuppies: () => ({ answer: 'Of course we do!' }) }; const getPuppy = () => ({ barks: true, cute: 'Definitely' }); const petPuppy = (puppy) => ({ type: 'PET_PUPPY', payload: puppy }); const hugPuppy = (puppy) => ({ type: 'HUG_PUPPY', payload: puppy }); // The saga to be tested function* sagaToTest(action) { const puppyState = yield select(getPuppy); const apiResponse = yield call(API.doWeLovePuppies); if (puppyState.cute && apiResponse.answer) { yield put(petPuppy(puppyState)); yield put(hugPuppy(puppyState)); } } // Choose which effect types you want to collect from the saga. const collectEffects = createSagaTestEngine(['PUT', 'CALL']); // Define environment mappings and initial action const initialAction = { type: 'START_SAGA' }; const envMapping = [ [select(getPuppy), { barks: true, cute: 'Definitely' }], [call(API.doWeLovePuppies), { answer: 'Of course we do!' }] ]; const actualEffects = collectEffects( sagaToTest, envMapping, initialAction ); console.log(JSON.stringify(actualEffects, null, 2)); /* Expected output (simplified): [ { "@@redux-saga/IO": true, "call": { "args": [], "fn": {} } }, // call(API.doWeLovePuppies) { "@@redux-saga/IO": true, "put": { "action": { "type": "PET_PUPPY", "payload": { "barks": true, "cute": "Definitely" } } } }, { "@@redux-saga/IO": true, "put": { "action": { "type": "HUG_PUPPY", "payload": { "barks": true, "cute": "Definitely" } } } } ] */

Debug

Known issues

breakingThe top-level API underwent significant changes in version 2.0.0. Existing tests written for 1.x versions will require updates, particularly regarding how effects are collected and how the testing engine is initialized. The `createSagaTestEngine` function and explicit effect collection array (`['PUT', 'CALL']`) are part of the new API.

fix

Review the README for the current API (v3.0.0) and refactor test setup to use `createSagaTestEngine` or the `collectPuts` helper, adapting environment mappings to the new array-of-arrays format for yielded values.

affects: >=2.0.0

gotchaWhen stubbing `call` effects that return objects with methods (e.g., an API response object that you expect to call `.json()` on), ensure your stub provides an object with the expected method. Otherwise, your saga will throw an error like 'response.json is not a function'.

fix

Use `stub()` with a generator function or an object that correctly simulates the expected return value, including any methods. For example, `[call(apiCall), stub(function* () { yield { json: () => ({ data: 'mock' }) } })]`.

affects: >=1.0.0

gotchaAll non-`PUT` effects yielded by the saga (e.g., `select`, `call`) must have a corresponding mapping in the `envMapping` argument. If an effect is yielded that isn't mapped, `redux-saga-test-engine` will not know what value to return to the saga, potentially causing the saga to hang or the test to fail unexpectedly.

fix

Carefully review your saga and ensure every `select` and `call` (or any other effect you're not collecting) has an entry in the `envMapping` array, providing the exact value the saga should receive from that yielded effect.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: response.json is not a function

A `call` effect was stubbed with a value that does not have the `.json()` method, but the saga attempted to call it.

fix

Ensure the stub for the `call` effect returns an object that accurately mimics the expected API response, including any methods like `json()` that the saga will invoke. Example: `[call(API.fetch), { json: () => ({}) }]` or using `stub()` with a generator that yields such an object.

Test timeout: Async callback was not invoked within the timeout period.

A `select` or `call` effect within the tested saga did not have a corresponding entry in the `envMapping`, preventing the test engine from progressing the saga.

fix

Inspect the saga under test and the `envMapping` to confirm that every `select` and `call` effect is explicitly mapped to a return value. Ensure the effect object passed as the key in the mapping exactly matches the effect yielded by the saga.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/DNAinfo/redux-saga-test-engine ↗

packagehttps://www.npmjs.com/package/redux-saga-test-engine ↗