Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/scalvert/bin-tester
A test harness to invoke a CLI in a tmp directory
https://github.com/scalvert/bin-tester
Last synced: 2 months ago
JSON representation
A test harness to invoke a CLI in a tmp directory
- Host: GitHub
- URL: https://github.com/scalvert/bin-tester
- Owner: scalvert
- Created: 2022-03-10T20:58:32.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2023-03-06T05:06:01.000Z (almost 2 years ago)
- Last Synced: 2024-10-19T17:57:38.266Z (2 months ago)
- Language: TypeScript
- Size: 22.8 MB
- Stars: 4
- Watchers: 4
- Forks: 0
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# @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
## 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> -
- A project instance.
| 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)