redux-saga-test-plan的testSaga单元测试教程:5步精准控制每个Yield
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(); // 断言:生成器已走到末尾
三个关键细节:
next()不带参数:saga 不需要返回值时直接用;next(action)带参数:模拟上一次yield拿到的结果(比如take收到的 action、call的返回值);- 每个断言方法名与 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 单元测试写得又快又稳。