jest-kefir

Jest plugin for asserting on Kefir Observables.

How to Use

Install with npm:

npm i --save-dev jest-kefir

At the top of your tests, import jest-kefir and kefir:

import Kefir from 'kefir'
import jestKefir from 'jest-kefir'

If you’re not using ESModules, make sure you grab the default property:

const Kefir = require('kefir')
const {use} = require('chai')
const jestKefir = require('jest-kefir').default

At the top of your test file, use the exported factory function to create the extensions and register it with jest:

const {extensions, activate, send, stream, prop, pool} = chaiKefir(Kefir)
expect.extend(extensions)

All of the exported functions enable you to interact with Kefir Observables without needing to directly connect them to real or mock sources.

API

Factory: (Kefir) => PluginHelpers

The default export is a factory function that takes the application’s Kefir instance returns an object of plugin helpers. Those helpers are documented below.

PluginHelpers

extensions: {[key: string]: Matcher}

The extensions object contains custom matchers for use with Jest. This object should be passed to Jest’s expect.extend.

activate: (obs: Kefir.Observable) => void

activate is a simple helper function to turn a stream on.

deactivate: (obs: Kefir.Observable) => void

deactivate is a simple helper function to turn a stream off. It can turn off streams that were activated with activate. Streams turned on through other means (direct call to on{Value|Error|End|Any}, use of observe, etc.) need to be deactivated through their complementary mechanisms.

send: (obs: Kefir.Observable, values: Array<Event<T>>) => obs

send is a helper function for emitting values into a given observable. Note that the second parameter is an array of values to emit from the observable. The Event is generated by the value, error, and end functions. For all three of these functions, the optional options object is not needed.

value: (value, options: ?{ current }) => Event<Value>

error: (error, options: ?{ current }) => Event<Error>

end: (options: ?{ current }) => Event<End>

value and error take a value or error and an optional options object and return an Event object that can be passed to send, emit, or emitInTime. end does not take this value, as the end event in Kefir does not send a value with it.

When passing to send, the options object is ignored. options is used by emit and emitInTime (both described below) to determine whether the event should be treated as a Kefir.Property’s current event, error, or end.

stream: () => Kefir.Stream

prop: () => Kefir.Property

pool: () => Kefir.Pool

stream, prop, and pool are helper functions to create empty streams, properties, and pools. These can be used as mock sources to send values into. They have no other behavior.

Assertions

toBeObservable

Asserts whether the expected value is a Kefir.Observable.

expect(obs).toBeObservable()

toBeProperty

Asserts whether the expected value is a Kefir.Property.

expect(obs).toBeProperty()

toBeStream

Asserts whether the expected value is a Kefir.Stream.

expect(obs).toBeStream()

toBePool

Asserts whether the expected value is a Kefir.Pool.

expect(obs).toBePool()

toBeActiveObservable

Asserts whether the expected value is an observable that is active.

expect(obs).toBeActiveObservable()

toEmit

Asserts whether the provided observable emits the expected values synchronously. toEmit takes an array of values to match against and expects them to deep equal the values in the correct order.

Accepts an optional callback to be called after the observable is activated. This is because values emitted into the observable before it’s passed to Jest will not be emitted into the assertion, unless it’s a Property.

expect(obs).toEmit([value(1), error(new Error('whoops!')), end()], () => {
  send(obs, [value(1), error(new Error('whoops!')), end()])
})

If obs is a Kefir.Property with a current value, the expected values should get the options object with current: true. Note that given how Properties work, only the last value is current.

send(obs, [value(1)])
send(obs, [value(2)])
expect(obs).to.emit([value(2, {current: true}), end()], () => {
  send(obs, [end()])
})

These rules also apply to toEmitInTime.

toEmitInTime

Asserts whether the provided emits the values correctly over time. Uses lolex behind the scenes to take over JavaScripts timers, allowing you to assert against the times the values are emitted. The expected value should be an array of tuples, where the first value is the time and the second is the value emitted.

const expected = [[0, value(1)], [10, error(new Error('whoops!'))], [20, end()]]

Accepts a callback which is passed both a simple tick function as well as the full lolex clock. tick advances the internal timer by the provided ms. clock is documented here.

expect(obs).toEmitInTime(expected, (tick, clock) => {
  send(obs, [value(1)])
  tick(10)
  send(obs, [error(new Error('whoops!'))])
  tick(10)
  send(obs, [end()])
})

toEmitInTime also accepts an optional configuration object after the callback. That object takes the following options:

• reverseSimultaneous: bool: Indicates whether callbacks scheduled for the same time should be called in reverse. This is an advanced use case to check if your implementation handles a common browser bug. See this issue for more information. This is handled correctly by Kefir’s built-in methods, so unless you’re using timers in your implementation, this mostly isn’t necessary.