jest-marbles
Version:
Marble testing helpers library for RxJs and Jest
244 lines (204 loc) • 8.29 kB
Markdown
# jest-marbles
[](https://badge.fury.io/js/jest-marbles)   [](https://conventionalcommits.org)
A set of helper functions and Jest matchers for RxJs marble testing.
This library will help you to test your reactive code in easy and clear way.
# Features
- Typescript
- Marblized error messages
# Prerequisites
- Jest
- RxJs
- Familiarity with [marbles syntax](https://rxjs.dev/guide/testing/marble-testing#marble-syntax)
# v4 migration (run mode)
v4 runs rxjs's `TestScheduler` in **run mode**:
- **Frames are 1ms each (was 10).** `time('--|')` now returns `2`, not `20`.
Re-baseline any hard-coded frame numbers.
- **Marble diagrams are unchanged** — `cold('--a--b|')` vs `cold('--a--b|')`
still passes; both sides shift by the same factor.
- **`TestScheduler.frameTimeFactor` is no longer honored.** Express durations
with time-progression syntax: `cold('a 250ms b|')`.
- **Time operators use real virtual time.** For example, `debounceTime(250)` on
`cold('a 250ms b|')` yields `cold('250ms a 1ms (b|)')` — `a` debounces out
at 250ms and `b` flushes on completion 1ms later.
- **New `marbleTest`** for tests that need `animate()`, or that exercise
operators using RxJS's default scheduler (`delay`, `timer`, `interval`,
`debounceTime`, …) so they resolve against virtual time. Note: it virtualizes
RxJS's own schedulers, **not** the global `setTimeout`/`Date.now` — raw calls
to those in code under test still run in real time.
```js
it('drives animationFrames', marbleTest(() => {
animate('--x--x');
expect(source$).toBeObservable(cold('--a--(b|)'));
}));
```
# Usage
For RxJs 7:
```sh
npm i jest-marbles@latest -D
```
For RxJs 6:
```sh
npm i jest-marbles@2 -D
```
For RxJs 5:
```sh
npm i jest-marbles@1 -D
```
In the test file:
```js
import { cold, hot, time, schedule, marbleTest, animate } from 'jest-marbles';
```
Inside the test:
```js
expect(stream).toBeObservable(expected);
expect(stream).toBeMarble(marbleString);
expect(stream).toHaveSubscriptions(marbleString);
expect(stream).toHaveSubscriptions(marbleStringsArray);
expect(stream).toHaveNoSubscriptions();
expect(stream).toSatisfyOnFlush(() => {
expect(someMock).toHaveBeenCalled();
})
```
# Examples
## toBeObservable
Verifies that the resulting stream emits certain values at certain time frames
```js
it('Should merge two hot observables and start emitting from the subscription point', () => {
const e1 = hot('----a--^--b-------c--|', {a: 0});
const e2 = hot(' ---d-^--e---------f-----|', {a: 0});
const expected = cold('---(be)----c-f-----|', {a: 0});
expect(e1.pipe(merge(e2))).toBeObservable(expected);
});
```
Sample output when the test fails (if change the expected result to `'-d--(be)----c-f-----|'`):
```
Expected notifications to be:
"-d--(be)----c-f-----|"
But got:
"---(be)----c-f-----|"
```
## toBeMarble
Same as `toBeObservable` but receives marble string instead
```js
it('Should concatenate two cold observables into single cold observable', () => {
const a = cold('-a-|');
const b = cold('-b-|');
const expected = '-a--b-|';
expect(a.pipe(concat(b))).toBeMarble(expected);
});
```
## toHaveSubscriptions
Verifies that the observable was subscribed in the provided time frames.
Useful, for example, when you want to verify that particular `switchMap` worked as expected:
```js
it('Should figure out single subscription points', () => {
const x = cold(' --a---b---c--|');
const xsubs = ' ------^-------!';
const y = cold(' ---d--e---f---|');
const ysubs = ' --------------^-------------!';
const e1 = hot(' ------x-------y------|', { x, y });
const expected = cold('--------a---b----d--e---f---|');
expect(e1.pipe(switchAll())).toBeObservable(expected);
expect(x).toHaveSubscriptions(xsubs);
expect(y).toHaveSubscriptions(ysubs);
});
```
The matcher can also accept multiple subscription marbles:
```js
it('Should figure out multiple subscription points', () => {
const x = cold(' --a---b---c--|');
const y = cold(' ----x---x|', {x});
const ySubscription1 = ' ----^---!';
// '--a---b---c--|'
const ySubscription2 = ' --------^------------!';
const expectedY = cold(' ------a---a---b---c--|');
const z = cold(' -x|', {x});
// '--a---b---c--|'
const zSubscription = ' -^------------!';
const expectedZ = cold(' ---a---b---c--|');
expect(y.pipe(switchAll())).toBeObservable(expectedY);
expect(z.pipe(switchAll())).toBeObservable(expectedZ);
expect(x).toHaveSubscriptions([ySubscription1, ySubscription2, zSubscription]);
});
```
Sample output when the test fails (if change `ySubscription1` to `'-----------------^---!'`):
```
Expected observable to have the following subscription points:
["-----------------^---!", "--------^------------!", "-^------------!"]
But got:
["-^------------!", "----^---!", "--------^------------!"]
```
## toHaveNoSubscriptions
Verifies that the observable was not subscribed during the test.
Especially useful when you want to verify that certain chain was not called due to an error:
```js
it('Should verify that switchMap was not performed due to an error', () => {
const x = cold('--a---b---c--|');
const y = cold('---#-x--', {x});
const result = y.pipe(switchAll());
expect(result).toBeMarble('---#');
expect(x).toHaveNoSubscriptions();
});
```
Sample output when the test fails (if remove error and change the expected marble to `'------a---b---c--|'`):
```
Expected observable to have no subscription points
But got:
["----^------------!"]
```
## toSatisfyOnFlush
Allows you to assert on certain side effects/conditions that should be satisfied when the observable has been flushed (finished)
```js
it('should verify mock has been called', () => {
const mock = jest.fn();
const stream$ = cold('blah|').pipe(tap(mock));
expect(stream$).toSatisfyOnFlush(() => {
expect(mock).toHaveBeenCalledTimes(4);
});
})
```
## schedule
Allows you to schedule task on specified frame
```js
it('should verify subject values', () => {
const source = new Subject();
const expected = cold('ab');
schedule(() => source.next('a'), 1);
schedule(() => source.next('b'), 2);
expect(source).toBeObservable(expected);
});
```
## time-progression syntax
Use `Nms`, `Ns`, or `Nm` inside a marble string to express large durations without drawing every frame:
```js
it('debounces emissions', marbleTest(() => {
const src = cold('a 250ms b|');
expect(src.pipe(debounceTime(250))).toBeObservable(cold('250ms a 1ms (b|)'));
}));
```
## marbleTest
Wraps a test body in a real `TestScheduler.run()` context. Use this when you need `animate()`, or when the code under test uses operators backed by RxJS's default scheduler (`delay`, `timer`, `interval`, `debounceTime`, …) and you want them to resolve against virtual time. It virtualizes RxJS's schedulers only — not the global `setTimeout`/`Date.now`. Pass the return value directly to `it`:
```js
it(
'runs assertions inside a real run() context',
marbleTest(() => {
const src = cold('a 250ms b|');
expect(src.pipe(debounceTime(250))).toBeObservable(cold('250ms a 1ms (b|)'));
})
);
```
## animate
Only valid inside `marbleTest`. Drives `animationFrames`-based timing by scheduling virtual animation-frame ticks at the positions marked in the marble string:
```js
it(
'drives animationFrames-based timing',
marbleTest(() => {
animate('--x--x');
const src = animationFrames().pipe(
map(({ elapsed }) => elapsed),
take(2)
);
expect(src).toBeObservable(cold('--a--(b|)', { a: 2, b: 5 }));
})
);
```