A modern and intuitive testing library for command-line apps

Installation

$ npm install --save @amilajack/joker

How it looks

const path = require('path');
const assert = require('assert');
const { default: Joker } = require('@amilajack/joker');

(async () => {
  await new Joker()
    .run('echo hello')
    .expect((result) => {
      assert(result.stdout === 'hello');
    })
    .code(0)
    .end();
})();

API

See full API docs

Features

Formatting options

Joker can strip new line characters and colors. You can tell it to do so by passing an object that looks like this:

const options = {
  colors: false,
  newLines: false
};

new Joker(options);

Custom expectations

While Joker comes with built-in expectations, you can use your own too.

await new Joker()
  .run('unicorns')
  .expect(result => {
    if (result.stdout !== 'unicorns') {
      return new Error('NO!');
    }
  })
  .end();

Custom middlewares

You can register as many before and after middlewares as you wish.

await new Joker()
  .before(setupDatabase)
  .before(runMigrations)
  .run(cmd)
  .after(downgradeCron)
  .after(deleteDatabase)
  .end();

Middleware order

The Middleware execution order is very simple - "before" middlewares always run before everything else, "after" middlewares always run after everything else. The other middlewares will match the order that you have specified.

await new Joker()
  .before(before1)
  .before(before2)
  .after(after1)
  .after(after2)
  .writeFile(file, '')
  .run(cmd)
  .unlink(file)
  .end();

// Execution order:
// before1, before2, writeFile, cmd, unlink, after1, after2

Plugins

Joker has primitive support for plugins. You can register any expectation or/and any middleware by calling joker.register.

const fn = () => {};
new Joker().register('foo', fn);

Or you may want to register many functions at once.

const fn = () => {};
const fn1 = () => {};
joker.register({ baz: fn, bar: fn1 });

Usage with a test runner

Joker plays nice with any test runner out there.

Jest

Here is a minimal example how you could use it with Jest using async/await:

describe('todo add', () => {
  it('adds a new todo item', async () => {
    const result = await new Joker()
      .run('todo add')
      .stdout('A new todo has been added')
      .end();
    expect(result.stdout).toMatchSnapshot();
  });
});

Mocha

Here is a minimal example how you could use it with Mocha using callbacks:

describe('todo add', () => {
  it('adds a new todo item', done => {
    new Joker()
      .run('todo add')
      .stdout('A new todo has been added')
      .end(done);
  });
});

Usage without a test runner

While using a test runner is recommended Joker is completely 'nodeable'. Here is a simple example how you could accomplish that:

const assert = require('assert');

function refute(err) {
  assert(!err);
}

new Joker()
  .run(cmd)
  .end(refute);

new Joker()
  .run(anotherCmd)
  .end(refute);

Responding to interactive prompts

Joker can respond to apps that run interactively using the on() and respond() functions.

await new Joker()
  .run(cmd)
  .on('Your name: ')
  .respond('Joe User\n')
  .end();

See test/prompt.test.ts for more examples.

Templates

Every Joker instance can be cloned, which allows you to build "templates" for tests. Here's some examples:

const template = new Joker()
  .cwd(path.join(__dirname, 'fixtures'))
  .run('echo test');

const test1 = await template
  .clone()
  .stdout(/test/)
  .end();

const test2 = await template
  .clone()
  .stdout('test')
  .end();

Credits

Special thanks to:

• Martin Lazarov
• Radoslav Stankov

Support

Do you like this project? Star the repository, spread the word - it really helps. You may want to follow me on Twitter and GitHub. Thanks!

If this project is saving you (or your team) time, please consider supporting it on Patreon 👍 thank you!