@scalvert/bin-tester 0.0.4

package/README.md

@@ -0,0 +1,100 @@
+# @scalvert/bin-tester
+
+![CI Build](https://github.com/scalvert/bin-tester/workflows/CI%20Build/badge.svg)
+[![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.
+
+## 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', () => {
+    const result = await runBin();
+
+    expect(result.stdout).toBe('Did some stuff');
+  });
+
+  // Write a file with contents to the tmp directory
+  test('another test', () => {
+    project.write({
+      '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
+    });
+
+    expect(result.stdout).toBe('Read "some/file.txt"');
+  });
+});
+```
+
+## API
+
+```ts
+class BinTesterProject extends Project {
+    private _dirChanged;
+    constructor(name: string, version?: string, cb?: (project: Project) => void);
+    gitInit(): execa.ExecaChildProcess<string>;
+    chdir(): void;
+    dispose(): void;
+}
+
+interface BinTesterOptions {
+    binPath: string;
+    projectConstructor?: any;
+}
+
+interface RunOptions {
+    args?: string[];
+    execaOptions?: execa.Options<string>;
+}
+
+interface createBinTesterResult<TProject extends BinTesterProject> {
+    runBin: (runOptions?: RunOptions) => execa.ExecaChildProcess<string>;
+    setupProject: () => Promise<TProject>;
+    setupTmpDir: () => Promise<string>;
+    teardownProject: () => void;
+}
+
+function createBinTester<TProject extends BinTesterProject>(options: BinTesterOptions): createBinTesterResult<TProject>;
+```

package/dist/index.cjs

@@ -0,0 +1,126 @@
+var __create = Object.create;
+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 __markAsModule = (target) => __defProp(target, "__esModule", { value: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __reExport = (target, module2, copyDefault, desc) => {
+  if (module2 && typeof module2 === "object" || typeof module2 === "function") {
+    for (let key of __getOwnPropNames(module2))
+      if (!__hasOwnProp.call(target, key) && (copyDefault || key !== "default"))
+        __defProp(target, key, { get: () => module2[key], enumerable: !(desc = __getOwnPropDesc(module2, key)) || desc.enumerable });
+  }
+  return target;
+};
+var __toESM = (module2, isNodeMode) => {
+  return __reExport(__markAsModule(__defProp(module2 != null ? __create(__getProtoOf(module2)) : {}, "default", !isNodeMode && module2 && module2.__esModule ? { get: () => module2.default, enumerable: true } : { value: module2, enumerable: true })), module2);
+};
+var __toCommonJS = /* @__PURE__ */ ((cache) => {
+  return (module2, temp) => {
+    return cache && cache.get(module2) || (temp = __reExport(__markAsModule({}), module2, 1), cache && cache.set(module2, temp), temp);
+  };
+})(typeof WeakMap !== "undefined" ? /* @__PURE__ */ new WeakMap() : 0);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  BinTesterProject: () => BinTesterProject,
+  createBinTester: () => createBinTester
+});
+
+// src/create-bin-tester.ts
+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 ROOT = process.cwd();
+var BinTesterProject = class extends import_fixturify_project.Project {
+  constructor(name = "fake-project", version, cb) {
+    super(name, version, cb);
+    this._dirChanged = false;
+    this.pkg = Object.assign({}, this.pkg, {
+      license: "MIT",
+      description: "Fake project",
+      repository: "http://fakerepo.com"
+    });
+  }
+  gitInit() {
+    return (0, import_execa.default)(`git init -q ${this.baseDir}`);
+  }
+  chdir() {
+    this._dirChanged = true;
+    process.chdir(this.baseDir);
+  }
+  dispose() {
+    if (this._dirChanged) {
+      process.chdir(ROOT);
+    }
+    return super.dispose();
+  }
+};
+
+// src/create-bin-tester.ts
+var DEFAULT_BIN_TESTER_OPTIONS = {
+  staticArgs: [],
+  projectConstructor: BinTesterProject
+};
+var DEFAULT_RUN_OPTIONS = {
+  args: [],
+  execaOptions: {}
+};
+function createBinTester(options) {
+  let project;
+  const mergedOptions = __spreadValues(__spreadValues({}, DEFAULT_BIN_TESTER_OPTIONS), options);
+  function runBin(runOptions = DEFAULT_RUN_OPTIONS) {
+    return (0, import_execa2.default)(process.execPath, [mergedOptions.binPath, ...mergedOptions.staticArgs, ...runOptions.args], __spreadValues({
+      reject: false,
+      cwd: project.baseDir
+    }, runOptions.execaOptions));
+  }
+  async function setupProject() {
+    project = new mergedOptions.projectConstructor();
+    await project.write();
+    return project;
+  }
+  async function setupTmpDir() {
+    if (typeof project === "undefined") {
+      await setupProject();
+    }
+    return project.baseDir;
+  }
+  function teardownProject() {
+    project.dispose();
+  }
+  return {
+    runBin,
+    setupProject,
+    teardownProject,
+    setupTmpDir
+  };
+}
+module.exports = __toCommonJS(src_exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BinTesterProject,
+  createBinTester
+});

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+import execa from 'execa';
+import { Project } from 'fixturify-project';
+
+declare class BinTesterProject extends Project {
+    private _dirChanged;
+    constructor(name?: string, version?: string, cb?: (project: Project) => void);
+    gitInit(): execa.ExecaChildProcess<string>;
+    chdir(): void;
+    dispose(): void;
+}
+
+interface BinTesterOptions {
+    /**
+     * The absolute path to the bin to invoke
+     */
+    binPath: string;
+    /**
+     * An array of static arguments that will be used every time when running the bin
+     */
+    staticArgs?: string[];
+    /**
+     * An optional class to use to create the project
+     */
+    projectConstructor?: any;
+}
+interface RunOptions {
+    /**
+     * Arguments to provide to the bin script.
+     */
+    args: string[];
+    /**
+     * Options to provide to execa. @see https://github.com/sindresorhus/execa#options
+     */
+    execaOptions?: execa.Options<string>;
+}
+interface CreateBinTesterResult<TProject extends BinTesterProject> {
+    runBin: (runOptions?: RunOptions) => execa.ExecaChildProcess<string>;
+    setupProject: () => Promise<TProject>;
+    setupTmpDir: () => Promise<string>;
+    teardownProject: () => void;
+}
+/**
+ * Creates the bin tester API functions to use within tests.
+ *
+ * @param options - An object of bin tester options
+ * @returns - A project instance.
+ */
+declare function createBinTester<TProject extends BinTesterProject>(options: BinTesterOptions): CreateBinTesterResult<TProject>;
+
+export { BinTesterProject, createBinTester };

package/dist/index.js

@@ -0,0 +1,92 @@
+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";
+
+// src/project.ts
+import execa from "execa";
+import { Project } from "fixturify-project";
+var ROOT = process.cwd();
+var BinTesterProject = class extends Project {
+  constructor(name = "fake-project", version, cb) {
+    super(name, version, cb);
+    this._dirChanged = false;
+    this.pkg = Object.assign({}, this.pkg, {
+      license: "MIT",
+      description: "Fake project",
+      repository: "http://fakerepo.com"
+    });
+  }
+  gitInit() {
+    return execa(`git init -q ${this.baseDir}`);
+  }
+  chdir() {
+    this._dirChanged = true;
+    process.chdir(this.baseDir);
+  }
+  dispose() {
+    if (this._dirChanged) {
+      process.chdir(ROOT);
+    }
+    return super.dispose();
+  }
+};
+
+// src/create-bin-tester.ts
+var DEFAULT_BIN_TESTER_OPTIONS = {
+  staticArgs: [],
+  projectConstructor: BinTesterProject
+};
+var DEFAULT_RUN_OPTIONS = {
+  args: [],
+  execaOptions: {}
+};
+function createBinTester(options) {
+  let project;
+  const mergedOptions = __spreadValues(__spreadValues({}, DEFAULT_BIN_TESTER_OPTIONS), options);
+  function runBin(runOptions = DEFAULT_RUN_OPTIONS) {
+    return execa2(process.execPath, [mergedOptions.binPath, ...mergedOptions.staticArgs, ...runOptions.args], __spreadValues({
+      reject: false,
+      cwd: project.baseDir
+    }, runOptions.execaOptions));
+  }
+  async function setupProject() {
+    project = new mergedOptions.projectConstructor();
+    await project.write();
+    return project;
+  }
+  async function setupTmpDir() {
+    if (typeof project === "undefined") {
+      await setupProject();
+    }
+    return project.baseDir;
+  }
+  function teardownProject() {
+    project.dispose();
+  }
+  return {
+    runBin,
+    setupProject,
+    teardownProject,
+    setupTmpDir
+  };
+}
+export {
+  BinTesterProject,
+  createBinTester
+};

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@scalvert/bin-tester",
+  "version": "0.0.4",
+  "description": "A test harness to invoke a CLI in a tmp directory",
+  "keywords": [
+    "cli",
+    "fake",
+    "project",
+    "test",
+    "harness"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scalvert/bin-tester.git"
+  },
+  "license": "MIT",
+  "author": "Steve Calvert <steve.calvert@gmail.com>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "docs:generate": "npm run build && readme-api-generator dist/index.js",
+    "lint": "eslint .",
+    "prepublishOnly": "npm run build",
+    "test": "npm run lint && vitest run",
+    "test:watch": "vitest",
+    "watch": "npm run build -- --watch src"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "execa": "^5.1.1",
+    "fixturify-project": "^4.1.0"
+  },
+  "devDependencies": {
+    "@scalvert/readme-api-generator": "^0.1.0",
+    "@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-node": "^11.1.0",
+    "eslint-plugin-prettier": "^4.0.0",
+    "eslint-plugin-tsdoc": "^0.2.14",
+    "eslint-plugin-unicorn": "^41.0.0",
+    "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.6.0"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "release-it": {
+    "plugins": {
+      "release-it-lerna-changelog": {
+        "infile": "CHANGELOG.md",
+        "launchEditor": true
+      }
+    },
+    "git": {
+      "tagName": "v${version}"
+    },
+    "github": {
+      "release": true,
+      "tokenRef": "GITHUB_AUTH"
+    }
+  },
+  "volta": {
+    "node": "14.19.0",
+    "npm": "8.5.3"
+  }
+}