@scalvert/bin-tester

Provides a test harness for node CLIs that allow you to run tests against a real project.

Install

npm add @scalvert/bin-tester --save-dev

# or

yarn add @scalvert/bin-tester --dev

Usage

@scalvert/bin-tester uses two libraries to provide the test harness:

• fixturify-project: Allows you to dynamically create test fixtures using real directories and files in a tmp directory
• execa: A better replacement for child_process.exec

It combines the above and provides an API for running a binary with a set of arguments against a real project structure, thus mimicking testing a real environment.

import { createBinTester } from '@scalvert/bin-tester';

describe('Some tests', () => {
  let project;
  let { setupProject, teardownProject, runBin } = createBinTester({
    binPath: 'node_modules/.bin/someBin',
    staticArgs: ['--some-arg'], // pass some args to the bin that will be used for each invocation
  });

  beforeEach(() => {
    project = await setupProject();
  });

  afterEach(() => {
    await teardownProject();
  });

  // Run the bin and do something with the result
  test('a test', async () => {
    const result = await runBin();

    expect(result.stdout).toBe('Did some stuff');
  });

  test('another test', async () => {
    // Write a file with contents to the tmp directory
    await project.writeDirJSON({
      'some/file.txt': 'some content',
    });

    // pass some args to the bin that will be used for only this invocation
    const result = await runBin('--path', 'some/file.txt');

    expect(result.stdout).toBe('Read "some/file.txt"');
  });
});

API

Classes

BinTesterProject

Functions

createBinTester(options) ⇒ CreateBinTesterResult.<TProject>

Creates the bin tester API functions to use within tests.

BinTesterProject

Kind: global class

• BinTesterProject
  • new BinTesterProject(name, version, cb)
  • .gitInit() ⇒ *
  • .chdir()
  • .dispose() ⇒ void

new BinTesterProject(name, version, cb)

Constructs an instance of a BinTesterProject.

Param	Type	Default	Description
name	string	"fake-project"	The name of the project. Used within the package.json as the name property.
version	string		The version of the project. Used within the package.json as the version property.
cb	function		An optional callback for additional setup steps after the project is constructed.

binTesterProject.gitInit() ⇒ *

Runs git init inside a project.

Kind: instance method of BinTesterProject
Returns: * -

{execa.ExecaChildProcess}

binTesterProject.chdir()

Changes a directory from inside the project.

Kind: instance method of BinTesterProject

binTesterProject.dispose() ⇒ void

Correctly disposes of the project, observing when the directory has been changed.

Kind: instance method of BinTesterProject

createBinTester(options) ⇒ CreateBinTesterResult.<TProject>

Creates the bin tester API functions to use within tests.

Kind: global function
Returns: CreateBinTesterResult.<TProject> -

• A project instance.

Param	Type	Description
options	BinTesterOptions.<TProject>	An object of bin tester options

• createBinTester(options) ⇒ CreateBinTesterResult.<TProject>
  • ~runBin(...args) ⇒ execa.ExecaChildProcess.<string>
  • ~setupProject()
  • ~setupTmpDir()
  • ~teardownProject()

createBinTester~runBin(...args) ⇒ execa.ExecaChildProcess.<string>

Kind: inner method of createBinTester
Returns: execa.ExecaChildProcess.<string> -

An instance of execa's child process.

Param	Type	Description
...args	RunBinArgs	Arguments or execa options.

createBinTester~setupProject()

Sets up the specified project for use within tests.

Kind: inner method of createBinTester

createBinTester~setupTmpDir()

Sets up a tmp directory for use within tests.

Kind: inner method of createBinTester

createBinTester~teardownProject()

Tears the project down, ensuring the tmp directory is removed. Shoud be paired with setupProject.

Kind: inner method of createBinTester