Repository files navigation

rxjs-marbles is an RxJSmarble testing library that should be compatible with any test framework. It wraps the RxJSTestScheduler and provides methods similar to thehelper methods used theTestScheduler API.

It can be used withAVA,Jasmine,Jest,Mocha orTape in the browser or in Node and it supports CommonJS and ES module bundlers.

I created this package because I wanted to use RxJS marble tests in a number of projects and those projects used different test frameworks.

There are a number of marble testing packages available - including the Mocha-based implementation in RxJS itself - but I wanted something that was simple, didn't involve messing with globals andbeforeEach/afterEach functions and was consistent across test frameworks.

If you are looking for something similar, this might suit.

Install the package using NPM:

npm install rxjs-marbles --save-dev

If you're just getting started with marble testing, you might be interested in how I wasted some of my time by not carefully reading the manual:RxJS Marble Testing: RTFM.

In particular, you should read the RxJS documentation onmarble syntax andsynchronous assertion.

rxjs-marbles contains framework-specific import locations. If there is a location for the test framework that you are using, you should use the specific import. Doing so will ensure that you receive the best possible integration with your test framework.

For example, importing from"rxjs-marbles/jest" will ensure that Jest's matcher is used and the output for test failures will be much prettier.

Instead of passing your test function directly toit, pass it to the library'smarbles function, like this:

import{marbles}from"rxjs-marbles/mocha";import{map}from"rxjs/operators";describe("rxjs-marbles",()=>{it("should support marble tests",marbles(m=>{constsource=m.hot("--^-a-b-c-|");constsubs="^-------!";constexpected="--b-c-d-|";constdestination=source.pipe(map(value=>String.fromCharCode(value.charCodeAt(0)+1)));m.expect(destination).toBeObservable(expected);m.expect(source).toHaveSubscriptions(subs);}));});

To see howrxjs-marbles can be used with other test frameworks, see theexamples within the repository.

With AVA and Tape, the callback passed to themarbles function will receive an addional argument - the AVAExecutionContext or the TapeTest - which can be used to specify the number of assertions in the test plan. See the framework-specific examples for details.

In addition to themarbles function, the library exports acases function that can be used to reduce test boilerplate by specifying multiple cases for variations of a single test. The API is based on that ofjest-in-case, but also includes the marbles context.

Thecases implementation is framework-specific, so the import must specify the framework. For example, with Mocha, you would importcases and use it instead of theit function, like this:

import{cases}from"rxjs-marbles/mocha";import{map}from"rxjs/operators";describe("rxjs-marbles",()=>{cases("should support cases",(m,c)=>{constsource=m.hot(c.s);constdestination=source.pipe(map(value=>String.fromCharCode(value.charCodeAt(0)+1)));m.expect(destination).toBeObservable(c.e);},{"non-empty":{s:"-a-b-c-|",e:"-b-c-d-|"},"empty":{s:"-|",e:"-|"}});});

In RxJS version 6, arun method was added to theTestScheduler and when it's used, the scheduler's behaviour is significantly changed.

rxjs-marbles now defaults to using the scheduler'srun method. To use the scheduler's old behaviour, you can call theconfigure function, passing{ run: false }, like this:

import{configure}from"rxjs-marbles/mocha";const{ cases, marbles}=configure({run:false});

WARNING:bind is deprecated and can only be used withconfigure({ run: false }).

Sometimes, passing theTestScheduler instance to the code under test can be tedious. The context includes abind method that can be used to bind a scheduler'snow andschedule methods to those of the context'sTestScheduler.

bind can be passed specific scheduler instances or can be called with no arguments to bind RxJS'sanimationFrame,asap,async andqueue schedulers to the context'sTestScheduler.

For example:

