Unit Testing Tools for Most.js
This is a library to make unit testing of Most.js streams easier.
Though I expect to include more in the future, the most important (and currently only) tool provided is a stream runner utilizing a virtual timer with which you can test your streams on your own terms, rather than being subject to the unpredictability and imprecision of the OS timer. Being able to test with single-millisecond granularity can make your tests clearer and more concise as well.
Special thanks to @RamIdeas for testing and contributing fixes and enhancements to the library.
Installation
npm install --save-dev most-test
Stream Runner
Testing a stream using the virtual timer is very straightforward. Simply import the run
function from most-test
and use it instead of stream.observe
. Call tick()
or tick(interval)
to advance time forward by either 1 millisecond (default) or a custom interval. The function returns a promise containing a summary of the events that occurred during that time interval. To advance time again, simply call tick(interval?)
again, returning the promise so that it resolves as the next step in the promise chain.
API
type Stream: most.Stream
type Time: Number
type Interval: Number
run: (stream:Stream) => BasicTestEnvironment
type BasicTestEnvironment: {
tick: (min?:Interval) => Promise<Result>
now: Time,
results: [Result]
}
type Result: {
events: Array,
end?: true|A,
error?: Error
}
The tick()
method advances the timer by the specified interval and returns a promise for the events that occurred during that interval.
A Result
object always contains an events
property, which is an array of zero or more values that were emitted by the stream during the elapsed interval. If the stream completed, it'll also have an end
property which will have the completion value emitted with the end
event, or true
if no completion value was emitted. If a completion value was provided, the end
property will be an object with a value
property; e.g. {value: 'x'}
A BasicTestEnvironment
object also contains a results
property (getter only), which is an array of all of the Result
objects created as a result of each tick()
call.
Example
This example uses Mocha's BDD API. You should use whatever you prefer.
;; ;
As of version 1.2.0:
As of version 1.2.0, run(stream)
returns a BasicTestEnvironment
which is a wrapper around TestEnvironment
.
run(stream)
works best when instantiating the stream under test within the test itself.
If you are testing a stream instantiated externally of your tests (eg. an imported module), the environment created when running this stream can remain associated with it and, therefore, future tests on the same stream can have unpredictable results.
In this situation, you should create a TestEnvironment
and share it amongst your tests. Remembering to .reset()
the environment after each test.
const env = ; // returns a promise - either return it to `afterEach` or `await` it; ; ;
tick()
initiates a promise chain but returns the TestEnvironment
instance. Subsequent calls to collect()
wait for this promise and then return a Result
.
collect(stream)
implicitly calls track(stream)
- this helps avoid repetition. If collect()
isn't being called within the same frame as tick()
, you'll need to call track()
explicitly, upfront.
;