@scalvert/bin-tester 0.0.5 → 0.1.0

package/README.md

@@ -53,15 +53,14 @@ describe('Some tests', () => {
     expect(result.stdout).toBe('Did some stuff');
   });
 
-  // Write a file with contents to the tmp directory
   test('another test', () => {
-    project.write({
+    // Write a file with contents to the tmp directory
+    await project.writeJSON({
       'some/file.txt': 'some content',
     });
 
-    const result = await runBin({
-      args: ['--path', 'some/file.txt'], // pass some args to the bin that will be used for only this invocation
-    });
+    // 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"');
   });

package/dist/index.cjs

@@ -53,6 +53,7 @@ var import_execa2 = __toESM(require("execa"), 1);
 // src/project.ts
 var import_execa = __toESM(require("execa"), 1);
 var import_fixturify_project = require("fixturify-project");
+var import_deepmerge = __toESM(require("deepmerge"), 1);
 var ROOT = process.cwd();
 var BinTesterProject = class extends import_fixturify_project.Project {
   constructor(name = "fake-project", version, cb) {
@@ -67,13 +68,14 @@ var BinTesterProject = class extends import_fixturify_project.Project {
   gitInit() {
     return (0, import_execa.default)(`git init -q ${this.baseDir}`);
   }
-  chdir() {
+  async chdir() {
     this._dirChanged = true;
+    await this.write();
     process.chdir(this.baseDir);
   }
   writeJSON(dirJSON) {
-    this.files = __spreadValues(__spreadValues({}, this.files), dirJSON);
-    return super.write();
+    this.files = (0, import_deepmerge.default)(this.files, dirJSON);
+    return this.write();
   }
   dispose() {
     if (this._dirChanged) {
@@ -88,22 +90,32 @@ var DEFAULT_BIN_TESTER_OPTIONS = {
   staticArgs: [],
   projectConstructor: BinTesterProject
 };
-var DEFAULT_RUN_OPTIONS = {
-  args: [],
-  execaOptions: {}
-};
+function parseArgs(args) {
+  if (args.length > 0 && typeof args[args.length - 1] === "object") {
+    const execaOptions = args.pop();
+    return {
+      args,
+      execaOptions
+    };
+  } else {
+    return {
+      args,
+      execaOptions: {}
+    };
+  }
+}
 function createBinTester(options) {
   let project;
   const mergedOptions = __spreadValues(__spreadValues({}, DEFAULT_BIN_TESTER_OPTIONS), options);
-  function runBin(runOptions = {}) {
-    const mergedRunOptions = __spreadValues(__spreadValues({}, DEFAULT_RUN_OPTIONS), runOptions);
+  function runBin(...args) {
+    const mergedRunOptions = parseArgs(args);
     return (0, import_execa2.default)(process.execPath, [mergedOptions.binPath, ...mergedOptions.staticArgs, ...mergedRunOptions.args], __spreadValues({
       reject: false,
       cwd: project.baseDir
     }, mergedRunOptions.execaOptions));
   }
   async function setupProject() {
-    project = new mergedOptions.projectConstructor();
+    project = "createProject" in mergedOptions ? await mergedOptions.createProject() : new BinTesterProject();
     await project.write();
     return project;
   }

package/dist/index.d.ts

@@ -1,14 +1,39 @@
 import execa from 'execa';
-import { Constructor } from 'type-fest';
 import fixturify from 'fixturify';
 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 {(project: Project) => void} 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 {*} {execa.ExecaChildProcess<string>}
+     */
     gitInit(): execa.ExecaChildProcess<string>;
-    chdir(): void;
+    /**
+     * Changes a directory from inside the project.
+     */
+    chdir(): Promise<void>;
+    /**
+     * Writes a directory struture in the project directory.
+     *
+     * @param {fixturify.DirJSON} dirJSON - A JSON object representing the directory structure to create.
+     * @returns {*} {Promise<void>}
+     */
     writeJSON(dirJSON: fixturify.DirJSON): Promise<void>;
+    /**
+     * Correctly disposes of the project, observing when the directory has been changed.
+     *
+     * @returns {void}
+     */
     dispose(): void;
 }
 
@@ -22,31 +47,52 @@ interface BinTesterOptions<TProject> {
      */
     staticArgs?: string[];
     /**
-     * An optional class to use to create the project
+     * An optional function to use to create the project. Use this if you want to provide a custom implementation of a BinTesterProject.
      */
-    projectConstructor?: Constructor<TProject>;
+    createProject?: () => TProject;
 }
-interface RunOptions {
+interface RunBin {
     /**
-     * Arguments to provide to the bin script.
+     * A runBin implementation that takes no parameters.
+     *
+     * @returns {*}  {execa.ExecaChildProcess<string>}
+     * @memberof RunBin
      */
-    args?: string[];
+    (): execa.ExecaChildProcess<string>;
     /**
-     * Options to provide to execa. @see https://github.com/sindresorhus/execa#options
+     * A runBin implementation that takes varargs.
+     *
+     * @param {...RunBinArgs} args
+     * @returns {*}  {execa.ExecaChildProcess<string>}
+     * @memberof RunBin
      */
-    execaOptions?: execa.Options<string>;
+    (...args: RunBinArgs): execa.ExecaChildProcess<string>;
 }
 interface CreateBinTesterResult<TProject extends BinTesterProject> {
-    runBin: (runOptions?: RunOptions) => execa.ExecaChildProcess<string>;
+    /**
+     * 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. Shoud be paired with setupProject.
+     */
     teardownProject: () => void;
 }
+declare type RunBinArgs = [...binArgs: string[], execaOptions: execa.Options<string>];
 /**
  * Creates the bin tester API functions to use within tests.
  *
- * @param options - An object of bin tester options
- * @returns - A project instance.
+ * @typedef TProject - The type of BinTesterProject used.
+ * @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>;
 

package/dist/index.js

@@ -21,6 +21,7 @@ import execa2 from "execa";
 // src/project.ts
 import execa from "execa";
 import { Project } from "fixturify-project";
+import deepmerge from "deepmerge";
 var ROOT = process.cwd();
 var BinTesterProject = class extends Project {
   constructor(name = "fake-project", version, cb) {
@@ -35,13 +36,14 @@ var BinTesterProject = class extends Project {
   gitInit() {
     return execa(`git init -q ${this.baseDir}`);
   }
-  chdir() {
+  async chdir() {
     this._dirChanged = true;
+    await this.write();
     process.chdir(this.baseDir);
   }
   writeJSON(dirJSON) {
-    this.files = __spreadValues(__spreadValues({}, this.files), dirJSON);
-    return super.write();
+    this.files = deepmerge(this.files, dirJSON);
+    return this.write();
   }
   dispose() {
     if (this._dirChanged) {
@@ -56,22 +58,32 @@ var DEFAULT_BIN_TESTER_OPTIONS = {
   staticArgs: [],
   projectConstructor: BinTesterProject
 };
-var DEFAULT_RUN_OPTIONS = {
-  args: [],
-  execaOptions: {}
-};
+function parseArgs(args) {
+  if (args.length > 0 && typeof args[args.length - 1] === "object") {
+    const execaOptions = args.pop();
+    return {
+      args,
+      execaOptions
+    };
+  } else {
+    return {
+      args,
+      execaOptions: {}
+    };
+  }
+}
 function createBinTester(options) {
   let project;
   const mergedOptions = __spreadValues(__spreadValues({}, DEFAULT_BIN_TESTER_OPTIONS), options);
-  function runBin(runOptions = {}) {
-    const mergedRunOptions = __spreadValues(__spreadValues({}, DEFAULT_RUN_OPTIONS), runOptions);
+  function runBin(...args) {
+    const mergedRunOptions = parseArgs(args);
     return execa2(process.execPath, [mergedOptions.binPath, ...mergedOptions.staticArgs, ...mergedRunOptions.args], __spreadValues({
       reject: false,
       cwd: project.baseDir
     }, mergedRunOptions.execaOptions));
   }
   async function setupProject() {
-    project = new mergedOptions.projectConstructor();
+    project = "createProject" in mergedOptions ? await mergedOptions.createProject() : new BinTesterProject();
     await project.write();
     return project;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalvert/bin-tester",
-  "version": "0.0.5",
+  "version": "0.1.0",
   "description": "A test harness to invoke a CLI in a tmp directory",
   "keywords": [
     "cli",
@@ -39,6 +39,7 @@
     "dist"
   ],
   "dependencies": {
+    "deepmerge": "^4.2.2",
     "execa": "^5.1.1",
     "fixturify-project": "^4.1.0"
   },
@@ -48,9 +49,9 @@
     "@typescript-eslint/parser": "^5.14.0",
     "eslint": "^8.10.0",
     "eslint-config-prettier": "^8.5.0",
+    "eslint-plugin-jsdoc": "^38.0.4",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^4.0.0",
-    "eslint-plugin-tsdoc": "^0.2.14",
     "eslint-plugin-unicorn": "^41.0.0",
     "fixturify": "^2.1.1",
     "prettier": "^2.5.1",