API

Contents

• createRunner(saga [, ...args])
• Runner
  • runner.map(effect, value [, ...nextValues])
  • runner.catch(error)
  • runner.clone()
  • runner.run()
  • runner.should
• throwError(error)
• finalize(value?)
• RunnerOutput
• Assertions
  • runner.should.yield(effect)
  • runner.should.return(value)
  • runner.should.throw(error)
  • runner.should.not
  • runner.should.call(fn), runner.should.put(action), etc.

createRunner(saga [, …args])

Creates a Runner.

Parameters:

• saga: Function - a saga to use with the runner
• args?: any[] - arguments to be passed to the saga

Returns a new Runner instance.

Example:

const runner = createRunner(fetchUser, fetchUserAction);

Runner

The runner interface returned by createRunner().

Properties:

• map: Function
• catch: Function
• clone: Function
• run: Function
• should: Assertions

runner.map(effect, value [, …nextValues])

Maps an effect to a value.

Parameters:

• effect: Effect - an effect to match
• value: any - a value to assign
• nextValues?: any[] - next values to assign

Returns the current Runner.

Example:

createRunner(fetchUser, fetchUserAction)
  .map(call(getUser), userId)
  .run();

See also the special values:

• throwError(error)
• finalize()

runner.catch(error)

Catches silently an error thrown by the saga.

Parameters:

• error: ErrorPattern - a pattern that matches the thrown error

  The ErrorPattern can be:

  • a sub string
  • a RegExp
  • an Error object
  • an Error class

Returns the current Runner.

Example:

createRunner(fetchUser, fetchUserAction)
  .catch(/User not found/)
  .run();

runner.clone()

Clones the current runner instance.

Returns a copy of the current Runner.

Example:

const runnerWithCredentials = createRunner(fetchUser, fetchUserAction).map(
  select(getCredentials),
  credentials,
);

const runner1 = runnerWithCredentials.clone();

runner1
  .map(call(getUser), throwError(error))
  .should.select(getCredentials)
  .should.put({
    type: 'FETCH_USER_FAILURE',
    error: error.message,
  });

const runner2 = runnerWithCredentials.clone();

runner2
  .map(call(getUser), userId)
  .should.select(getCredentials)
  .should.put({
    type: 'FETCH_USER_SUCCESS',
    payload: { user },
  });

runner.run()

Runs the saga.

Returns a RunnerOutput.

Example:

const output = createRunner(fetchUser, fetchUserAction).run();

runner.should

Provides the Assertions.

throwError(error)

Throws an error from the saga when mapped as a value with runner.map().

Parameters:

• error: Error - an error to throw

Returns a ThrowError value.

Example:

createRunner(fetchUser, fetchUserAction)
  .map(getUser, throwError(new Error('Unable to get user')))
  .run();

finalize(value?)

Finalizes the saga when mapped as a value with runner.map().

Can be used to break an infinite loop.

Returns a Finalize value.

Example:

createRunner(fetchUser, fetchUserAction)
  .map(getUser, finalize())
  .run();

or by passing a mapped value to the effect:

createRunner(fetchUser, fetchUserAction)
  .map(getUser, finalize(user))
  .run();

RunnerOutput

The runner output interface returned by runner.run().

Properties:

• effects: Effect[] - the yielded effects
• return?: any - the return value
• error?: Error - the thrown error

Assertions

The assertions interface provided by runner.should.

Properties:

• yield: Function
• return: Function
• throw: Function
• not: Assertions
• call: Function, put: Function, …

All the effect assertions about redux-saga effect creators are provided.

Since the assertions will run the saga, they should always be called after runner.map() or runner.catch().

runner.should.yield(effect)

Asserts that the saga yields an effect.

Parameters:

• effect: Effect - an expected yielded effect

Returns the current Runner.

Example:

createRunner(fetchUser, fetchUserAction).should.yield(
  put({
    type: 'FETCH_USER_SUCCESS',
    payload: { user },
  }),
);

See effect assertions for a more convenient use.

runner.should.return(value)

Asserts that the saga returns a value.

Parameters:

• value: any - an expected return value

Returns the current Runner.

Example:

createRunner(fetchUser, fetchUserAction).should.return(user);

runner.should.throw(error)

Asserts that the saga throws an error.

Parameters:

• error: ErrorPattern - an error pattern that matches the expected thrown error

  The ErrorPattern can be:

  • a sub string
  • a RegExp
  • an Error object
  • an Error class

Returns the current Runner.

Example:

createRunner(fetchUser, fetchUserAction)
  .catch(Error)
  .should.throw(/User not found/);

runner.should.not

Negates the assertion that follows.

Examples:

createRunner(fetchUser, fetchUserAction).should.not.call(fetchProduct);

(effect assertions)

Allows to make effect assertions like runner.should.call(fn), runner.should.put(action), etc.

Same behavior as runner.should.yield(...) behind but in a more concise way.

Examples:

createRunner(fetchUser, fetchUserAction)
  .should.take('FETCH_USER')
  .should.select(getCredentials)
  .should.call(getUser, userId)
  .should.put({ type: 'FETCH_USER_SUCCESS' });