feat(shell): Mock mode for sh

I want to control the results from `sh` calls in order to test different
paths through a script without changing my system configuration.

Author: seb-cr

README.md

@@ -102,3 +102,40 @@ await withYamlFile('example.yaml', (f) => {
   f.setIn(['foo', 'bar', 'baz'], 42);
 });
 ```
+
+## Test helpers
+
+### `sh.mock()`
+
+`sh` has a mock mode that allows you to control its output, which can be useful when testing scripts. Activate it using `sh.mock()`. This returns an object with methods to control `sh` behaviour. You can provide sequential mock results to return, either as default (ignoring the command being run) or matching to a specific command.
+
+When you're done, use `sh.restore()` to stop mocking.
+
+```ts
+// activate mock mode
+const mock = sh.mock();
+
+// add some default mocks
+mock.returns({ stdout: 'first call' });
+mock.returns({ stdout: 'second call' });
+
+// add some command-specific mocks
+mock.command('cat file.txt').returns({ stdout: 'file contents' });
+mock.command(/echo/).returns({ stdout: 'mock echo' });
+
+await sh('some arbitrary command');
+// => 'first call'
+
+await sh('some arbitrary command');
+// => 'second call'
+
+await sh('echo "hi there"');
+// => 'mock echo'
+
+await sh('cat file.txt');
+// => 'file contents'
+
+// assert that all expected `sh` calls were made
+mock.assertDone();
+sh.restore();
+```

src/regex.ts

@@ -16,6 +16,9 @@ export function escapeRegex(string: string): string {
 /**
  * Turns a `string | RegExp` into a RegExp.
  *
+ * If `value` is a string, the returned RegExp will match `value` anywhere in
+ * the target string.
+ *
  * @param value
  */
 export function regex(value: string | RegExp): RegExp {
@@ -24,6 +27,20 @@ export function regex(value: string | RegExp): RegExp {
     : value;
 }
 
+/**
+ * Turns a `string | RegExp` into a RegExp.
+ *
+ * If `value` is a string, the returned RegExp is anchored so that it will only
+ * match if the target string exactly equals `value`.
+ *
+ * @param value
+ */
+export function anchoredRegex(value: string | RegExp): RegExp {
+  return typeof value === 'string'
+    ? new RegExp(`^${escapeRegex(value)}$`)
+    : value;
+}
+
 /**
  * Turns a search value (string or RegExp) into a global RegExp.
  *

src/shell.ts

@@ -1,6 +1,8 @@
 import { ExecOptions, exec as execWithCallback } from 'child_process';
 import { promisify } from 'util';
 
+import { escapeRegex } from './regex';
+
 /**
  * Promisified version of `child_process.exec`.
  *
@@ -21,6 +23,11 @@ import { promisify } from 'util';
  */
 export const exec = promisify(execWithCallback);
 
+/**
+ * `exec` function used by `sh`. This is mutable to allow faking.
+ */
+let shExec: (command: string, options?: ExecOptions) => Promise<{ stdout: string; stderr: string; }> = exec;
+
 /**
  * Options for `sh`.
  */
@@ -47,14 +54,178 @@ export type ShOptions = ExecOptions & {
  * // => 'hello\n'
  * ```
  *
+ * `sh` has a mock mode that allows you to control its output, which can be
+ * useful when testing scripts. Activate it using `sh.mock()`.
+ *
  * @param command The command to run.
  * @param options Options to be passed to `exec`.
  */
 export async function sh(command: string, options?: ShOptions): Promise<string> {
-  const result = await exec(command, options);
+  const result = await shExec(command, options);
   let output = result.stdout.toString();
   if (options?.trim ?? true) {
     output = output.trim();
   }
   return output;
 }