it("should support binding non-test schedulers",marbles(m=>{m.bind();constsource=m.hot("--^-a-b-c-|");constsubs="^--------!";constexpected="---a-b-c-|";// Note that delay is not passed a scheduler:constdestination=source.delay(m.time("-|"));m.expect(destination).toBeObservable(expected);m.expect(source).toHaveSubscriptions(subs);}));

WARNING:reframe is deprecated and can only be used withconfigure({ run: false }).

The RxJSTestScheduler defaults to 10 virtual milliseconds per frame (each character in the diagram represents a frame) with a maximum of 750 virtual milliseconds for each test.

If the default is not suitable for your test, you can change it by calling the context'sreframe method, specifying the time per frame and the (optional) maximum time. Thereframe method must be called before any of thecold,flush,hot ortime methods are called.

Theexamples include tests that usereframe.

If the BDD syntax is something you really don't like, there are some alternative methods on theContext that are more terse:

constsource=m.hot("--^-a-b-c-|",values);constsubs="^-------!";constexpected=m.cold("--b-c-d-|",values);constdestination=source.map((value)=>value+1);m.equal(destination,expected);m.has(source,subs);

Therxjs-marbles API includes the following functions:

• configure
• marbles
• observe
• fakeSchedulers

interfaceConfiguration{assert?:(value:any,message:string)=>void;assertDeepEqual?:(a:any,b:any)=>void;frameworkMatcher?:boolean;run?:boolean;}functionconfigure(options:Configuration):{marbles:MarblesFunction};

Theconfigure method can be used to specify the assertion functions that are to be used. Calling it is optional; it's only necessary if particular assertion functions are to be used. It returns an object containing amarbles function that will use the specified configuration.

The default implementations simply perform the assertion and throw an error for failed assertions.

functionmarbles(test:(context:Context)=>any):()=>any;functionmarbles<T>(test:(context:Context,t:T)=>any):(t:T)=>any;

marbles is passed the test function, which it wraps, passing the wrapper to the test framework. When the test function is called, it is passed theContext - which contains methods that correspond to theTestSchedulerhelper methods:

interfaceContext{autoFlush:boolean;bind(...schedulers:IScheduler[]):void;cold<T=any>(marbles:string,values?:any,error?:any):ColdObservable<T>;configure(options:Configuration):void;equal<T=any>(actual:Observable<T>,expected:Observable<T>):void;equal<T=any>(actual:Observable<T>,expected:string,values?:{[key:string]:T},error?:any):void;equal<T=any>(actual:Observable<T>,subscription:string,expected:Observable<T>):void;equal<T=any>(actual:Observable<T>,subscription:string,expected:string,values?:{[key:string]:T},error?:any):void;expect<T=any>(actual:Observable<T>,subscription?:string):Expect<T>;flush():void;has<T=any>(actual:Observable<T>,expected:string|string[]):void;hot<T=any>(marbles:string,values?:any,error?:any):HotObservable<T>;reframe(timePerFrame:number,maxTime?:number):void;readonlyscheduler:TestScheduler;teardown():void;time(marbles:string):number;}interfaceExpect<T>{toBeObservable(expected:ColdObservable<T>|HotObservable<T>):void;toBeObservable(expected:string,values?:{[key:string]:T},error?:any):void;toHaveSubscriptions(expected:string|string[]):void;}

In Jasmine, Jest and Mocha, the test framework recognises asynchronous tests by their taking adone callback or returning a promise.

Theobserve helper can be useful when an observable cannot be tested using a marble test. Instead, expectations can be added to the observable stream and the observable can be returned from the test.

See theexamples for usage.

With Jest and Jasmine, the test framework can be configured to use its own concept of fake time. AVA, Mocha and Tape don't have built-in support for fake time, but the functionality can be added viasinon.useFakeTimers().

In some situations, testing asynchronous observables with marble tests can be awkward. Where testing with marble tests is too difficult, it's possible to test observables using the test framework's concept of fake time, but thenow method of theAsyncScheduler has to be patched. ThefakeSchedulers helper can be used to do this.

See theexamples for usage.

Also, I've written an article on thefakeSchedulers function:RxJS: Testing with Fake Time.