RxJS Marble Testing

7.0.1 · active · verified Sun Apr 19

rxjs-marbles is a flexible and framework-agnostic library designed for conducting marble tests in RxJS applications. It provides a consistent interface for testing observable streams across various JavaScript testing frameworks, including AVA, Jasmine, Jest, Mocha, and Tape, in both browser and Node.js environments. The library currently targets RxJS version 7.x, as indicated by its peer dependency on `rxjs: ^7.0.0`. Its key differentiator lies in abstracting away framework-specific boilerplate like global setups or `beforeEach`/`afterEach` hooks, allowing developers to focus solely on the marble diagrams. It wraps RxJS's internal `TestScheduler` and exposes similar helper methods, simplifying the process of defining hot/cold observables, subscriptions, and expected outputs using the familiar marble syntax. While no explicit release cadence is stated, the package is actively maintained, with version 7.0.1 being the current stable release. The library ships with TypeScript types, facilitating its use in TypeScript projects.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'run')
```
cause The test function was not correctly wrapped by the `marbles` helper function, meaning no `TestScheduler` instance ('m' argument) was provided.

fix Ensure your test callback is passed to `marbles`, like `it('should work', marbles(m => { ... }));`.
```
Expected true to be false
```
cause A common assertion error indicating that the expected marble diagram does not match the actual observable output.

fix Carefully re-examine your source, subscription, and expected marble diagrams. Use `m.log('label', observable)` to debug and inspect the actual emissions of your observables during the test run.
```
TypeError: (0 , rxjs_operators_1.map) is not a function
```
cause This error typically occurs when RxJS operators are imported incorrectly, often in CommonJS environments or when using incompatible RxJS versions with your module resolution settings.

fix Verify that RxJS operators are imported from `rxjs/operators` (e.g., `import { map } from 'rxjs/operators';`). If using CommonJS, ensure your build setup correctly transpires ESM imports, or use `const { map } = require('rxjs/operators');` if targeting CJS directly (though ESM imports are preferred for modern RxJS).

Warnings

breaking Ensure your `rxjs` version is compatible with the `rxjs-marbles` peer dependency. `rxjs-marbles@7.x` requires `rxjs@^7.0.0`. Mismatched versions can lead to `TestScheduler` API incompatibilities and runtime errors.
Fix: Install a compatible `rxjs` version (e.g., `npm install rxjs@^7.0.0 --save-dev`) or use an `rxjs-marbles` version that targets your existing `rxjs` installation.
gotcha Failing to use framework-specific import paths (e.g., `rxjs-marbles/jest` instead of `rxjs-marbles`) results in less optimal test integration, potentially poorer error reporting, and missing framework-specific matchers.
Fix: Always import `marbles` from the path specific to your test framework, such as `import { marbles } from 'rxjs-marbles/mocha';` or `import { marbles } from 'rxjs-marbles/jest';`.
gotcha A common pitfall is misunderstanding the core RxJS marble testing syntax, especially synchronous assertion rules and frame timing. `rxjs-marbles` acts as a wrapper for RxJS's `TestScheduler`, so its behavior is dictated by RxJS's underlying marble test mechanics.
Fix: Thoroughly review the official RxJS documentation on 'marble syntax' and 'synchronous assertion' to grasp the intricacies of marble diagram interpretation and test execution.

Install

npm install rxjs-marbles npm
yarn add rxjs-marbles yarn
pnpm add rxjs-marbles pnpm

Imports

marbles
wrong:
```
import { marbles } from 'rxjs-marbles';
```
correct:
```
import { marbles } from 'rxjs-marbles/mocha';
```
Always use framework-specific import paths (e.g., `/jest`, `/ava`) for optimal integration and clearer error reporting. The generic path might work but is not recommended.
map
wrong:
```
import { map } from 'rxjs';
```
correct:
```
import { map } from 'rxjs/operators';
```
RxJS operators like `map` are imported from `rxjs/operators` for tree-shaking and consistency with modern RxJS practices.
TestScheduler
```
import { TestScheduler } from 'rxjs/testing';
```
Direct import of `TestScheduler` is rarely needed as `rxjs-marbles` abstracts it. This is primarily for type-checking or advanced direct interaction with RxJS's testing utilities.

Quickstart

Demonstrates a basic marble test using `rxjs-marbles` with Mocha. It defines a hot observable, applies a transformation, and asserts the output against a marble diagram.

import { marbles } from "rxjs-marbles/mocha";
import { map } from "rxjs/operators";
import { Observable } from 'rxjs';

describe("rxjs-marbles basic test", () => {

    it("should map values from a hot observable", marbles(m => {
        // Define a hot observable source using marble syntax
        const source =  m.hot("--^-a-b-c-|');
        // Define the subscription timeframe
        const subs =            "^-------!";
        // Define the expected output after mapping
        const expected =        "--b-c-d-|';

        // Apply the map operator to the source observable
        const destination: Observable<string> = source.pipe(
            map(value => String.fromCharCode(value.charCodeAt(0) + 1))
        );

        // Assert that the destination observable matches the expected marble diagram
        m.expect(destination).toBeObservable(expected);
        // Assert that the source was subscribed to during the defined 'subs' timeframe
        m.expect(source).toHaveSubscriptions(subs);
    }));
});

view raw JSON →