+
+export interface MockShCommandController {
+  /**
+   * Adds a new command-specific mock result.
+   *
+   * @param mock The mock result.
+   * @param [mock.exitCode] The mock process exit code.
+   * @param [mock.stdout] The mock stdout output.
+   * @param [mock.stderr] The mock stderr output.
+   */
+  returns(mock: { exitCode?: number, stdout?: string, stderr?: string }): MockShCommandController;
+}
+
+export interface MockShController {
+  /**
+   * Adds a new default mock result.
+   *
+   * @param mock The mock result.
+   * @param [mock.exitCode] The mock process exit code.
+   * @param [mock.stdout] The mock stdout output.
+   * @param [mock.stderr] The mock stderr output.
+   */
+  returns(mock: { exitCode?: number, stdout?: string, stderr?: string }): MockShController;
+
+  /**
+   * Adds a command matcher.
+   *
+   * @param command The command to match.
+   */
+  command(command: string | RegExp): MockShCommandController;
+
+  /**
+   * Asserts that a corresponding `sh` call was made for each mock.
+   *
+   * Throws if there are mocks that haven't been used.
+   */
+  assertDone(): void;
+
+  /**
+   * Removes all mocks.
+   *
+   * `sh` remains in mock mode. To restore it, use `sh.restore()`.
+   */
+  reset(): void;
+}
+
+/**
+ * Start mocking `sh`.
+ *
+ * Returns an object with methods to control `sh` behaviour. You can provide
+ * sequential mock results to return, either as default (ignoring the command
+ * being run) or matching to a specific command.
+ *
+ * When you're done, use `sh.restore()` to stop mocking.
+ *
+ * ```ts
+ * // activate mock mode
+ * const mock = sh.mock();
+ *
+ * // add some default mocks
+ * mock.returns({ stdout: 'first call' });
+ * mock.returns({ stdout: 'second call' });
+ *
+ * // add some command-specific mocks
+ * mock.command('cat file.txt').returns({ stdout: 'file contents' });
+ * mock.command(/echo/).returns({ stdout: 'mock echo' });
+ *
+ * await sh('some arbitrary command');
+ * // => 'first call'
+ *
+ * await sh('some arbitrary command');
+ * // => 'second call'
+ *
+ * await sh('echo "hi there"');
+ * // => 'mock echo'
+ *
+ * await sh('cat file.txt');
+ * // => 'file contents'
+ *
+ * // assert that all expected `sh` calls were made
+ * mock.assertDone();
+ * sh.restore();
+ * ```
+ */
+sh.mock = () => {
+  if (shExec !== exec) {
+    throw new Error('`sh` is already mocked');
+  }
+
+  type Mock = { exitCode: number, stdout: string, stderr: string };
+  const matchers: [RegExp, Mock[]][] = [];
+  const defaults: Mock[] = [];
+
+  shExec = async (command) => {
+    const match = matchers.find(([r, m]) => m.length > 0 && r.exec(command));
+    const mock = match ? match[1].shift() : defaults.shift();
+    if (!mock) {
+      throw new Error(`No mock found for command: ${command}`);
+    }
+    if (mock.exitCode !== 0) {
+      throw new Error(`Command failed: ${command}\n${mock.stderr}`);
+    }
+    return { stdout: mock.stdout, stderr: mock.stderr };
+  };
+
+  const mockController: MockShController = {
+    returns(mock: { exitCode?: number, stdout?: string, stderr?: string }) {
+      const {
+        exitCode = 0,
+        stdout = '',
+        stderr = '',
+      } = mock;
+      defaults.push({ exitCode, stdout, stderr });
+      return mockController;
+    },
+
+    command(command: string | RegExp) {
+      const re = typeof command === 'string'
+        ? new RegExp(`^${escapeRegex(command)}$`)
+        : command;
+      const mocks: Mock[] = [];
+      matchers.push([re, mocks]);
+
+      const cmdController: MockShCommandController = {
+        returns(mock: { exitCode?: number, stdout?: string, stderr?: string }) {
+          const {
+            exitCode = 0,
+            stdout = '',
+            stderr = '',
+          } = mock;
+          mocks.push({ exitCode, stdout, stderr });
+          return cmdController;
+        },
+      };
+      return cmdController;
+    },
+
+    assertDone() {
+      if (
+        defaults.length > 0
+        || matchers.some(([, unconsumed]) => unconsumed.length > 0)
+      ) {
+        throw new Error('Some `sh` mocks were not used');
+      }
+    },
+
+    reset() {
+      matchers.splice(0, matchers.length);
+      defaults.splice(0, defaults.length);
+    },
+  };
+
+  return mockController;
+};
+
+/**
+ * Stop mocking `sh`.
+ */
+sh.restore = () => {
+  shExec = exec;
+};

