Skip to content

arielshaqed/kurkar

Repository files navigation

Build status on Cirrus Build status on GitHub Actions

Kurkar: Ava macros to test RxJS

Kurkar helps you test RxJS operators and pipelines with marbles using Ava. Ava macros let you write concise tests.

Install

npm install --save-dev kurkar

Basic usage

import test from 'ava';
import marbles from 'kurkar';

test('observable', marbles, (_t, _sched, helpers) => {
  const letters = 'the quick brown fox jumps over the lazy dog|';
  const source$ = helpers.hot(letters);
  helpers.expectObservable(source$).toBe(letters);
});

Kurkar provides an Ava test macro to easily set up RxJS tests in Ava. Include the macro function marbles before the test function to hook up an RxJS TestScheduler to the Ava execution context "t". The test function will be run inside a test scheduler, with these parameters:

  • t: Ava execution context for this test.
  • sched: RxJS TestScheduler running this test. Use when you need to pass a scheduler argument into some operators.
  • helpers: Helper functions created by TestScheduler.run for easily creating and comparing Observables.

TestScheduler runs synchronously, so the test function is not async.

The marbles macro uses t.deepEqual to compare actual and expected results. Pass a different comparison function to withEquals to generate other versions of the macro. marbles is just

const marbles = withEquals((t, a, e) => t.deepEqual(a, e));

TypeScript support

Kurkar fully supports TypeScript types and exports useful types. You do not need to install additional @types to enjoy TypeScript.

Here's a typed version of the above test:

import test from 'ava';
import marbles, { withEquals, ExecutionContext, TestScheduler, RunHelpers } from 'kurkar';

test('observable', marbles, (_t: ExecutionContext, _sched: TestScheduler, helpers: RunHelpers) => {
  const letters = 'the quick brown fox jumps over the lazy dog|';
  const source$ = helpers.hot(letters);
  helpers.expectObservable(source$).toBe(letters);
});

Due to current limitations with Ava types, TypeScript language servers currently cannot always deduce the types of the test function parameters.

FAQ

Why another Ava RxJS marbles library?

Because it provides an Ava test macro, Kurkar removes the most boilerplate from your tests. It is native TypeScript and can provide exact type-checking.

Why the name?

"Kurkar" ("כורכר") is a soft middle-eastern sandstone -- a very different rock from marble.

What are all these other names?

  • Ava: A JavaScript and TypeScript test runner.
  • RxJS: A library for composing asynchronous and event-based programs by using observable sequences.
  • Marbles: Diagram-based testing of RxJS operators and pipelines.

Build Status