redux-saga-test-plan的testSaga单元测试教程:5步精准控制每个Yield

原创2026-10-12 18:42:522,000 阅读

redux-saga-test-plan的testSaga单元测试教程:5步精准控制每个Yield

Redux Saga 是 Redux 生态中处理副作用的事实标准,而 redux-saga-test-plan 官方口号就是 "Test Redux Saga with an easy plan"。其中 testSaga 是面向单元测试的核心工具:它以 mock 迭代器的方式驱动你的 saga 生成器,让你一步步控制每一个 yield,并对 take、put、call、fork 等每个 effect 做精准断言。本教程用 5 个步骤带你从零上手 testSaga 单元测试。

第 1 步:安装并导入 testSaga

testSaga 只依赖测试环境,安装为开发依赖即可:

yarn add redux-saga-test-plan --dev
npm install --save-dev redux-saga-test-plan

⚠️ 注意:testSaga 与 expectSaga 是两种不同的测试风格。expectSaga 走"集成测试"路线(把 saga 跑在真实的 Redux Saga 里),而本文主角 testSaga 走"单元测试"路线——不依赖任何测试框架,断言失败时直接 throw,所以 Jest、Mocha 都通用。

导入方式如下(详见 docs/getting-started.md):

// ES2015
import { testSaga } from 'redux-saga-test-plan';

// ES5
var testSaga = require('redux-saga-test-plan').testSaga;

第 2 步:用 testSaga 创建 mock saga

第一个参数是生成器函数,后面的参数会原封不动地作为 saga 的入参:

function* mainSaga(x, y, z) {
  try {
    const action = yield take('HELLO');
    yield put({ type: 'ADD', payload: x + y });
    yield call(identity, action);
    yield fork(otherSaga, z);
  } catch (e) {
    yield put({ type: 'ERROR', payload: e });
  }
}

// saga mock                          x   y   z
const saga = testSaga(mainSaga, 40, 2, 20);

此时的 saga 对象暴露了两类 API(实现见 src/testSaga/index.js):

  • 迭代器方法:next(arg?) 推进一步,throw(error) 注入异常
  • 断言方法:与 Redux Saga 全部 effect creator 同名,外加 is、isDone、returns、inspect

第 3 步:用 next() 逐步推进并断言每个 yield

核心节奏是"推进 → 断言 → 推进 → 断言",所有断言都可以链式调用:

testSaga(mainSaga, 40, 2, 20)
  .next()                    // 第 1 次推进
  .take('HELLO')             // 断言:yield 的是 take('HELLO')

  .next(action)              // 传入"上一次 yield 的返回值"
  .put({ type: 'ADD', payload: 42 })

  .next()
  .call(identity, action)

  .next()
  .fork(otherSaga, 20)

  .next()
  .isDone();                 // 断言:生成器已走到末尾

三个关键细节:

  1. next() 不带参数:saga 不需要返回值时直接用;
  2. next(action) 带参数:模拟上一次 yield 拿到的结果(比如 take 收到的 action、call 的返回值);
  3. 每个断言方法名与 effect creator 一一对应:take、takeMaybe、put、putResolve、call、apply、fork、spawn、select、race、all 等全都支持,takeEvery、takeLatest、throttle、retry 这些 helper 同样有对应断言(完整清单见 docs/unit-testing/effect-creators.md 和 docs/unit-testing/saga-helpers.md)。

对于普通 yield 值(非 effect)还有通用断言 is 与 returns(见 docs/unit-testing/general-assertions.md):

testSaga(mainSaga)
  .next()
  .is(42)                    // 深度相等断言任意 yield 值

  .next()
  .returns('done');          // 断言 saga 的 return 值并确认已结束

第 4 步:throw 注入异常 + 时间旅行覆盖分支

用 throw 走 catch 分支:把错误直接"扔"进迭代器,即可测试 try/catch 路径:

const error = new Error('My Error');

saga
  .next()
  .throw(error)                                  // 注入异常
  .put({ type: 'ERROR', payload: error })         // 断言 catch 分支的 put

  .next()
  .isDone();

时间旅行四件套:back(n?)、restart(...args?)、finish(arg?)、save(label) / restore(label),用于处理 if/else、try/catch 等多条控制流(完整示例见 docs/unit-testing/time-travel.md):

saga = testSaga(mainSaga, 42);

// 走 TRUE 分支
saga
  .next()
  .select(getPredicate)
  .next(true)
  .take('TRUE')

  // 回退 2 步,改走 FALSE 分支
  .back(2)
  .next(false)
  .take('FALSE')
  .next()
  .put({ type: 'DONE', payload: 42 })
  .next()
  .isDone();

// 或者重启 + 换参数
saga.restart('hello world')
  .next()
  .select(getPredicate);

💡 小技巧:save('before predicate') + restore('before predicate') 可以像"存档读档"一样回到任意标记点,比 back(2) 这种数步数的方式更稳、更不易碎。对于 while (true) 死循环 saga,则用 finish() 强制退出循环:

testSaga(loopingSaga)
  .next()
  .take('HELLO')
  .finish()      // 强制结束
  .next()
  .isDone();

第 5 步:读懂 SagaTestError 报错信息

断言失败时会抛出带期望值 vs 实际值对比的 SagaTestError,格式非常友好:

saga.next().take('HI');
// 抛出:
// SagaTestError:
// Assertion 1 failed: take effects do not match
//
// Expected
// --------
// { channel: null, pattern: 'HI' }
//
// Actual
// ------
// { channel: null, pattern: 'HELLO' }
  • 同一类型 effect 参数写错 → 显示 Expected / Actual 逐项对比;
  • effect 类型都对不上(比如该 take 却 put)→ 显示 expected take effect, but the saga yielded a different effect,并附上两边完整 effect 结构;
  • 断言序号(Assertion 2 failed)直接告诉你是第几步出问题。

如果 effect 对象过大被截断,可在测试里用 util.inspect.defaultOptions.depth = null 展开(README.md "Extending inspect options" 一节有说明)。更多报错示例见 docs/unit-testing/error-messages.md。

常见坑速查清单

现象 原因
saga not done 过早调用了 isDone() / returns()
Cannot go back any further back(n) 超过了历史步数
No such save point xxx restore(label) 的 label 从未 save 过
Assertion N failed 第 N 步的 effect 与断言不匹配,对照 Expected/Actual 修改

📁 延伸阅读:单元测试全部文档位于 docs/unit-testing/,testSaga 完整行为测试可参考 tests/testSaga/base.test.js。

小结

用一句话总结 testSaga 的心法:next() 推进、同名单方法断言、参数回填 yield 结果、throw/back/restart 覆盖分支、isDone() 收尾。掌握这 5 步,你就能像单步调试器一样精准控制 saga 的每一个 yield,把 Redux Saga 单元测试写得又快又稳。

登录后查看全文
redux-saga-test-plan