package
Integration testing for CLI applications
npm install first-baseGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Estimated unpacked size across 6 packages.
110.5 kB
Includes dependencies.
4 direct · 2 outdated
^3.2.2
4.0.1
^5.0.0
7.2.0
^1.0.0
1.0.0
^1.2.0-beta.3
1.2.0-beta.18
first-baseIntegration testing for CLI applications.
const { spawn } = require("first-base");
test("something", async () => {
const run = spawn("node", ["-i"]); // launch node REPL
await run.outputContains("> "); // wait until `> ` is logged
run.write("2 + 2\n"); // enter `2 + 2` and press enter
await run.outputContains("4"); // wait until `4` is logged
run.kill();
spawn(command: string, args?: Array<string>, options?: Object) => RunContextargs and options are the same as child_process.spawn.
Returns a RunContext object; see below.
RunContext#resultAn object with the following properties on it:
stdout (string): All the data the process has written to STDOUT so farstderr (string): All the data the process has written to STDERR so farcode (number | null): Exit status code, if the process has finishederror (null | Error): If the process errored out, this is the ErrorNOTE: If spawned with option
pty: true,RunContext#resulthas a singleoutput: stringproperty instead of bothstdoutandstderr.
This object gets updated over time as the process runs.
const run = spawn("ls", { cwd: __dirname });
console.log(run.result); // { stdout: '', stderr: '', code: null, error: null }
await run.completion;
console.log(run.result); // { stdout: 'README.md\npackage.json\nindex.js\n', stderr: '', code: 0, error: null }RunContext#completionA Promise that gets resolved when the process completes. You can await it in your tests.
const run = spawn("ls", { cwd: __dirname });
await run.completion; // Waits until the `ls` process finishesRunContext#outputContains(value: string | RegExp) => Promise<void>Returns a Promise that will resolve once the process's output (combined STDOUT/STDERR) contains either the specified string or matches the specified RegExp. Ignores ANSI control characters.
const run = spawn("node", ["-i"]); // start Node.js REPL
await run.outputContains("> "); // Wait until prompt appearsRunContext#clearOutputContainsBuffer()Clears the buffer of "seen" output as far as the outputContains method is concerned. Useful if the output already contains the specified value, and you want to wait until it appears a second time.
const run = spawn("node", ["-i"]); // start Node.js REPL
await run.outputContains("> "); // Wait until prompt appears
run.write("2 + 2\n"); // Write 2 + 2 then press enter
run.clearOutputContainsBuffer();
await run.outputContains("> "); // Wait until prompt appears a second time. If we hadn't cleared the buffer, this would resolve immediately.RunContext#write(data: string | Buffer)Write some data into the process's STDIN stream.
const run = spawn("node", ["-i"]); // start Node.js REPL
await run.outputContains("> "); // Wait until prompt appears
run.write("2 + 2\n"); // Write 2 + 2 then press enter
await run.outputContains("4");RunContext#close(stream: 'stdin' | 'stdout' | 'stderr')Close one of the processes's associated stdio streams.
NOTE: If spawned with option
pty: true,RunContext#closeis not present.
const run = spawn("node", ["-i"]); // start Node.js REPL
await run.outputContains("> "); // Wait until prompt appears
run.close("stdin"); // Like pressing Ctrl+D; sends EOF
await run.completion;RunContext#kill(signal?: string)Kills the process. If no signal is specified, it defaults to "SIGINT".
const run = spawn("node", ["-i"]);
run.kill(); // Kill with SIGINT
// OR:
run.kill("SIGTERM"); // Kill with SIGTERM
run.kill("SIGKILL"); // Kill with SIGKILL
// etcRunContext#cleanResult()A function which returns a new object with the same shape as RunContext#result but with its stdout/stderr/output passed through the sanitizers Array (see below).
Unlike result, this object does NOT get updated over time as the process runs.
sanitizers: Array<(string) => string>An array of functions that will be run on stdout/stderr when calling
RunContext#cleanResult().
By default, it contains 5 functions, which are run in order:
stripAnsi: Removes ANSI control charactersreplaceRootDir: Replaces eg /home/suchipi/Code/first-base/src/index.js with <rootDir>/src/index.js
replaceRootDir.cache..git or .hgpackage-lock.json, .gitignore or .hgignore,package.json or README.mdreplaceCwd: Replaces the current working directory with <cwd>collapseStackTrace: For Node.JS-style stack traces, replaces the long chain of "at ..." lines with a single "at somewhere" lineomitThrowLineNumber: For Node.JS error source display, removes the line numberYou can remove them or replace them or add to them by mutating the sanitizers Array.
allInflightRunContexts: Set<RunContext>All runs that have been spawned which haven't reached completion (see RunContext#completion).
It may be beneficial to clean these up in a test timeout handler or etc.
MIT
The only things that changed between 1.x and 2.0 are:
error property of a RunContext changed from boolean to null | ErrorRunContext.write and RunContext.kill were narrowed slightly. The runtime behavior of those methods didn't change.RunContext.debug() is deprecated (but not removed). Use spawn option debug: true instead.RunContext.debug() is removed. Use spawn option debug: true instead.pty: true now has one output: string property instead of a fake stdout: string and always-empty stderr: string.
.stdout is now written to .output. stderr was always empty for pty children because of how node-pty works.stdout and stderr strings like always.