observable-process

ObservableProcess

ObservableProcess decorates the low-level Node.JS ChildProcess model with functionality to observe the behavior of processes more conveniently. In particular:

• easier access to the complete textual content of the stdout and stderr streams
• augments stdout and stderr with methods to search for textual content
• create a new output stream that combines stdout and stderr
• await the process end
• easier access to the process exit code
• signals whether the process ended naturally or was manually terminated

This is useful for example when testing the terminal output of applications. Executing long-running processes through ObservableProcess will cause high memory consumption because it stores all the terminal output in RAM.

Setup

Add this library to your code base:

$ npm install observable-process

Load this library into your JavaScript code:

const { createObservableProcess } = require("observable-process")

– or –

import { createObservableProcess } from "observable-process"

Starting processes

The best way to provide the command to run is in the form of an argv array:

const observable = createObservableProcess(["node", "server.js"])

You can also provide the full command line to run as a string:

const observable = createObservableProcess("node server.js")

By default, the process runs in the current directory. To set the different working directory for the subprocess:

const observable = createObservableProcess("node server.js", { cwd: "~/tmp" })

You can provide custom environment variables for the process:

const observable = createObservableProcess("node server.js", {
  env: {
    foo: "bar",
    PATH: process.env.PATH
  }
})

Without a custom env parameter, ObservableProcess uses the environment variables from the parent process.

Reading output from the process

The stdout and stderr variables of an ObservableProcess behave like normal readable streams and provide extra functionality to access and search their content.

// normal access to STDOUT
observable.stdout.on("data", function() {
  // do something here
})

// get all content from STDOUT as a string
const text = observable.stdout.fullText()

// wait for text to appear in STDOUT
await observable.stdout.waitForText("server is online")

// wait for a regex on STDOUT
const port = await observable.stdout.waitForRegex(/running at port \d+./)
// => "running at port 3000."

Comparable functionality is available for STDERR. ObservableProcess also creates a new output stream with the combined content of STDOUT and STDERR:

observable.output.on("data", function(data) {
  // do something here
})
const text = observable.output.fullText()
await observable.output.waitForText("server is online")
const port = await observable.output.waitForRegex(/running at port \d+./)

Sending input to the process

ObservableProcess exposes the stdin stream of its underlying ChildProcess:

observable.stdin.write("my input\n")
observable.stdin.end()

Get the process id

observable.pid()

Stop the process

You can manually stop a running process via:

await observable.kill()

This sets the killed property on the ObservableProcess instance, which allows to distinguish manually terminated processes from naturally ended ones.

To let ObservableProcess notify you when a process ended:

const exitCode = await observable.waitForEnd()

You can also listen to this in the background:

observable.waitForEnd().then(function() {
  // do somehing here
})

The exit code is available via an attribute:

observable.exitCode

Related libraries

• nexpect: Allows to define expectations on command output, and send it input, but doesn't allow to add more listeners to existing long-running processes, which makes declarative testing hard.

Development

If you want to hack on ObservableProcess:

• run all tests: make test
• run automated code repair: make fix
• see all make commands: make help

To deploy a new version:

• update the version in package.json and commit to master
• run npm publish