rxjs-marbles

library7.0.1jsnpmunverified

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.

testing

npm install rxjs-marbles

github ↗package ↗

INSTALL

IMPORT

SIG · RXJS-MARBLES

rxjs-marbles

testingjavascriptv7.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

marbles

✓ import { marbles } from 'rxjs-marbles/mocha';

✗ import { marbles } from 'rxjs-marbles';

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

✓ import { map } from 'rxjs/operators';

✗ import { map } from 'rxjs';

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.

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); })); });

Debug

Known issues

breakingEnsure 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.

affects: >=7.0.0

gotchaFailing 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';`.

affects: >=1.0.0

gotchaA 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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'run')

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

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

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).

Upgrade

Version history

7.0.1latest on npm

Audit

Dependencies

rxjsrequiredRuntime peer dependency for RxJS observable stream manipulation and `TestScheduler` functionality.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/cartant/rxjs-marbles ↗

packagehttps://www.npmjs.com/package/rxjs-marbles ↗