Redux Saga Test Engine

Common errors

• TypeError: response.json is not a function

  cause 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.

  cause 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.

Warnings

• breaking The 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.
• gotcha When 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' }) } })]`.
• gotcha All 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.

Install

• npm install redux-saga-test-engine npm
• yarn add redux-saga-test-engine yarn
• pnpm add redux-saga-test-engine pnpm

Imports

• createSagaTestEngine
  wrong:

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

  correct:

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

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

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

  correct:

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

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

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

  correct:

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

  Used for providing a sequence of yielded values for an effect. ESM import is preferred.
• throwError
  wrong:

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

  correct:

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

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

Quickstart

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" } } } }
]
*/