spawk

node.js child_process.spawn mocking library

Spawk can be used to test modules that call spawn in isolation.

Note: This module does its best to implement platform specific behaviors of child_process.spawn(), anything that behaves differently is a bug.

Example

const spawk = require('spawk')
spawk.spawn('ls').exit(1).stdout('custom response')

const child = require('child_process').spawn('ls')

child here will be a mocked ChildProcess object that will exit with a status code of 1, and will receive the string custom response on its stdout interface.

By default, any calls to spawn that do not match an existing mock will pass through to the original spawn. See preventUnmatched below for more info on how to change this.

Each intercepted call will only be used once, so if you want to intercept multiple calls to the same command you need to call spawk.spawn for each call you want to be intercepted. They will be used in the order that they were created.

API

spawk

npm install spawk

const spawk = require('spawk')

spawk.spawn(command, arguments, options)

Intercept and mock a call to child_process.spawn. Returns a Interceptor object, see below for more info. Parameters are defined as follows:

• command

Command to intercept and mock. Can either be a string, a RegExp, or a function. The interceptor will mock a given call if the string matches exactly, or the RegExp matches, or the function returns true. The function will be passed three parameters: the command, args, and options passed to child_process.spawn. The function will be called under the context of the Interceptor, so you will have access to the methods and attributes described below.

• arguments

Optional arguments that must accompany the given command in order to be mocked. Can either be an array or a function. The interceptor will mock a given call if the array matches exactly, or if the function returns true. The function will be passed one parameter: the args passed to child_process.spawn. The function will be called under the context of the Interceptor, so you will have access to the methods and attributes described below.

• options

Optional options that must accompany the given command in order to be mocked. Can either be an object or a function. The interceptor will mock a given call if all of the attributes in these options match, or if the function returns true. If an object, only the attributes you give are matched, others do not affect whether or not it matches. If a function, it will be passed one parameter: the options passed to child_process.spawn. The function will be called under the context of the Interceptor, so you will have access to the methods and attributes described below.

When generating stdin/stdin/stdout streams for the interceptor, if the call to spawn specifies inherit for their modes they will not be created.

spawk.allowUnmatched()

Allow calls to child_process.spawn that do not match any interceptor to pass through to node's implementation. This is the default state.

spawk.preventUnmatched()

Allow calls to child_process.spawn that do not match any interceptor from passing through to node's implementation. An unmatched call will cause an exception to be thrown.

spawk.done()

Ensure that all configured interceptors have been called. If they have this will return true. If they have not this will throw an exception.

spawk.clean()

Remove any currently configured interceptors.

spawk.unload()

Unloads spawk from intercepting child_process.spawn calls completely. This also removes any currently configured interceptors.

spawk.load()

Loads spawk for intercepting child_process.spawn calls. This is called by default, you should only need to call this if you have previously called spawk.unload() for some reason.

Interceptor

const interceptor = spawk.spawn('ls')

All of the following methods can be chained together.

By default a interceptor will exit with a code of 0 with no signal, and nothing written to either stdout or stderr.

interceptor.called

Boolean that denotes whether or not this interceptor has been called yet

interceptor.description

Helpful string representation of the interceptor.

interceptor.calledWith

When the interceptor has been called, this will be an object that contains the command, args, and options that were actually called.

It will also contain an array with the stdio objects that the spawned process got, provided it was not called with inherit (aka if pipe was used). You can use this to assert for instance that certain things were written to the stdin of your spawned process.

stdio will be an array that contains [stdin, stdout, stderr].

interceptor.signals

Array containing any signals that the interceptor received via .kill()

interceptor.exit(code)

Tells the interceptor what status code to exit with. Defaults to 0.

This can be either a number or a function that returns a number. The function can also be async or return a Promise. The function will be called with this set to the interceptor.

Calling this will clear out any signal previously set with interceptor.signal

interceptor.signal(signal)

Tells the interceptor what signal to exit with. Defaults to null (exit with no signal).

This can be either a string or a function that returns a string. The function can also be async or return a Promise. The function will be called with this set to the interceptor.

Calling this will clear out any code previously set with interceptor.exit

interceptor.stdout(data)

Tells the interceptor what to write to stdout before exit.

This can be either a string, buffer, or a function that returns a string or buffer. The function can also be async or return a Promise. The function will be called with this set to the interceptor.

interceptor.stderr(data)

Tells the interceptor what to write to stderr before exit.

This can be either a string, buffer, or a function that returns a string or buffer. The function can also be async or return a Promise. The function will be called with this set to the interceptor.

interceptor.delay(ms)

Tells the interceptor to delay exiting for a given number of milliseconds.

interceptor.exitOnSignal(signal)

Tells the interceptor to delay exiting until it receives the given signal. Setting this will ignore any delay you have set. This will also be the signal that the interceptor exits with, unless you otherwise change it via interceptor.signal.

interceptor.spawnError(error)

Tells the interceptor to emit the given error object via the error event, instead of the normal spawn event. The interceptor will not emit the exit or close events in this case, nor will it set up any stdio objects. This can be combined with interceptor.delay to delay this error, or with interceptor.exitOnSignal to error when the given signal is received (replicating a process that can not be killed).

interceptor.stdoutEmit(eventName, [...args])

Tells the interceptor to emit a given event from stdout with any number of arguments.

interceptor.stderrEmit(eventName, [...args])

Tells the interceptor to emit a given event from stderr with any number of arguments.