tests/shell.spec.ts

@@ -36,3 +36,123 @@ describe('sh', () => {
     });
   });
 });
+
+describe('sh mock mode', () => {
+  afterEach(() => sh.restore());
+
+  describe('the example in the JSDoc', () => {
+    it('should work as demonstrated', async () => {
+      const mock = sh.mock();
+
+      mock.returns({ stdout: 'First call' });
+      mock.returns({ stdout: 'Second call' });
+
+      mock.command('cat file.txt').returns({ stdout: 'file contents' });
+      mock.command(/echo/).returns({ stdout: 'mock echo!' });
+
+      let result = await sh('some arbitrary command');
+      expect(result).to.equal('First call');
+
+      result = await sh('some arbitrary command');
+      expect(result).to.equal('Second call');
+
+      result = await sh('echo "hi there"');
+      expect(result).to.equal('mock echo!');
+
+      result = await sh('cat file.txt');
+      expect(result).to.equal('file contents');
+
+      mock.assertDone();
+      sh.restore();
+    });
+  });
+
+  describe('sh.mock', () => {
+    it('should throw if called twice', () => {
+      sh.mock();
+      expect(() => sh.mock()).to.throw('`sh` is already mocked');
+    });
+  });
+
+  describe('default mocks', () => {
+    it('should return the mock results in order', async () => {
+      sh.mock()
+        .returns({ stdout: 'first' })
+        .returns({ stdout: 'second' });
+
+      let result = await sh('blah');
+      expect(result).to.equal('first');
+
+      result = await sh('blah');
+      expect(result).to.equal('second');
+    });
+
+    it('should throw if `sh` is called without a mock', async () => {
+      sh.mock();
+
+      await expect(sh('blah')).to.eventually.be.rejectedWith(
+        'No mock found for command: blah',
+      );
+    });
+  });
+
+  describe('matching mocks', () => {
+    it('should return the mock results for the matching command', async () => {
+      const mock = sh.mock();
+      mock.command('a')
+        .returns({ stdout: 'first a' })
+        .returns({ stdout: 'second a' });
+      mock.command('b')
+        .returns({ stdout: 'first b' })
+        .returns({ stdout: 'second b' });
+
+      let result = await sh('a');
+      expect(result).to.equal('first a');
+
+      result = await sh('b');
+      expect(result).to.equal('first b');
+
+      result = await sh('a');
+      expect(result).to.equal('second a');
+
+      result = await sh('b');
+      expect(result).to.equal('second b');
+    });
+
+    it("should fall back to default mock if command doesn't match", async () => {
+      sh.mock()
+        .returns({ stdout: 'default' })
+        .command('a').returns({ stdout: 'matched' });
+
+      const result = await sh('blah');
+      expect(result).to.equal('default');
+    });
+  });
+
+  describe('assertDone', () => {
+    it('should do nothing if all mocks were used', async () => {
+      const mock = sh.mock().returns({ stdout: 'test' });
+      await sh('blah');
+      mock.assertDone();
+    });
+
+    it('should throw if some mocks were not used', () => {
+      const mock = sh.mock().returns({ stdout: 'test' });
+      expect(() => mock.assertDone()).to.throw();
+    });
+  });
+
+  describe('reset', () => {
+    it('should clear out any existing mocks', async () => {
+      const mock = sh.mock();
+      mock.returns({ stdout: 'test' });
+      mock.command('blah').returns({ stdout: 'test' });
+
+      mock.reset();
+      mock.returns({ stdout: 'new' });
+
+      const result = await sh('blah');
+      expect(result).to.equal('new');
+    });
+  });
+});