@scalvert/bin-tester 2.1.0 → 3.0.0

package/README.md

@@ -4,176 +4,116 @@
 [![npm version](https://badge.fury.io/js/%40scalvert%2Fbin-tester.svg)](https://badge.fury.io/js/%40scalvert%2Fbin-tester)
 [![License](https://img.shields.io/npm/l/@scalvert/bin-tester.svg)](https://github.com/scalvert/bin-tester/blob/master/package.json)
 ![Dependabot](https://badgen.net/badge/icon/dependabot?icon=dependabot&label)
-![Volta Managed](https://img.shields.io/static/v1?label=volta&message=managed&color=yellow&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABmJLR0QAeQC6AMEpK7AhAAAACXBIWXMAAAsSAAALEgHS3X78AAAAB3RJTUUH5AMGFS07qAYEaAAAABl0RVh0Q29tbWVudABDcmVhdGVkIHdpdGggR0lNUFeBDhcAAAFmSURBVDjLY2CgB/g/j0H5/2wGW2xyTAQ1r2DQYOBgm8nwh+EY6TYvZtD7f9rn5e81fAGka17GYPL/esObP+dyj5Cs+edqZsv/V8o//H+z7P+XHarW+NSyoAv8WsFszyKTtoVBM5Tn7/Xys+zf7v76vYrJlPEvAwPjH0YGxp//3jGl/L8LU8+IrPnPUkY3ZomoDQwOpZwMv14zMHy8yMDwh4mB4Q8jA8OTgwz/L299wMDyx4Mp9f9NDAP+bWVwY3jGsJpB3JaDQVCEgYHlLwPDfwYWRqVQJgZmHoZ/+3PPfWP+68Mb/Pw5sqUoLni9ipuRnekrAwMjA8Ofb6K8/PKBF5nU7RX+Hize8Y2DOZTP7+kXogPy1zrH+f/vT/j/Z5nUvGcr5VhJioUf88UC/59L+/97gUgDyVH4YzqXxL8dOs/+zuFLJivd/53HseLPPHZPsjT/nsHi93cqozHZue7rLDYhUvUAADjCgneouzo/AAAAAElFTkSuQmCC&link=https://volta.sh)
 [![Code Style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](#badge)
 
-> Provides a test harness for node CLIs that allow you to run tests against a real project.
+A test harness for Node.js CLI tools.
 
-## Install
-
-```shell
-npm add @scalvert/bin-tester --save-dev
-
-# or
-
-yarn add @scalvert/bin-tester --dev
-```
+Testing a CLI isn't like testing a library—you can't just import functions and call them. You need to spawn your CLI as a subprocess, give it real files to work with, and capture its output. bin-tester simplifies this:
 
-## 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
+```ts snippet=basic-example.ts
 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
+describe('my-cli', () => {
+  const { setupProject, teardownProject, runBin } = createBinTester({
+    binPath: './bin/my-cli.js',
   });
 
-  beforeEach(() => {
+  let project;
+
+  beforeEach(async () => {
     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');
+    teardownProject();
   });
 
-  test('another test', async () => {
-    // Write a file with contents to the tmp directory
-    await project.writeDirJSON({
-      'some/file.txt': 'some content',
-    });
+  test('processes files', async () => {
+    project.files = { 'input.txt': 'hello' };
+    await project.write();
 
-    // pass some args to the bin that will be used for only this invocation
-    const result = await runBin('--path', 'some/file.txt');
+    const result = await runBin('input.txt');
 
-    expect(result.stdout).toBe('Read "some/file.txt"');
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain('processed');
   });
 });
 ```
 
-## API
-
-<!--DOCS_START-->
-## Classes
-
-<dl>
-<dt><a href="#BinTesterProject">BinTesterProject</a></dt>
-<dd></dd>
-</dl>
-
-## Functions
-
-<dl>
-<dt><a href="#createBinTester">createBinTester(options)</a> ⇒ <code>CreateBinTesterResult.&lt;TProject&gt;</code></dt>
-<dd><p>Creates the bin tester API functions to use within tests.</p></dd>
-</dl>
-
-<a name="BinTesterProject"></a>
-
-## BinTesterProject
-**Kind**: global class  
-
-* [BinTesterProject](#BinTesterProject)
-    * [new BinTesterProject(name, version, cb)](#new_BinTesterProject_new)
-    * [.gitInit()](#BinTesterProject+gitInit) ⇒ <code>\*</code>
-    * [.chdir()](#BinTesterProject+chdir)
-    * [.dispose()](#BinTesterProject+dispose) ⇒ <code>void</code>
-
-<a name="new_BinTesterProject_new"></a>
-
-### new BinTesterProject(name, version, cb)
-<p>Constructs an instance of a BinTesterProject.</p>
-
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| name | <code>string</code> | <code>&quot;fake-project&quot;</code> | <p>The name of the project. Used within the package.json as the name property.</p> |
-| version | <code>string</code> |  | <p>The version of the project. Used within the package.json as the version property.</p> |
-| cb | <code>function</code> |  | <p>An optional callback for additional setup steps after the project is constructed.</p> |
-
-<a name="BinTesterProject+gitInit"></a>
-
-### binTesterProject.gitInit() ⇒ <code>\*</code>
-<p>Runs <code>git init</code> inside a project.</p>
-
-**Kind**: instance method of [<code>BinTesterProject</code>](#BinTesterProject)  
-**Returns**: <code>\*</code> - <p>{execa.ExecaChildProcess<string>}</p>  
-<a name="BinTesterProject+chdir"></a>
-
-### binTesterProject.chdir()
-<p>Changes a directory from inside the project.</p>
+## Install
 
-**Kind**: instance method of [<code>BinTesterProject</code>](#BinTesterProject)  
-<a name="BinTesterProject+dispose"></a>
+```bash
+npm add @scalvert/bin-tester --save-dev
+```
 
-### binTesterProject.dispose() ⇒ <code>void</code>
-<p>Correctly disposes of the project, observing when the directory has been changed.</p>
+## Usage
 
-**Kind**: instance method of [<code>BinTesterProject</code>](#BinTesterProject)  
-<a name="createBinTester"></a>
+`createBinTester` returns helpers for setting up projects, running your CLI, and cleaning up:
 
-## createBinTester(options) ⇒ <code>CreateBinTesterResult.&lt;TProject&gt;</code>
-<p>Creates the bin tester API functions to use within tests.</p>
+```ts snippet=create-bin-tester.ts
+const { setupProject, teardownProject, runBin } = createBinTester({
+  binPath: './bin/my-cli.js',
+  staticArgs: ['--verbose'], // args passed to every invocation
+});
+```
 
-**Kind**: global function  
-**Returns**: <code>CreateBinTesterResult.&lt;TProject&gt;</code> - <ul>
-<li>A project instance.</li>
-</ul>  
+**Setup and teardown:**
 
-| Param | Type | Description |
-| --- | --- | --- |
-| options | <code>BinTesterOptions.&lt;TProject&gt;</code> | <p>An object of bin tester options</p> |
+```ts snippet=setup-teardown.ts
+const project = await setupProject(); // creates temp directory
+// ... run tests ...
+teardownProject(); // removes temp directory
+```
 
+**Writing fixture files:**
 
-* [createBinTester(options)](#createBinTester) ⇒ <code>CreateBinTesterResult.&lt;TProject&gt;</code>
-    * [~runBin(...args)](#createBinTester..runBin) ⇒ <code>execa.ExecaChildProcess.&lt;string&gt;</code>
-    * [~setupProject()](#createBinTester..setupProject)
-    * [~setupTmpDir()](#createBinTester..setupTmpDir)
-    * [~teardownProject()](#createBinTester..teardownProject)
+```ts snippet=writing-fixtures.ts
+project.files = {
+  'src/index.js': 'export default 42;',
+  'package.json': JSON.stringify({ name: 'test' }),
+};
+await project.write();
+```
 
-<a name="createBinTester..runBin"></a>
+**Running your CLI:**
 
-### createBinTester~runBin(...args) ⇒ <code>execa.ExecaChildProcess.&lt;string&gt;</code>
-**Kind**: inner method of [<code>createBinTester</code>](#createBinTester)  
-**Returns**: <code>execa.ExecaChildProcess.&lt;string&gt;</code> - <p>An instance of execa's child process.</p>  
+```ts snippet=running-cli.ts
+const result = await runBin('--flag', 'arg');
 
-| Param | Type | Description |
-| --- | --- | --- |
-| ...args | <code>RunBinArgs</code> | <p>Arguments or execa options.</p> |
+result.exitCode; // number
+result.stdout; // string
+result.stderr; // string
+```
 
-<a name="createBinTester..setupProject"></a>
+## Debugging
 
-### createBinTester~setupProject()
-<p>Sets up the specified project for use within tests.</p>
+Set `BIN_TESTER_DEBUG` to enable the Node inspector and preserve fixtures for inspection:
 
-**Kind**: inner method of [<code>createBinTester</code>](#createBinTester)  
-<a name="createBinTester..setupTmpDir"></a>
+```bash
+BIN_TESTER_DEBUG=attach npm test  # attach debugger
+BIN_TESTER_DEBUG=break npm test   # break on first line
+```
 
-### createBinTester~setupTmpDir()
-<p>Sets up a tmp directory for use within tests.</p>
+Or use `runBinDebug()` programmatically:
 
-**Kind**: inner method of [<code>createBinTester</code>](#createBinTester)  
-<a name="createBinTester..teardownProject"></a>
+```ts snippet=run-bin-debug.ts
+await runBinDebug('--flag'); // runs with --inspect
+```
 
-### createBinTester~teardownProject()
-<p>Tears the project down, ensuring the tmp directory is removed. Shoud be paired with setupProject.</p>
+For VS Code, add to `.vscode/launch.json`:
+
+```jsonc
+{
+  "name": "Debug Tests",
+  "type": "node",
+  "request": "launch",
+  "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/vitest",
+  "runtimeArgs": ["run"],
+  "autoAttachChildProcesses": true,
+  "console": "integratedTerminal",
+}
+```
 
-**Kind**: inner method of [<code>createBinTester</code>](#createBinTester)  
+## API
 
-<!--DOCS_END-->
+See the [full API documentation](https://scalvert.github.io/bin-tester/).

package/dist/index.cjs

@@ -1,23 +1,8 @@
-var __create = Object.create;
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropSymbols = Object.getOwnPropertySymbols;
-var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __propIsEnum = Object.prototype.propertyIsEnumerable;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __spreadValues = (a, b) => {
-  for (var prop in b || (b = {}))
-    if (__hasOwnProp.call(b, prop))
-      __defNormalProp(a, prop, b[prop]);
-  if (__getOwnPropSymbols)
-    for (var prop of __getOwnPropSymbols(b)) {
-      if (__propIsEnum.call(b, prop))
-        __defNormalProp(a, prop, b[prop]);
-    }
-  return a;
-};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -30,25 +15,30 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target, mod));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
-var src_exports = {};
-__export(src_exports, {
+var index_exports = {};
+__export(index_exports, {
   BinTesterProject: () => BinTesterProject,
   createBinTester: () => createBinTester
 });
-module.exports = __toCommonJS(src_exports);
+module.exports = __toCommonJS(index_exports);
 
 // src/create-bin-tester.ts
-var import_execa2 = __toESM(require("execa"), 1);
+var import_execa2 = require("execa");
 
 // src/project.ts
-var import_execa = __toESM(require("execa"), 1);
+var import_execa = require("execa");
 var import_fixturify_project = require("fixturify-project");
 var ROOT = process.cwd();
 var BinTesterProject = class extends import_fixturify_project.Project {
+  /**
+   * Constructs an instance of a BinTesterProject.
+   * @param {string} name - The name of the project. Used within the package.json as the name property.
+   * @param {string} version - The version of the project. Used within the package.json as the version property.
+   * @param {Function} cb - An optional callback for additional setup steps after the project is constructed.
+   */
   constructor(name = "fake-project", version, cb) {
     super(name, version, cb);
     this._dirChanged = false;
@@ -58,14 +48,31 @@ var BinTesterProject = class extends import_fixturify_project.Project {
       repository: "http://fakerepo.com"
     });
   }
+  /**
+   * Runs `git init` inside a project.
+   * @returns {*} {ResultPromise}
+   */
   gitInit() {
-    return (0, import_execa.default)(`git init -q ${this.baseDir}`);
+    return (0, import_execa.execa)("git", ["init", "-q", this.baseDir]);
+  }
+  /**
+   * Writes the project files to disk.
+   */
+  async write() {
+    return super.write();
   }
+  /**
+   * Changes a directory from inside the project.
+   */
   async chdir() {
     this._dirChanged = true;
     await this.write();
     process.chdir(this.baseDir);
   }
+  /**
+   * Correctly disposes of the project, observing when the directory has been changed.
+   * @returns {void}
+   */
   dispose() {
     if (this._dirChanged) {
       process.chdir(ROOT);
@@ -80,28 +87,59 @@ var DEFAULT_BIN_TESTER_OPTIONS = {
 };
 function parseArgs(args) {
   if (args.length > 0 && typeof args[args.length - 1] === "object") {
-    const execaOptions = args.pop();
+    const argsCopy = [...args];
+    const execaOptions = argsCopy.pop();
     return {
-      args,
+      args: argsCopy,
       execaOptions
     };
   } else {
     return {
-      args,
+      args: [...args],
       execaOptions: {}
     };
   }
 }
 function createBinTester(options) {
   let project;
-  const mergedOptions = __spreadValues(__spreadValues({}, DEFAULT_BIN_TESTER_OPTIONS), options);
+  const mergedOptions = {
+    ...DEFAULT_BIN_TESTER_OPTIONS,
+    ...options
+  };
   function runBin(...args) {
     const mergedRunOptions = parseArgs(args);
     const binPath = typeof mergedOptions.binPath === "function" ? mergedOptions.binPath(project) : mergedOptions.binPath;
-    return (0, import_execa2.default)(process.execPath, [binPath, ...mergedOptions.staticArgs, ...mergedRunOptions.args], __spreadValues({
+    const optionsEnv = mergedRunOptions.execaOptions.env;
+    const debugEnv = optionsEnv?.BIN_TESTER_DEBUG ?? process.env.BIN_TESTER_DEBUG;
+    const nodeOptions = [];
+    if (debugEnv && debugEnv !== "0" && debugEnv.toLowerCase() !== "false") {
+      if (debugEnv.toLowerCase() === "break") {
+        nodeOptions.push("--inspect-brk=0");
+      } else {
+        nodeOptions.push("--inspect=0");
+      }
+      console.log(`[bin-tester] Debugging enabled. Fixture: ${project.baseDir}`);
+    }
+    const resolvedCwd = mergedRunOptions.execaOptions.cwd ?? project.baseDir;
+    return (0, import_execa2.execaNode)(binPath, [...mergedOptions.staticArgs, ...mergedRunOptions.args], {
       reject: false,
-      cwd: project.baseDir
-    }, mergedRunOptions.execaOptions));
+      cwd: resolvedCwd,
+      nodeOptions,
+      ...mergedRunOptions.execaOptions
+    });
+  }
+  function runBinDebug(...args) {
+    const parsedArgs = parseArgs(args);
+    const debugEnv = process.env.BIN_TESTER_DEBUG || "attach";
+    parsedArgs.execaOptions = {
+      ...parsedArgs.execaOptions,
+      env: {
+        ...parsedArgs.execaOptions.env,
+        BIN_TESTER_DEBUG: debugEnv
+      }
+    };
+    const reconstructedArgs = [...parsedArgs.args, parsedArgs.execaOptions];
+    return runBin(...reconstructedArgs);
   }
   async function setupProject() {
     project = "createProject" in mergedOptions ? await mergedOptions.createProject() : new BinTesterProject();
@@ -115,10 +153,16 @@ function createBinTester(options) {
     return project.baseDir;
   }
   function teardownProject() {
+    const debugEnv = process.env.BIN_TESTER_DEBUG;
+    if (debugEnv && debugEnv !== "0" && debugEnv.toLowerCase() !== "false") {
+      console.log(`[bin-tester] Fixture preserved: ${project.baseDir}`);
+      return;
+    }
     project.dispose();
   }
   return {
     runBin,
+    runBinDebug,
     setupProject,
     teardownProject,
     setupTmpDir

package/dist/index.d.cts

@@ -0,0 +1,112 @@
+import { ResultPromise, Options } from 'execa';
+import { Project } from 'fixturify-project';
+
+declare class BinTesterProject extends Project {
+    private _dirChanged;
+    /**
+     * Constructs an instance of a BinTesterProject.
+     * @param {string} name - The name of the project. Used within the package.json as the name property.
+     * @param {string} version - The version of the project. Used within the package.json as the version property.
+     * @param {Function} cb - An optional callback for additional setup steps after the project is constructed.
+     */
+    constructor(name?: string, version?: string, cb?: (project: Project) => void);
+    /**
+     * Runs `git init` inside a project.
+     * @returns {*} {ResultPromise}
+     */
+    gitInit(): ResultPromise;
+    /**
+     * Writes the project files to disk.
+     */
+    write(): Promise<void>;
+    /**
+     * Changes a directory from inside the project.
+     */
+    chdir(): Promise<void>;
+    /**
+     * Correctly disposes of the project, observing when the directory has been changed.
+     * @returns {void}
+     */
+    dispose(): void;
+}
+
+/**
+ * Options for configuring the bin tester.
+ */
+interface BinTesterOptions<TProject> {
+    /**
+     * The absolute path to the bin to invoke
+     */
+    binPath: string | (<TProject extends BinTesterProject>(project: TProject) => string);
+    /**
+     * An array of static arguments that will be used every time when running the bin
+     */
+    staticArgs?: string[];
+    /**
+     * An optional function to use to create the project. Use this if you want to provide a custom implementation of a BinTesterProject.
+     */
+    createProject?: () => Promise<TProject>;
+}
+/**
+ * Function signature for running the configured CLI binary.
+ */
+interface RunBin {
+    /**
+     * A runBin implementation that takes no parameters.
+     * @returns {*}  {ResultPromise}
+     */
+    (): ResultPromise;
+    /**
+     * A runBin implementation that takes string varargs.
+     * @param {...RunBinArgs} args
+     * @returns {*}  {ResultPromise}
+     */
+    (...args: [...binArgs: string[]]): ResultPromise;
+    /**
+     * A runBin implementation that takes an Options object.
+     * @param {...RunBinArgs} args
+     * @returns {*}  {ResultPromise}
+     */
+    (...args: [execaOptions: Options]): ResultPromise;
+    /**
+     * A runBin implementation that takes string or an Options object varargs.
+     * @param {...RunBinArgs} args
+     * @returns {*}  {ResultPromise}
+     */
+    (...args: [...binArgs: string[], execaOptions: Options]): ResultPromise;
+}
+/**
+ * The result returned by createBinTester.
+ */
+interface CreateBinTesterResult<TProject extends BinTesterProject> {
+    /**
+     * Runs the configured bin function via execa.
+     */
+    runBin: RunBin;
+    /**
+     * Sets up the specified project for use within tests.
+     */
+    setupProject: () => Promise<TProject>;
+    /**
+     * Sets up a tmp directory for use within tests.
+     */
+    setupTmpDir: () => Promise<string>;
+    /**
+     * Tears the project down, ensuring the tmp directory is removed.
+     * When BIN_TESTER_DEBUG is set, fixtures are preserved for inspection.
+     */
+    teardownProject: () => void;
+    /**
+     * Runs the configured bin with Node inspector enabled in attach mode (--inspect).
+     * Set BIN_TESTER_DEBUG=break to break on first line instead.
+     */
+    runBinDebug: RunBin;
+}
+/**
+ * Creates the bin tester API functions to use within tests.
+ * @param {BinTesterOptions<TProject>} options - An object of bin tester options
+ * @returns {CreateBinTesterResult<TProject>} - A project instance.
+ */
+declare function createBinTester<TProject extends BinTesterProject>(options: BinTesterOptions<TProject>): CreateBinTesterResult<TProject>;
+
+export { type BinTesterOptions, BinTesterProject, type CreateBinTesterResult, type RunBin, createBinTester };

package/dist/index.d.ts

@@ -1,11 +1,10 @@
-import execa from 'execa';
+import { ResultPromise, Options } from 'execa';
 import { Project } from 'fixturify-project';
 
 declare class BinTesterProject extends Project {
     private _dirChanged;
     /**
      * Constructs an instance of a BinTesterProject.
-     *
      * @param {string} name - The name of the project. Used within the package.json as the name property.
      * @param {string} version - The version of the project. Used within the package.json as the version property.
      * @param {Function} cb - An optional callback for additional setup steps after the project is constructed.
@@ -13,22 +12,27 @@ declare class BinTesterProject extends Project {
     constructor(name?: string, version?: string, cb?: (project: Project) => void);
     /**
      * Runs `git init` inside a project.
-     *
-     * @returns {*} {execa.ExecaChildProcess<string>}
+     * @returns {*} {ResultPromise}
      */
-    gitInit(): execa.ExecaChildProcess<string>;
+    gitInit(): ResultPromise;
+    /**
+     * Writes the project files to disk.
+     */
+    write(): Promise<void>;
     /**
      * Changes a directory from inside the project.
      */
     chdir(): Promise<void>;
     /**
      * Correctly disposes of the project, observing when the directory has been changed.
-     *
      * @returns {void}
      */
     dispose(): void;
 }
 
+/**
+ * Options for configuring the bin tester.
+ */
 interface BinTesterOptions<TProject> {
     /**
      * The absolute path to the bin to invoke
@@ -43,23 +47,37 @@ interface BinTesterOptions<TProject> {
      */
     createProject?: () => Promise<TProject>;
 }
+/**
+ * Function signature for running the configured CLI binary.
+ */
 interface RunBin {
     /**
      * A runBin implementation that takes no parameters.
-     *
-     * @returns {*}  {execa.ExecaChildProcess<string>}
-     * @memberof RunBin
+     * @returns {*}  {ResultPromise}
+     */
+    (): ResultPromise;
+    /**
+     * A runBin implementation that takes string varargs.
+     * @param {...RunBinArgs} args
+     * @returns {*}  {ResultPromise}
+     */
+    (...args: [...binArgs: string[]]): ResultPromise;
+    /**
+     * A runBin implementation that takes an Options object.
+     * @param {...RunBinArgs} args
+     * @returns {*}  {ResultPromise}
      */
-    (): execa.ExecaChildProcess<string>;
+    (...args: [execaOptions: Options]): ResultPromise;
     /**
-     * A runBin implementation that takes varargs.
-     *
+     * A runBin implementation that takes string or an Options object varargs.
      * @param {...RunBinArgs} args
-     * @returns {*}  {execa.ExecaChildProcess<string>}
-     * @memberof RunBin
+     * @returns {*}  {ResultPromise}
      */
-    (...args: RunBinArgs): execa.ExecaChildProcess<string>;
+    (...args: [...binArgs: string[], execaOptions: Options]): ResultPromise;
 }
+/**
+ * The result returned by createBinTester.
+ */
 interface CreateBinTesterResult<TProject extends BinTesterProject> {
     /**
      * Runs the configured bin function via execa.
@@ -74,17 +92,21 @@ interface CreateBinTesterResult<TProject extends BinTesterProject> {
      */
     setupTmpDir: () => Promise<string>;
     /**
-     * Tears the project down, ensuring the tmp directory is removed. Shoud be paired with setupProject.
+     * Tears the project down, ensuring the tmp directory is removed.
+     * When BIN_TESTER_DEBUG is set, fixtures are preserved for inspection.
      */
     teardownProject: () => void;
+    /**
+     * Runs the configured bin with Node inspector enabled in attach mode (--inspect).
+     * Set BIN_TESTER_DEBUG=break to break on first line instead.
+     */
+    runBinDebug: RunBin;
 }
-declare type RunBinArgs = [...binArgs: string[], execaOptions: execa.Options<string>];
 /**
  * Creates the bin tester API functions to use within tests.
- *
  * @param {BinTesterOptions<TProject>} options - An object of bin tester options
  * @returns {CreateBinTesterResult<TProject>} - A project instance.
  */
 declare function createBinTester<TProject extends BinTesterProject>(options: BinTesterOptions<TProject>): CreateBinTesterResult<TProject>;
 
-export { BinTesterProject, createBinTester };
+export { type BinTesterOptions, BinTesterProject, type CreateBinTesterResult, type RunBin, createBinTester };

package/dist/index.js

@@ -1,28 +1,17 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropSymbols = Object.getOwnPropertySymbols;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __propIsEnum = Object.prototype.propertyIsEnumerable;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __spreadValues = (a, b) => {
-  for (var prop in b || (b = {}))
-    if (__hasOwnProp.call(b, prop))
-      __defNormalProp(a, prop, b[prop]);
-  if (__getOwnPropSymbols)
-    for (var prop of __getOwnPropSymbols(b)) {
-      if (__propIsEnum.call(b, prop))
-        __defNormalProp(a, prop, b[prop]);
-    }
-  return a;
-};
-
 // src/create-bin-tester.ts
-import execa2 from "execa";
+import { execaNode } from "execa";
 
 // src/project.ts
-import execa from "execa";
+import { execa } from "execa";
 import { Project } from "fixturify-project";
 var ROOT = process.cwd();
 var BinTesterProject = class extends Project {
+  /**
+   * Constructs an instance of a BinTesterProject.
+   * @param {string} name - The name of the project. Used within the package.json as the name property.
+   * @param {string} version - The version of the project. Used within the package.json as the version property.
+   * @param {Function} cb - An optional callback for additional setup steps after the project is constructed.
+   */
   constructor(name = "fake-project", version, cb) {
     super(name, version, cb);
     this._dirChanged = false;
@@ -32,14 +21,31 @@ var BinTesterProject = class extends Project {
       repository: "http://fakerepo.com"
     });
   }
+  /**
+   * Runs `git init` inside a project.
+   * @returns {*} {ResultPromise}
+   */
   gitInit() {
-    return execa(`git init -q ${this.baseDir}`);
+    return execa("git", ["init", "-q", this.baseDir]);
   }
+  /**
+   * Writes the project files to disk.
+   */
+  async write() {
+    return super.write();
+  }
+  /**
+   * Changes a directory from inside the project.
+   */
   async chdir() {
     this._dirChanged = true;
     await this.write();
     process.chdir(this.baseDir);
   }
+  /**
+   * Correctly disposes of the project, observing when the directory has been changed.
+   * @returns {void}
+   */
   dispose() {
     if (this._dirChanged) {
       process.chdir(ROOT);
@@ -54,28 +60,59 @@ var DEFAULT_BIN_TESTER_OPTIONS = {
 };
 function parseArgs(args) {
   if (args.length > 0 && typeof args[args.length - 1] === "object") {
-    const execaOptions = args.pop();
+    const argsCopy = [...args];
+    const execaOptions = argsCopy.pop();
     return {
-      args,
+      args: argsCopy,
       execaOptions
     };
   } else {
     return {
-      args,
+      args: [...args],
       execaOptions: {}
     };
   }
 }
 function createBinTester(options) {
   let project;
-  const mergedOptions = __spreadValues(__spreadValues({}, DEFAULT_BIN_TESTER_OPTIONS), options);
+  const mergedOptions = {
+    ...DEFAULT_BIN_TESTER_OPTIONS,
+    ...options
+  };
   function runBin(...args) {
     const mergedRunOptions = parseArgs(args);
     const binPath = typeof mergedOptions.binPath === "function" ? mergedOptions.binPath(project) : mergedOptions.binPath;
-    return execa2(process.execPath, [binPath, ...mergedOptions.staticArgs, ...mergedRunOptions.args], __spreadValues({
+    const optionsEnv = mergedRunOptions.execaOptions.env;
+    const debugEnv = optionsEnv?.BIN_TESTER_DEBUG ?? process.env.BIN_TESTER_DEBUG;
+    const nodeOptions = [];
+    if (debugEnv && debugEnv !== "0" && debugEnv.toLowerCase() !== "false") {
+      if (debugEnv.toLowerCase() === "break") {
+        nodeOptions.push("--inspect-brk=0");
+      } else {
+        nodeOptions.push("--inspect=0");
+      }
+      console.log(`[bin-tester] Debugging enabled. Fixture: ${project.baseDir}`);
+    }
+    const resolvedCwd = mergedRunOptions.execaOptions.cwd ?? project.baseDir;
+    return execaNode(binPath, [...mergedOptions.staticArgs, ...mergedRunOptions.args], {
       reject: false,
-      cwd: project.baseDir
-    }, mergedRunOptions.execaOptions));
+      cwd: resolvedCwd,
+      nodeOptions,
+      ...mergedRunOptions.execaOptions
+    });
+  }
+  function runBinDebug(...args) {
+    const parsedArgs = parseArgs(args);
+    const debugEnv = process.env.BIN_TESTER_DEBUG || "attach";
+    parsedArgs.execaOptions = {
+      ...parsedArgs.execaOptions,
+      env: {
+        ...parsedArgs.execaOptions.env,
+        BIN_TESTER_DEBUG: debugEnv
+      }
+    };
+    const reconstructedArgs = [...parsedArgs.args, parsedArgs.execaOptions];
+    return runBin(...reconstructedArgs);
   }
   async function setupProject() {
     project = "createProject" in mergedOptions ? await mergedOptions.createProject() : new BinTesterProject();
@@ -89,10 +126,16 @@ function createBinTester(options) {
     return project.baseDir;
   }
   function teardownProject() {
+    const debugEnv = process.env.BIN_TESTER_DEBUG;
+    if (debugEnv && debugEnv !== "0" && debugEnv.toLowerCase() !== "false") {
+      console.log(`[bin-tester] Fixture preserved: ${project.baseDir}`);
+      return;
+    }
     project.dispose();
   }
   return {
     runBin,
+    runBinDebug,
     setupProject,
     teardownProject,
     setupTmpDir

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalvert/bin-tester",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "A test harness to invoke a CLI in a tmp directory",
   "keywords": [
     "cli",
@@ -18,9 +18,9 @@
   "type": "module",
   "exports": {
     ".": {
-      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.cjs"
     }
   },
   "main": "./dist/index.cjs",
@@ -28,8 +28,12 @@
   "types": "./dist/index.d.ts",
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
-    "docs:generate": "readme-api-generator ./src --ts",
-    "lint": "eslint .",
+    "docs": "typedoc",
+    "docs:check": "markdown-code check",
+    "docs:sync": "markdown-code sync",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint . && npm run format:check && npm run docs:check",
     "prepublishOnly": "npm run build",
     "test": "npm run lint && npm run test:vitest",
     "test:vitest": "vitest run",
@@ -40,36 +44,37 @@
     "dist"
   ],
   "dependencies": {
-    "execa": "^5.1.1",
-    "fixturify-project": "^5.0.2"
+    "execa": "^9.6.1",
+    "fixturify-project": "^7.1.3"
   },
   "devDependencies": {
-    "@babel/plugin-proposal-class-properties": "^7.16.7",
-    "@babel/plugin-proposal-object-rest-spread": "^7.17.3",
-    "@babel/plugin-transform-typescript": "^7.16.8",
-    "@babel/preset-env": "^7.16.11",
-    "@babel/preset-typescript": "^7.16.7",
-    "@scalvert/readme-api-generator": "^0.2.4",
-    "@typescript-eslint/eslint-plugin": "^5.14.0",
-    "@typescript-eslint/parser": "^5.14.0",
-    "eslint": "^8.10.0",
-    "eslint-config-prettier": "^8.5.0",
-    "eslint-plugin-jsdoc": "^38.0.4",
+    "@babel/plugin-proposal-class-properties": "^7.18.6",
+    "@babel/plugin-proposal-object-rest-spread": "^7.20.7",
+    "@babel/plugin-transform-typescript": "^7.27.0",
+    "@babel/preset-env": "^7.26.9",
+    "@babel/preset-typescript": "^7.27.0",
+    "@release-it-plugins/lerna-changelog": "^8.0.1",
+    "@typescript-eslint/eslint-plugin": "^8.29.1",
+    "@typescript-eslint/parser": "^8.29.1",
+    "eslint": "^9.24.0",
+    "eslint-config-prettier": "^10.1.2",
+    "eslint-plugin-jsdoc": "^61.5.0",
     "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-prettier": "^4.0.0",
-    "eslint-plugin-unicorn": "^41.0.0",
-    "fixturify": "^2.1.1",
-    "prettier": "^2.5.1",
-    "release-it": "^14.2.1",
-    "release-it-lerna-changelog": "^3.1.0",
-    "tsup": "^5.12.0",
-    "type-fest": "^2.12.0",
-    "typescript": "^4.6.2",
-    "vite": "^2.8.6",
-    "vitest": "^0.9.3"
+    "eslint-plugin-prettier": "^5.2.6",
+    "eslint-plugin-unicorn": "^62.0.0",
+    "fixturify": "^3.0.0",
+    "markdown-code": "^0.6.1",
+    "prettier": "^3.5.3",
+    "release-it": "^19.2.2",
+    "tsup": "^8.4.0",
+    "type-fest": "^5.3.1",
+    "typedoc": "^0.28.15",
+    "typescript": "^5.8.3",
+    "vite": "^7.3.0",
+    "vitest": "^4.0.16"
   },
   "engines": {
-    "node": "^12.22.0 || >=14"
+    "node": ">=22"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -77,7 +82,7 @@
   },
   "release-it": {
     "plugins": {
-      "release-it-lerna-changelog": {
+      "@release-it-plugins/lerna-changelog": {
         "infile": "CHANGELOG.md",
         "launchEditor": true
       }
@@ -89,9 +94,5 @@
       "release": true,
       "tokenRef": "GITHUB_AUTH"
     }
-  },
-  "volta": {
-    "node": "14.19.0",
-    "npm": "8.5.3"
   }
 }