spawk
v1.8.2
Published
child_process.spawn mocking library
Downloads
18,817
Maintainers
Readme
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.