gentle-cli

Inspired / Based off both cli-easy and supertest

CLI assertions made easy.

• Struggling with testing cli tools.
• cli-easy is super great, but designed for generating vows
• supertest is super great, but designed to make HTTP assertions via super-agent.

gentle-cli is nothing more than a simple, chainable API to ease the process of testing CLI applications & tools.

Right now, it doesn't do anything fancy and just allow you to easily test the exit code and stdout output, and make assertions on top of that.

Documentation

It should work with any test framework, here is an example using any test framework at all.

var cli = require('gentle-cli');

// promise
cli()
  .use('whoami')
  .expect(0, 'A fool')
  .then(function(res) {
    console.log(res.status);
    console.log(res.text);
    console.log(res.err);
  });

// callback
cli()
  .use('uname')
  .expect(0, 'Linux\n')
  .end(function(err, stdout, stderr) {
    if(err) throw err;
  });

ava

Check gentle cli tests, they're using ava:

import test from 'ava';
import cli from '..';
import constants from 'constants';

test('Testing on uname', t => {
  t.plan(0);
  return cli()
    .use('uname')
    .expect(0, process.platform === 'darwin' ? 'Darwin' : 'Linux')
    .end();
});

test('Testing on a wtf thing', t => {
  t.plan(0);
  return cli()
    .use('wtfBinary')
    .expect(constants.ENOENT)
    .throws('ENOENT')
    .end();
});

cli().end() returns a promise you can pass through ava, as well as .then() and .catch().

Tips Make sure to call t.plan(0) if you're doing assertions using gentle-cli and not ava. Otherwise, ava will fail.

mocha

Here's an example with mocha, note how you can pass done straight to any of the .expect() calls (or .end()):

describe('test uname', function() {
  it('respond with Linux', function(done) {
    cli()
      .use('uname')
      .expect('should return Linux', 'Linux\n')
      .expect(0, done)
  });
});

fancier example.

describe('Testing on a wtf thing', function() {
  it('should fail as expected', function(done) {
    cli()
      .use('wtfBinary')
      .expect(127, /command not found/)
      .end(done);
  });
});

promise example

API

module.exports = Runnable;

Main assertion thingy

Thx to @tj, based off supertest's Runnable object: https://github.com/visionmedia/supertest/blob/master/lib/Runnable.js

function Runnable(cmds, options)

Initialize a new Runnable with the given options Hash object.

Runnable#use()

Setup CLI command.

Runnable#expect()

Adds a new expectation to this runnable instance.

.expect(0)
.expect(0, fn)
.expect(0, body)
.expect('Some body')
.expect('Some body', fn)

Runnable#throws()

Adds a new expectation to this runnable instance.

.throws(0)
.throws('ENOENT')
.throws(require('constants').ENOENT)

Runnable#end()

Defer invoking .end() until the command is done running.

it('test thing', function(done) {
  cli()
    .use('thing')
    .expect(/run thing/)
    .end(done);
});

Returns a promise.

Runnable#then()

Automatically invokes end() and register the callback.

Returns a promise.

Runnable#catch()

Automatically invokes end() and register the errback.

Returns a promise.

Changelog

Unreleased

v1.0.4 - 2018-09-30

Fixed

• Switch to exec instead of spawn #1 #2

Commits

• es6: update test.js to use most of es6 syntax (thx prettier) cff47b0
• Rewrite test.js using es6 class syntax 055059d
• Update test, setup travis ee72e69

v1.0.3 - 2016-04-26

Commits

• Fix asserts err return 115f129

v1.0.2 - 2016-04-25

Commits

• s/clt/gentle-cli 5a71dae

v1.0.1 - 2016-04-25

Commits

• MIT 1811d15
• s/visionmedia/tj ce1bd1e

v1.0.0 - 2016-04-25

Commits

• Update code, implement throws and better support of node core errors 6c22c97
• Document api d7dd12f

v0.0.2 - 2012-09-20

Commits

• updates, adding prompt api, multiple expecs, adding API docs cecca5f

v0.0.1 - 2012-07-18

Commits

• haha.. this :q thing was funny 4dac4f7
• 1st 1bd8290