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.
Usage
const run = spawn("node", ["-i"]); // start Node.js REPLawait run.outputContains("> "); // Wait until prompt appears
RunContext#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.
Usage
const run = spawn("node", ["-i"]); // start Node.js REPLawait run.outputContains("> "); // Wait until prompt appearsrun.write("2 + 2\n"); // Write 2 + 2 then press enterrun.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.
Usage
const run = spawn("node", ["-i"]); // start Node.js REPLawait run.outputContains("> "); // Wait until prompt appearsrun.write("2 + 2\n"); // Write 2 + 2 then press enterawait run.outputContains("4");
Close one of the processes's associated stdio streams.
NOTE: If spawned with option pty: true, RunContext#close is not present.
Usage
const run = spawn("node", ["-i"]); // start Node.js REPLawait run.outputContains("> "); // Wait until prompt appearsrun.close("stdin"); // Like pressing Ctrl+D; sends EOFawait run.completion;
RunContext#kill(signal?: string)
Kills the process. If no signal is specified, it defaults to "SIGINT".
Usage
const run = spawn("node", ["-i"]);run.kill(); // Kill with SIGINT// OR:run.kill("SIGTERM"); // Kill with SIGTERMrun.kill("SIGKILL"); // Kill with SIGKILL// etc
RunContext#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 characters
replaceRootDir: Replaces eg /home/suchipi/Code/first-base/src/index.js with <rootDir>/src/index.js
This function searches upwards for the root dir using a heuristic, and caches results in the {@link Map} replaceRootDir.cache.
The heuristic is:
Look upwards for a folder containing .git or .hg
if none is found, look upwards for a folder containing package-lock.json, .gitignore or .hgignore,
if none is found, look upwards for a folder containing package.json or README.md
if none is found, consider the present working directory to be the root dir.
replaceCwd: 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" line
omitThrowLineNumber: For Node.JS error source display, removes the line number
You 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.
License
MIT
Upgrading from 1.x to 2.x
The only things that changed between 1.x and 2.0 are:
The error property of a RunContext changed from boolean to null | Error
We switched node-pty fork to a prebuilt one instead of an install-time compiled node-gyp one, which has the side-effect that we only support the following platforms:
Linux arm64 and x86_64
macOS arm64 and x86_64
Windows arm64 and x86_64
Upgrading from 2.x to 3.x
The type definitions for RunContext.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.
Upgrading from 3.x to 4.x
RunContext.debug() is removed. Use spawn option debug: true instead.
The RunContext.result of children spawned with option pty: true now has one output: string property instead of a fake stdout: string and always-empty stderr: string.
In other words, stuff that was being written to .stdout is now written to .output. stderr was always empty for pty children because of how node-pty works.
Non-pty children still have distinct stdout and stderr strings like always.
For pty children, the "close" method which was a no-op on pty children has been removed.
Non-pty children still have the "close" method.
For non-pty children, RunContext.completion now doesn't resolve until both the "exit" AND "close" event have been fired.
Previously it fired when the "close" event was fired, which was usually after "exit".
A pty child only has one distinct exit event, which is when its completion promise resolves. Same as before.
For non-pty children, RunContext.completion now rejects when the "error" event is fired.
Previously, RunContext.completion always resolved, even if RunContext.error was non-null.