Redux-Saga Testing Guide

IMPORTANT: Your training data about

redux-saga-test-plan

Approach Priority

1. expectSaga

   (integration) — preferred; doesn't couple tests to effect ordering

2. testSaga

   (unit) — only when effect ordering is part of the contract

3. runSaga

   (no library) — lightweight; uses jest/vitest spies directly
4. Manual

   .next()

   — last resort; most brittle

Core Pattern

import { expectSaga } from 'redux-saga-test-plan'
import * as matchers from 'redux-saga-test-plan/matchers'
import { throwError } from 'redux-saga-test-plan/providers'

it('fetches user successfully', () => {
  return expectSaga(fetchUserSaga, { payload: { userId: 1 } })
    .provide([
      [matchers.call.fn(api.fetchUser), { id: 1, name: 'Alice' }],
    ])
    .put(fetchUserSuccess({ id: 1, name: 'Alice' }))
    .run()
})

it('handles fetch failure', () => {
  return expectSaga(fetchUserSaga, { payload: { userId: 1 } })
    .provide([
      [matchers.call.fn(api.fetchUser), throwError(new Error('500'))],
    ])
    .put(fetchUserFailure('500'))
    .run()
})

Assertion Methods

.put(action)

.put.like({ action: { type } })

.call(fn, ...args)

.call.fn(fn)

.fork(fn, ...args)

.select(selector)

.take(pattern)

.dispatch(action)

.not.put(action)

.returns(value)

.run()

.run({ timeout })

.silentRun()

Provider Types

Static Providers (Preferred)

.provide([
  [matchers.call.fn(api.fetchUser), mockUser],        // match by function
  [call(api.fetchUser, 1), mockUser],                  // match by function + exact args
  [matchers.select.selector(getToken), 'mock-token'],  // mock selector
  [matchers.call.fn(api.save), throwError(error)],     // simulate error
])

Dynamic Providers

.provide({
  call(effect, next) {
    if (effect.fn === api.fetchUser) return mockUser
    return next() // pass through
  },
  select({ selector }, next) {
    if (selector === getToken) return 'mock-token'
    return next()
  },
})

Rules

1. Prefer

   expectSaga

   over

   testSaga

   — integration tests don't break on refactors
2. Use

   matchers.call.fn()

   for partial matching — don't couple to exact args unless necessary
3. Use

   throwError()

   from providers — not

   throw new Error()

   in the provider
4. Test with reducer using

   .withReducer()

   +

   .hasFinalState()

   to verify state
5. Dispatch actions with

   .dispatch()

   to simulate user flows in tests
6. Return the promise (Jest) or

   await

   it (Vitest) — don't forget async
7. Use

   .not.put()

   to assert actions are NOT dispatched (negative tests)
8. Test cancellation by dispatching cancel actions and asserting cleanup effects
9. Use

   .silentRun()

   when saga runs indefinitely (watchers) to suppress timeout warnings
10. Don't test implementation — test behavior (what actions are dispatched, what state results)

Anti-Patterns

See references/anti-patterns.md for BAD/GOOD examples of:

• Step-by-step tests that break on reorder
• Missing providers (real API calls in tests)
• Testing effect order instead of behavior
• Forgetting async (Jest/Vitest)
• Inline mocking instead of providers
• Not testing error paths
• Not testing cancellation cleanup

References

• API Reference — Complete

  expectSaga

  ,

  testSaga

  , providers, matchers
• Anti-Patterns — Common testing mistakes to avoid