@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<string>}

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

Package detail