@evolopment/chai-process v1.0.2
chai-process
This plugin for the Chai assertion library allows to assert conditions on the execution of subprocesses.
Install
npm install @evolopment/chai-process --save-dev
Examples
As the result of execution is asynchronous, it's used along Chai as promised.
var chai = require('chai');
var chaiProcess = require('@evolopment/chai-process');
var chaiAsPromised = require('chai-as-promised);
chai.use(chaiProcess);
chai.use(chaiAsPromised);
var spawn = chaiProcess.spawn; // convinience to use shorter lines
it('succeeds if the process exits with return code 0', function () {
return expect(spawn('node', ['simple-ok.js'])).to.eventually.succeed;
});
it('succeeds if the process exits with return code other than 0', function () {
return expect(spawn('node', ['simple-ko.js'])).to.eventually.fail;
});
it('property returns the exit code', function () {
return expect(spawn('node', ['simple-ko-alt.js'])).to.eventually.exitCode.eql(2);
});
it('property returns the execution time', function () {
this.timeout(3000);
return expect(spawn('node', ['delay-2s.js'])).to.eventually.seconds.within(2, 2.5);
});
it('method returns the childout standard output (stdio[1])', function() {
return expect(spawn('node', ['io-stdout-1.js'])).to.eventually.stdout().eql('abcdefgh.\"+-*?1234\n');
});
it('method returns the childout standard error (stdio[2]) with specified encoding (ascii)', function() {
return expect(spawn('node', ['io-stderr-1.js'])).to.eventually.stderr('ascii').eql('abcdefgh.\"+-*?1234\n');
});
API
spawn(command, arguments, options)
Executes a spawn function to create a subprocess.
The command
and arguments
parameters are the same documented in spawn (command to be executed and arguments to the command).
The options
optional parameter (an object) allows the following properties:
- cwd: Execution directory, passed directly to
spawn
. - env: Environment variables, passed directly to
spawn
. - detached: Detached (true if the new process must not be child of the parent), passed directly to
spawn
. - uid: User id, to execute as another user, passed directly to
spawn
. - gid: Group id, to execute as another group, passed directly to
spawn
. ipc: To active the built-in interprocess communication. If specified, an 'ipc' file descriptor will be created after 'stderr'.
The standard I/O property (I/O) can't be specified directly, as it's used to capture the standard output and error.
The result value is a Promise, so it requires that the
Chai-As-Promised plugin is installed,
and the use of eventually
in the assertion chain.
Example
return expect(spawn('node', ['delay-2s.js'])).to.eventually.seconds.within(2, 2.5);
exec(command, options)
Executes an exec function to create a subprocess.
The command
and options
parameters are the same documented in exec
The result value is a Promise, so it requires that the
Chai-As-Promised plugin is installed,
and the use of eventually
in the assertion chain.
Example
return expect(exec('node delay-2s.js')).to.eventually.seconds.within(2, 2.5);
succeed
Asserts if a process has executed without errors (exit code 0).
Depends totally in the exit code, so if your subject under test fails with code 0, it won't work.
Example
return expect(spawn('node', ['simple-ok.js'])).to.eventually.succeed;
fail
Asserts if a process has executed with some error (exit code >0).
Depends totally in the exit code, so if your subject under test fails with code 0, it won't work.
Example
return expect(spawn('node', ['simple-ko.js'])).to.eventually.fail;
exitCode
Returns the exit code of the subprocess. It allows to check ranges.
Example
return expect(spawn('node', ['simple-ko-alt.js'])).to.eventually.exitCode.eql(2);
exitWithCode(n)
Asserts if a process exists with a concrete code. It's syntactic sugar for exitCode.eql(n).
Example
return expect(spawn('node', ['simple-ko-alt.js'])).to.eventually.exitWithCode(2);
seconds, milliseconds, microseconds, nanoseconds
Returns the execution time (as seen from the node.js engine of the parent).
The different properties return the value in each unit. The units are a commodity, not a specification of precision.
Although it uses the process.hrtime()
function and has it's value available even in nanoseconds,
don't expect much accuracy.
Example
return expect(spawn('node', ['delay-2s.js'])).to.eventually.seconds.within(2, 2.5);
stdout(), stdout(encoding)
Returns the standard output of the process, as a unique string. A default encoding is used unless the encoding parameter is used.
Examples
return expect(spawn('node', ['io-stdout-1.js'])).to.eventually.stdout().eql('abcdefgh.\"+-*?1234\n');
return expect(spawn('node', ['io-stdout-utf8.js'])).to.eventually.stdout('utf8').eql('¿?ÑÇ');
stderr(), stderr(encoding)
Returns the standard error of the process, as a unique string. A default encoding is used unless the encoding parameter is used.
Examples
return expect(spawn('node', ['io-stderr-1.js'])).to.eventually.stderr().eql('abcdefgh.\"+-*?1234\n');
return expect(spawn('node', ['io-stderr-utf8.js'])).to.eventually.stderr('utf8').eql('¿?ÑÇ');