Registry / testing / rx-sandbox

rx-sandbox

JSON →
library2.0.5jsnpmunverified

RxSandbox is a dedicated testing utility for RxJS Observables, employing a Domain Specific Language (DSL) based on marble diagrams to simplify assertions over virtual time. The current stable version, 2.0.5, is designed specifically for RxJS 7.0.1 and newer, while earlier major versions (1.x) supported RxJS 6.x, and pre-1.x versions accommodated RxJS 5. The project is actively maintained, though its development cadence is primarily tied to upstream RxJS releases rather than continuous feature additions, as it's considered feature-complete. It differentiates itself from the core RxJS `TestScheduler` by offering an extended marble diagram DSL, requiring near-zero configuration, operating independently of specific test frameworks, and supporting flexible `TestMessage` creation for granular testing scenarios.

npm install rx-sandbox
INSTALL
IMPORT
SIG · RX-SANDBOX
R
rx-sandbox
testingjavascriptv2.0.5
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

createSandbox
import { createSandbox } from 'rx-sandbox';
const createSandbox = require('rx-sandbox');
RxSandbox is primarily designed for ES Modules. While `require` might function in some Node.js setups, using ES `import` is recommended for better compatibility with TypeScript and modern bundlers.
RxSandboxInstance
import type { RxSandboxInstance } from 'rx-sandbox';
Import the `RxSandboxInstance` type for strict TypeScript typing when declaring the return type of `createSandbox()`.
{ get, cold, hot, expectObservable, expectSubscriptions }
const { get, cold, hot, expectObservable, expectSubscriptions } = createSandbox();
These are the primary utility functions and assertion methods provided as properties on the object returned by the `createSandbox()` factory, not direct named exports from the package.

Demonstrates initializing `rx-sandbox` and using its `cold`, `hot`, `expectObservable`, and `expectSubscriptions` methods with marble diagrams to test RxJS operators and observable lifecycles.

import { createSandbox } from 'rx-sandbox'; import { map, take } from 'rxjs/operators'; function runRxSandboxTest() { // Initialize the sandbox, destructuring common utilities for convenience. const { get, cold, hot, expectObservable, expectSubscriptions } = createSandbox(); // Example 1: Testing a cold observable transformation // 'cold' creates an observable that starts emitting when subscribed. const source$ = cold('-a-b-c|', { a: 1, b: 2, c: 3 }); const mapped$ = source$.pipe(map(x => x * 10)); // 'expectObservable' asserts the output using marble syntax and a value map. expectObservable(mapped$).toBe('-A-B-C|', { A: 10, B: 20, C: 30 }); // Example 2: Testing a hot observable with subscription points and unsubscription // 'hot' creates an observable that is already active when subscribed. const hotSource$ = hot('--a--b--c--d|'); // 'sub' defines the subscription (^) and unsubscription (!) frames. const sub = '^----------!'; // Subscribes at frame 0, unsubscribes at frame 10 const result$ = hotSource$.pipe(take(3), map(x => x.toUpperCase())); // Assert the observable's output and verify its subscription behavior. expectObservable(result$, sub).toBe('--A--B--C|', { A: 'A', B: 'B', C: 'C' }); expectSubscriptions(hotSource$.subscriptions).toBe(sub); console.log('RxSandbox tests are defined. In a real test runner (e.g., Jest, Mocha),'); console.log('these assertions would automatically execute and report outcomes.'); } // Execute the test function. In a typical test suite, this would be within `it()` blocks. runRxSandboxTest();
Debug
Known issues
breakingVersion 2.0.0 and subsequent releases of `rx-sandbox` enforce compatibility exclusively with RxJS version 7.x. Attempting to use `rx-sandbox@2.x` with RxJS 6.x or older will lead to runtime errors due to significant API changes in RxJS.
fix
Ensure your project's `rxjs` dependency is `^7.0.1` or higher when using `rx-sandbox@2.x`. For projects still on RxJS 6.x, use `rx-sandbox@1.x`. For RxJS 5.x, refer to pre-1.x versions of `rx-sandbox`.
affects: >=2.0.0-beta.1
breakingStarting with `rx-sandbox@2.0.0-beta.1`, the library mandates an ES2015-compatible runtime environment. This may impact projects targeting older Node.js versions or browser environments without adequate transpilation.
fix
Upgrade your Node.js environment to a version supporting ES2015+ (e.g., Node.js 12 or newer). If targeting browsers, ensure your build process includes transpilation to ES2015+ or a compatible target.
affects: >=2.0.0-beta.1
gotcha`RxSandbox` implements its own extended marble diagram DSL and has specific semantics for virtual time progression that differ from the `TestScheduler` provided in RxJS core. Direct mental mapping between the two can lead to unexpected test results.
fix
Consult the `rx-sandbox` documentation for its precise marble diagram token definitions, particularly if you are accustomed to RxJS's native `TestScheduler` or migrating existing tests.
affects: *
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'pipe') or similar 'X is not a function' errors related to RxJS operators.
This typically occurs when `rx-sandbox@2.x` is used with an incompatible RxJS version (e.g., RxJS 6.x) or when RxJS operators are imported incorrectly (e.g., trying to import `of` from `rxjs/operators` in RxJS 7).
fix
Verify that your `rxjs` peer dependency (`^7.x`) matches `rx-sandbox@2.x`. Ensure correct RxJS import paths; for RxJS 7, many creation functions like `of` are direct exports from `rxjs`, while operators like `map` are from `rxjs/operators`.
SyntaxError: Cannot use import statement outside a module
Attempting to run `rx-sandbox` code (which is published as ES Modules) in a Node.js environment configured for CommonJS without appropriate transpilation or Node.js module settings.
fix
To resolve this, configure your `package.json` with `"type": "module"`, use `.mjs` file extensions, or set up a transpiler (like Babel or TypeScript) to convert ES Modules to CommonJS if targeting a legacy Node.js environment. For direct execution of TypeScript, `ts-node` can often handle this.
Error: Expected marble diagram 'xyz' to match 'abc'
A mismatch between the expected marble diagram string and the actual one generated by the observable under test, or an incorrect `value` map for the marble diagram tokens.
fix
Carefully review both the expected marble diagram string and the actual observable's behavior. Ensure the `value` object passed to `toBe()` or `get()` correctly maps the emitted characters to their corresponding values, and that timing (dashes, parentheses, time progression) is accurate.
Upgrade
Version history
2.0.5latest on npm
Audit
Dependencies
rxjsrequiredThis is a peer dependency, crucial for defining and manipulating observable streams within tests.
Agent activity
2 hits · last 30 days
node
2
Resources
rx-sandbox — npm install rx-sandbox · libregistry