# @scalvert/bin-tester
[](https://badge.fury.io/js/%40scalvert%2Fbin-tester)
[](https://github.com/scalvert/bin-tester/blob/master/package.json)
[](#badge)
> Provides a test harness for node CLIs that allow you to run tests against a real project.
## Install
```shell
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`](https://github.com/stefanpenner/node-fixturify-project): Allows you to dynamically create test fixtures using real directories and files in a tmp directory
- [`execa`](https://github.com/sindresorhus/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.
```js
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](#BinTesterProject)
* [new BinTesterProject(name, version, cb)](#new_BinTesterProject_new)
* [.gitInit()](#BinTesterProject+gitInit) ⇒ \*
* [.chdir()](#BinTesterProject+chdir)
* [.dispose()](#BinTesterProject+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](#BinTesterProject)
**Returns**: \* - {execa.ExecaChildProcess}
### binTesterProject.chdir()
Changes a directory from inside the project.
**Kind**: instance method of [BinTesterProject](#BinTesterProject)
### binTesterProject.dispose() ⇒ void
Correctly disposes of the project, observing when the directory has been changed.
**Kind**: instance method of [BinTesterProject](#BinTesterProject)
## createBinTester(options) ⇒ CreateBinTesterResult.<TProject>
Creates the bin tester API functions to use within tests.
**Kind**: global function
**Returns**: CreateBinTesterResult.<TProject> -
| Param | Type | Description |
| --- | --- | --- |
| options | BinTesterOptions.<TProject> | An object of bin tester options
|
* [createBinTester(options)](#createBinTester) ⇒ CreateBinTesterResult.<TProject>
* [~runBin(...args)](#createBinTester..runBin) ⇒ execa.ExecaChildProcess.<string>
* [~setupProject()](#createBinTester..setupProject)
* [~setupTmpDir()](#createBinTester..setupTmpDir)
* [~teardownProject()](#createBinTester..teardownProject)
### createBinTester~runBin(...args) ⇒ execa.ExecaChildProcess.<string>
**Kind**: inner method of [createBinTester](#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)
### createBinTester~setupTmpDir()
Sets up a tmp directory for use within tests.
**Kind**: inner method of [createBinTester](#createBinTester)
### createBinTester~teardownProject()
Tears the project down, ensuring the tmp directory is removed. Shoud be paired with setupProject.
**Kind**: inner method of [createBinTester](#createBinTester)