1 | <img src="documentation/logo.png" width="1026" height="100" alt="logo">
|
2 | <hr>
|
3 |
|
4 | [![CircleCI](https://circleci.com/gh/Originate/observable-process.svg?style=svg)](https://circleci.com/gh/Originate/observable-process)
|
5 | [![Dependency Status](https://david-dm.org/originate/observable-process.svg)](https://david-dm.org/originate/observable-process)
|
6 | [![devDependency Status](https://david-dm.org/originate/observable-process/dev-status.svg)](https://david-dm.org/originate/observable-process#info=devDependencies)
|
7 | <a href="https://yarnpkg.com">
|
8 | <img src="https://img.shields.io/badge/yarn-compatible-brightgreen.svg">
|
9 | </a>
|
10 |
|
11 |
|
12 | High-level support for running, observing, and interacting with child processes
|
13 | in Node.js 4 and above.
|
14 |
|
15 |
|
16 | ```js
|
17 | ObservableProcess = require('observable-process')
|
18 | process = new ObservableProcess('my-server --port 3000')
|
19 | process.on('ended', function(exit-code) { ... })
|
20 | ```
|
21 |
|
22 | You can also provide the process to run as an _argv_ array:
|
23 |
|
24 | ```js
|
25 | process = new ObservableProcess(['my-server', '--port', '3000'])
|
26 | ```
|
27 |
|
28 |
|
29 | ## Set the working directory of the subshell
|
30 |
|
31 | ```js
|
32 | process = new ObservableProcess('my-server', { cwd: '~/tmp' })
|
33 | ```
|
34 |
|
35 |
|
36 | ## Set environment variables in the subshell
|
37 |
|
38 |
|
39 | ```js
|
40 | process = new ObservableProcess('my-server', { env: { foo: 'bar' } })
|
41 | ```
|
42 |
|
43 | ## Working with output
|
44 |
|
45 | ObservableProcess provides powerful mechanisms to work with output generated by the subprocess.
|
46 | By default the output of the observed process is printed on the console.
|
47 | You can also customize logging by providing custom `stdout` and `stderr` objects
|
48 | (which needs to have the method `write`):
|
49 |
|
50 | ```js
|
51 | myStdOut = {
|
52 | write: (text) => { ... }
|
53 | }
|
54 | myStdErr = {
|
55 | write: (text) => { ... }
|
56 | }
|
57 | process = new ObservableProcess('my-server', { stdout: myStdOut, stderr: myStdErr })
|
58 | ```
|
59 |
|
60 | You can use [dim-console](https://github.com/kevgo/dim-console-node)
|
61 | to print output from the subshell dimmed,
|
62 | so that it is easy to distinguish from output of the main thread.
|
63 |
|
64 | ```js
|
65 | dimConsole = require('dim-console')
|
66 | process = new ObservableProcess('my-server', { stdout: dimConsole.stdout, stderr: dimConsole.stderr })
|
67 | ```
|
68 |
|
69 | To get more detailed output, like lifecycle events of the subshell:
|
70 |
|
71 | ```js
|
72 | process = new ObservableProcess('my-server', { verbose: true })
|
73 | ```
|
74 | These events are printed to the error stream.
|
75 |
|
76 | You can retrieve the output that has accumulated so far to stdout and stderr:
|
77 |
|
78 | ```js
|
79 | process.fullOutput() // returns all the output produced by the subprocess so far
|
80 | ```
|
81 |
|
82 | You can be notified when the process prints given text on stdout or stderr:
|
83 |
|
84 | ```js
|
85 | process.wait('listening on port 3000', function() {
|
86 | // this method runs after the process prints "listening on port 3000"
|
87 | });
|
88 | ```
|
89 |
|
90 | This is useful for waiting until slow-starting services are fully booted up.
|
91 |
|
92 | To disable output altogether:
|
93 |
|
94 | ```js
|
95 | process = new ObservableProcess('my-server', { stdout: false, stderr: false })
|
96 | ```
|
97 |
|
98 |
|
99 |
|
100 | ## Input
|
101 |
|
102 | You can enter text into the running process via:
|
103 |
|
104 | ```js
|
105 | process.enter('text')
|
106 | ```
|
107 |
|
108 |
|
109 | ## Kill the process
|
110 |
|
111 | If the process is running, you can kill it via:
|
112 |
|
113 | ```js
|
114 | process.kill()
|
115 | ```
|
116 |
|
117 | This sets the `killed` property on the ObservableProcess instance,
|
118 | so that manual kills can be distinguished from crashes.
|
119 |
|
120 | To let ObservableProcess notify you when a process ended,
|
121 | subscribe to the `ended` event:
|
122 |
|
123 | ```js
|
124 | process.on 'ended', (exitCode, killed) => {
|
125 | // the process has ended here
|
126 | // you can also access the exit code via process.exitCode
|
127 | }
|
128 | ```
|
129 |
|
130 | ## Get the process id
|
131 |
|
132 | ```
|
133 | process.pid()
|
134 | ```
|
135 |
|
136 |
|
137 | ## related libraries
|
138 |
|
139 | * [nexpect](https://github.com/nodejitsu/nexpect):
|
140 | Allows to define expectations on command output,
|
141 | and send it input,
|
142 | but doesn't allow to add more listeners to existing long-running processes,
|
143 | which makes declarative testing hard.
|