Gallinago is designed to assist with the running and testing of NodeJS CLIs and binaries in a simple and controlled way. It is best used in combination with fixtures and pre-scaffolded directories such that you can reproduce the various configuration and folder structures your CLI may need to support for its users and then validate the output. Perfect for testing!
Often times while creating CLIs, it can be helpful to test the final output given the various configurations of the CLI. Running a CLI using config files and user files will all likely (and hopefully) result in idempotent output that can be validated over and over. With a testing framework like mocha, you could use Gallinago to verify that output to validate things like:
Use npm or your favorite package manager to install Gallinago as a (dev) dependency.
$ npm install gallinago --dev
To use Gallinago, you will just need two things
import path from 'path';
import { Runner } = from 'gallinago';
import { fileURLToPath, URL } from 'url';
const runner = new Runner();
const cliPath = fileURLToPath(new URL('./path/to/your/cli.js', import.meta.url)); // required
const buildDir = fileURLToPath(new URL('./build', import.meta.url)); // required
// this will also create the directory as well
runner.setup(buildDir);
// runs your CLI
// use the second param to pass any args
runner.runCommand(cliPath);
// teardown buildDir
runner.teardown();
You can optionally await
these methods as well, depending on your needs.
See our tests to see Gallinago in action!
The Runner
constructor returns a new instance of Runner
.
import { Runner } from 'gallinago';
const runner = new Runner(); // pass true to the constructor to enable stdout
Runner
takes two boolean flags (true
|false
)
true
to have the Runner log to stdout
true
and any node
flags passed to the parent process will be made available to the child processRunner.setup
initializes a directory for your CLI to be run in. Returns a Promise
.
runner.setup(__dirname);
Optionally, you can provide "setup" files if you want to copy additional files into the target directory, say from _nodemodules or a fixtures folder. You can provide these files as an array of objects.
source
: path of the file to copydestination
: path of where to copy the file torunner.setup(__dirname, [{
source: path.join(process.cwd(), 'node_modules/@webcomponents/webcomponentsjs/webcomponents-bundle.js'),
destination: path.join(__dirname, 'build', 'webcomponents-bundle.js')
}]);
Runner.runCommand
runs the script provided to Gallinago against the directory provided in Runner.setup
. Use the second param to pass any args to your CLI. Returns a Promise
.
runner.runCommand(
'/path/to/cli.js',
'--version'
);
runCommand
additionally takes an options object as the third param. With it you can further customize the runner:
runner.runCommand(
'/path/to/cli.js',
'--version',
{ async: true }
);
async
- By default runCommand
runs synchronously using Node's spawnSync
, which will block until the command completes With async: true
, this will now use spawn
, which is a better for use cases like starting a web server where you don't want to block the event loop.Runner.teardown
deletes any setupFiles
provided in Runner.setup
. Returns a Promise
.
runner.teardown();
You can pass additional files or directories to teardown
to have gallinago delete those too.
runner.teardown([
path.join(__dirname, 'build'),
path.join(__dirname, 'fixtures'),
.
.
.
]);
In certain circumstances, the command (process) you are running may do a couple things:
resolve()
the on.close
event callback)This isn't an issue per se, but if the (child) process doesn't stop, it will prevent the current (parent) process from completing. The most common case for something like this to happen is when starting a (web) server. Servers don't usually stop unless told to, usually by killing their process manually using something like PM2, or if in a shell, using CTR+C on the keyboard.
To support this in Gallinago, you can use Runner.stopCommand
to kill any and all processes associated with your runCommand
.
runner.stopCommand();
Note: When used with something like mocha, you'll need to use a
setTimeout
to work around the hung process and still advance the parent Mocha process. See our spec for this test case for a complete example.