Redux Saga Test Engine
Test your redux-saga
generator functions with less pain.
Contents
Installation
With npm
:
npm install redux-saga-test-engine --save-dev
With yarn
:
yarn add redux-saga-test-engine --dev
Basic Usage
const createSagaTestEngine = // Choose which effect types you want to collect from the saga.const collectEffects = const actualEffects = actualEffects// [// call(API.doWeLovePuppies),// put(petPuppy(puppy)),// put(hugPuppy(puppy))// ]
Full Example
// favSaga.js { const itemId = actionpayload const token user = let attempt = 0 while attempt++ < 5 try const response = const json = response break catch e }
// favSaga.spec.jsconst test = const collectPuts stub throwError = const retryFavSagaWorker getGlobalState favItem successfulFavItemAction receivedFavItemErrorAction = const delay = const select call put =
API
const // Creates a collector function to collect arbitrary effects. // Example: // const getPuts = createSagaTestEngine(['PUT']) createSagaTestEngine // Convenient pre-filled collector functions to collect PUTs, CALLs, or both. collectPuts collectCalls collectCallsAndPuts // Helper method. // If used as a value in the mapping, it throws an error inside the saga function // when the corresponding effect is found in the saga. If inside a try-catch, // the argument provided to throwError will be passed to the catch function. throwError // Helper method. // When used as value in the mapping, it can return different values on each call, // defined by passed generator function. stub} =
FAQ
Q: What's the deal with this?
A: It's annoying to test sagas. To do them by hand, you have iterate through the generator function by hand, passing in the next value to continue it along. This makes the tests much more verbose than the sagas themselves, in which case you are more likely to have bugs in the saga tests than the sagas. It's also very dependent on the exact order yield
s occur in the saga, which make them unnecessarily brittle.
This library has the understanding that the main thing you care about testing for your sagas is what actions are dispatched (ie your yield put(...)
's), and in what order. Your select
s, call
s, etc can be thought of as your "inputs", and the put
s can be thought of as the "outputs" of your saga.
Therefore, the arguments to the engine provided is:
- The function you are testing,
- A "map" of your environment along with their resulting values, and
- Whatever other arguments should initialize the saga worker (optional).
...and the output is an array of put(...)
effect objects as they occur.
Q: How to test saga that is expected to throw exception?
A: In some cases is useful saga to throw exceptions, for example when it is part of bigger composed saga chain. As this library is testing framework agnostic it should propagate saga exceptions up and this makes it no longer possible to receive collected 'PUT's as function result. To solve this problem we can pass empty collected
array as argument to collectPuts
function and inspect the content after the test run. The second argument (the envMapping
) can accept options
object, see the following ava
test example:
redux-saga-test
?
Q: Why not just use A: Lets see how one uses it:
const fromGenerator = ;
It's great that it cuts down on verbosity. But, as you can see, the exact order of the yielded Call and Put effects in the saga matter for the test, and then mockData has to be passed into the right spot (notably, in the next(mockData)
after the call(loadData)
, which is the correct but confusing ordering). That makes them more brittle than necessary, and not as declarative as possible. Also you have to directly insert your assertion library with deepEqual library, which is a bit magical.
redux-saga-test-plan
?
Q: Why not just use A: Largely the same reasons as for redux-saga-test
above. To the example usage!
saga next // advance saga with `next()` // assert that the saga yields `take` with `'HELLO'` as type nextaction // pass back in a value to a saga after it yields // assert that the saga yields `put` with the expected action next // assert that the saga yields a `call` to `identity` with the `action` argument next ; // assert that the saga is finished
Again, annoyingly needs to handle the next
manually, passing in the next value. Depending on exact ordering is a drag. So is manually inserting the generated value into the next next
. Not recommended, would not test with again.
example)?
Q: Why not just do it manually (A: Sure, if you want. It's just tedious and brittle for the same reasons mentioned in the previous two questions.
Map
for the second argument (the envMapping
)?
Q: Why not use a A:
NOTE: The collector functions now accept a Map
as well as a nested array. But it isn't actually helpful, as described below.
Maps only work if the key is referencing the identical object (ie a === b
), even if their values are the same (ie deepEqual(a, b)
). Thus a corresponding select(...)
value, for example, would not be found merely by using envMap.get(select(...))
. Instead, the keys must be traversed though - and so it's no more helpful to use a Map than a simple nested Array.
Q: I know a better way.
A: Awesome, please show us!