nexpect

nexpect is a node.js module for spawning child applications (such as ssh) and seamlessly controlling them using javascript callbacks. nexpect is based on the ideas of the expect library by Don Libes and the pexpect library by Noah Spurrier.

Motivation

node.js has good built in control for spawning child processes. nexpect builds on these core methods and allows developers to easily pipe data to child processes and assert the expected response. nexpect also chains, so you can compose complex terminal interactions.

Installation

  $ npm install --save nexpect

Usage

require('nspawn')

The module exposes a single function, .spawn.

function spawn (command, [params], [options])

command {string|Array} The command that you wish to spawn, a string will be split on ' ' to find the params if params not provided (so do not use the string variant if any arguments have spaces in them)
params {Array} Optional Argv to pass to the child process
options {Object} Optional An object literal which may contain
- cwd: Current working directory of the child process.
- env: Environment variables for the child process.
- ignoreCase: Ignores the case of any output from the child process.
- stripColors: Strips any ANSI colors from the output for .expect() and .wait() statements.
- stream: Expectations can be written against stdout, or stderr, but not both (defaults to 'stdout')
- verbose: Writes the stdout for the child process to process.stdout of the current process, and any data sent with sendline to the process.stdout of the current process.

Top-level entry point for nexpect that liberally parses the arguments and then returns a new chain with the specified command, params, and options.

function expect (str)

str {string} Output to assert on the target stream

Adds a one-time assertion to the context.queue for the current chain.

function wait (str)

str {string} Output to assert on the target stream

Adds an assertion to the context.queue for the current chain, that will wait until it returns true.

XXX(sam) Its not at all clear from the tests how wait() and expect() are different.

function sendline (line)

line {string} Output to write to the child process.

Adds a write line to context.process.stdin to the context.queue for the current chain.

function run (callback)

callback {function} Called when child process closes, with arguments
- err {Error|null} Error if any occurred
- output {Array} Array of lines of output examined
- exit {Number|String} Numeric exit code, or String name of signal

Runs the context against the specified context.command and context.params.

Example

Lets take a look at some sample usage:

  var nexpect = require('nexpect');

  nexpect.spawn("echo", ["hello"])
         .expect("hello")
         .run(function (err, stdout, exitcode) {
           if (!err) {
             console.log("hello was echoed");
           }
         });

  nexpect.spawn("ls -la /tmp/undefined", { stream: 'stderr' })
         .expect("No such file or directory")
         .run(function (err) {
           if (!err) {
             console.log("checked that file doesn't exists");
           }
         });

  nexpect.spawn("node --interactive")
         .expect(">")
         .sendline("console.log('testing')")
         .expect("testing")
         .sendline("process.exit()")
         .run(function (err) {
           if (!err) {
             console.log("node process started, console logged, process exited");
           }
           else {
             console.log(err)
           }
         });

If you are looking for more examples take a look at the examples, and tests.

Tests

All tests are written with vows:

  $ npm test

Authors

Elijah Insua Marak Squires, and Charlie Robbins.

chenglou/nexpect