observable-process/README.md

<img src="documentation/logo.png" width="1026" height="100" alt="logo">
<hr>

[![CircleCI](https://circleci.com/gh/Originate/observable-process.svg?style=shield)](https://circleci.com/gh/Originate/observable-process)
[![Dependency Status](https://david-dm.org/originate/observable-process.svg)](https://david-dm.org/originate/observable-process)
[![devDependency Status](https://david-dm.org/originate/observable-process/dev-status.svg)](https://david-dm.org/originate/observable-process#info=devDependencies)


High-level support for running, observing, and interacting with child processes
in Node.js 4 and above.


```js
const ObservableProcess = require('observableProcess')
var myProcess = new ObservableProcess('echo hello')
myProcess.on('ended', function ({exitCode}) {
  // ...
})
```

You can also provide the process to run as an _argv_ array:

```js
myProcess = new ObservableProcess(['echo', 'hello'])
```


## Set the working directory of the subshell

```js
myProcess = new ObservableProcess('echo hello', { cwd: '~/tmp' })
```


## Set environment variables in the subshell


```js
myProcess = new ObservableProcess('echo hello', { env: { foo: 'bar' } })
```

## Working with output

ObservableProcess provides powerful mechanisms to work with output
generated by the subprocess.
By default, the output of the observed process is printed on the console.
You can also customize logging by providing custom `stdout` and `stderr` objects
(which needs to have the method `write`):

```js
const myStdOut = {
  write: (text) => {
    // ...
  }
}
const myStdErr = {
  write: (text) => {
    // ...
  }
}
myProcess = new ObservableProcess('echo hello', { stdout: myStdOut, stderr: myStdErr })
```

You can use [dimConsole](https://github.com/kevgo/dim-console-node)
to print output from the subshell dimmed,
so that it is easy to distinguish from output of the main thread.

```js
const dimConsole = require('dim-console')
myProcess = new ObservableProcess('echo hello', { stdout: dimConsole.stdout, stderr: dimConsole.stderr })
```

To get more detailed output like lifecycle events of the subshell
in the error stream:

```js
myProcess = new ObservableProcess('echo hello', { verbose: true })
```

You can retrieve the output that has accumulated so far to `stdout` and `stderr`
merged into a single string:

```js
myProcess.fullOutput()  // returns all the output produced by the subprocess so far
```

You can be notified when the process prints given text on `stdout` or `stderr`.
This is useful for waiting until slow-starting services are fully booted up.

```js
myProcess.waitForText('listening on port 3000').then(function () {
  // this method runs after the process prints "listening on port 3000"
})
```

To disable output altogether:

```js
myProcess = new ObservableProcess('my-server', { stdout: null, stderr: null })
```



## Input

You can enter text into the running process via:

```js
myProcess.enter('text')
```


## Kill the process

If the process is running, you can kill it via:

```js
myProcess.kill()
```

This sets the `killed` property on the ObservableProcess instance,
so that manual kills can be distinguished from crashes.

To let ObservableProcess notify you when a process ended:

```js
myProcess.waitForEnd(({exitCode, killed}) => {
  // the process has ended here
})
```
You can also access the exit code from the process object:

```js
myProcess.exitCode
```

## Get the process id

```
myProcess.pid()
```


## related libraries

* [nexpect](https://github.com/nodejitsu/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.