How to unit test a script?

[gaggle]

Let's say we have this super simple script that just calls ls:

example.mjs

#!/usr/bin/env zx
const result = await $`ls -lha`
console.log(result.stdout)

How may I test that this script actually calls ls -lha? How can I test the output is rendered correctly?

In the real world I'm looking to test various calls and logic like git ... commands whose result are parsed and accumulated in various ways, but I think my question fundamentally boils down to how I can test anything at all. The bane of my existence has been effectively untestable Bash scripts, so I'm hoping to take a leap forward in maintainability with zx.

[gaggle]

Inspirationally, I suppose I'm hoping to write tests that could look like this:

describe("example.mjs", () => {
  it("calls `ls` with expected args", async () => {
    const stub = jest.fn()
    somehowRunScriptUnderTest("./example.mjs", { shell: stub })
    expect(stub).toHaveBeenCalledWith("ls -lha")
  })

  it("formats the output", async () => {
    const result = somehowRunScriptUnderTest("./example.mjs", {
      shell: jest.fn(() => `
Permissions Size User     Date Modified Name
drwxr-xr-x     - user 16 Jun 21:59  .
drwxr-xr-x     - user  7 Jun 17:30  ..
drwxr-xr-x     - user 16 Jun 21:59  foo
drwxr-xr-x     - user 27 May 14:53  bar
`),
    })
    expect(result.stdout).toEqual(`
Permissions Size User     Date Modified Name
drwxr-xr-x     - user 16 Jun 21:59  .
drwxr-xr-x     - user  7 Jun 17:30  ..
drwxr-xr-x     - user 16 Jun 21:59  foo
drwxr-xr-x     - user 27 May 14:53  bar
`)
  })
})

I'm no-doubt handwaving away important details in this pseudo-code, but just adding it here to explain my direction and intent with my question. I'm actually happy to pursue whatever approach zx supports and suggests.

[antonmedv]

You can use $.shell config for this. Override this function with a mock.

[gaggle]

That sounds really promising @antonmedv! 🙏

Can you elaborate on how $.shell can be set to a mock? I know I can call a script ala zx --shell=sh example.mjs, but you seem to indicate there's a way to invoke a script such that shell can be a stub?

As an example here's a uvu test that runs example.mjs and checks the result, using a stubbed call to ls.:

example.test.mjs

import "zx/globals"
import * as assert from 'uvu/assert'
import sinon from "sinon"
import { suite } from 'uvu'

const test = suite("example.mjs")

test("formats the output", async () => {
  const stub = sinon.stub(() => `
Permissions Size User     Date Modified Name
drwxr-xr-x     - user 16 Jun 21:59  .
drwxr-xr-x     - user  7 Jun 17:30  ..
drwxr-xr-x     - user 16 Jun 21:59  foo
drwxr-xr-x     - user 27 May 14:53  bar
`)

  const result = await $`zx --shell=${stub} example.mjs`

  assert.equal(result.stdout, `
Permissions Size User     Date Modified Name
drwxr-xr-x     - user 16 Jun 21:59  .
drwxr-xr-x     - user  7 Jun 17:30  ..
drwxr-xr-x     - user 16 Jun 21:59  foo
drwxr-xr-x     - user 27 May 14:53  bar
`)
})

test.run()

This doesn't work because the stub object is passed into zx as a string, which of course doesn't respond properly. I'm sure I'm not understanding what you wrote, but can you elaborate how we may pass in the stub?

[antonmedv]

@antongolub

[dibleauzah]

Hello.

Sorry for the unhelpfulness / mundane-ness, so to speak. I just wanted to give you a kudos for this task.

And just to share something (-...interesting, IMHO [lol]): guess how I found your (/this GH-) page? Voila--please see the attached pic.

I was testing my cell-tower personal-hotspot-based connection in...(drumrolls)...land of Idi Amin, Uganda! 🤣

BUT...I am now really curious to know if and how you actually solved the problem! I guess I need to read on to find that out. Again, kudos!

Respectfully,
...
A Humble Fellow Coder /
Seif Sekalala.

[kurtaking]

You can use $.shell config for this. Override this function with a mock.

@antonmedv, can you provide an example of how to do this?

[cmaster11]

Latecomer to the discussion, I had success with this half-baked mocking using vitest:

import { describe, expect, test, vi } from 'vitest';
import type { ProcessPromise } from 'zx';
import { ProcessOutput } from 'zx';

// Needed for easy type-checking, very hackish
interface ProcessPromisePublic {
  _stage: ProcessPromise['_stage'];
  _reject: ProcessPromise['_reject'];
  _resolve: ProcessPromise['_resolve'];
  _from: ProcessPromise['_from'];
}

function resolveProcessPromise(
  promise: ProcessPromise,
  opts:
    | {
        stdout: string;
      }
    | Error,
) {
  const promisePublic = promise as never as ProcessPromisePublic;

  const output = new ProcessOutput({
    code: opts instanceof Error ? 1 : 0,
    signal: null,
    error: null,
    duration: 0,
    store: {
      stdout: 'stdout' in opts ? [opts.stdout] : [],
      stderr: opts instanceof Error ? [opts.toString()] : [],
      stdall: [],
    },
    from: promisePublic._from,
  });

  if (!output.ok && !promise.isNothrow()) {
    promisePublic._stage = 'rejected';
    promisePublic._reject(output);
  } else {
    promisePublic._stage = 'fulfilled';
    promisePublic._resolve(output);
  }
}

const mocks = vi.hoisted(function () {
  const run = vi.fn(async function (this: ProcessPromise) {
    switch (this.cmd) {
      // Define here all possible commands
      case 'my-command':
        resolveProcessPromise(this, {
          stdout: 'This is the stdout of my command',
        });
        break;
      default:
        resolveProcessPromise(
          this,
          // Log all non-implemented tests
          new Error(
            `ProcessPromise.run is not implemented in tests: ${this.cmd}`,
          ),
        );
    }
    return this;
  });

  return {
    run,
  };
});

vi.mock(import('zx'), async (importOriginal) => {
  const { ProcessPromise, ...rest } = await importOriginal();

  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  (ProcessPromise.prototype.run as never as any) = mocks.run;

  return {
    ...rest,
    ProcessPromise,
  };
});

// Then, later run tests as normal and use $`my-command` as usual.
describe('My test', () => {
  test('Runs commands', async () => {
	// Here you use $ as usual, and it will return the custom-defined stdout or error
  })
})