Minimal Test Runner Command Builder

1.7.0 · abandoned · verified Tue Apr 21

The `test-cmd` package is a minimalist Node.js utility designed to facilitate the creation and execution of simple command-line test runners. Released with its latest stable version 1.7.0 over eight years ago, this package is built entirely on CommonJS modules and leverages older dependencies like `optimist` for argument parsing, `tape` for test assertions, and `through` for stream manipulation. Its primary function is to wrap shell commands and integrate them into a testing flow, making it suitable for black-box testing of command-line interfaces. Due to its age and lack of recent maintenance, it does not support modern JavaScript features like ESM or `async/await` and is generally considered superseded by contemporary testing frameworks. It has an infrequent release cadence, with its last update being many years ago, indicating it is no longer actively maintained.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to `require('test-cmd')` in an ECMAScript Module (ESM) context.

fix Change your file to use CommonJS (e.g., by ensuring your `package.json` does not have `"type": "module"`, or changing your file extension to `.cjs`), or use a transpiler like Babel if you must use ESM syntax while consuming CJS modules.
```
TypeError: createCommand is not a function
```
cause Incorrectly trying to destructure a named export, or accessing a property that doesn't exist. `test-cmd` exports a single function as its `module.exports`.

fix Use `const createCommand = require('test-cmd');` to get the default function export.
```
Error: listen EADDRINUSE: address already in use :::<port>
```
cause While not directly caused by `test-cmd`, old testing patterns often involve spawning multiple processes or servers without proper cleanup. `test-cmd` itself can spawn child processes for testing, and if these don't exit cleanly, they might leave resources like open ports in use.

fix Ensure that any child processes or servers spawned by your tests (managed by `test-cmd` or otherwise) are properly terminated or cleaned up after each test run, typically in `t.end()` or `afterEach` hooks.

Warnings

breaking The package is CommonJS-only. Using `import` statements in an ESM module context will result in a `SyntaxError: Cannot use import statement outside a module` or `require is not defined` error. It requires a Node.js environment configured for CommonJS.
Fix: Ensure your project or file uses CommonJS (`.js` files without `"type": "module"` in `package.json` or explicit `.cjs` extension) and use `const testCmd = require('test-cmd');`.
gotcha The package is unmaintained, with its last update over 8 years ago. It relies on deprecated dependencies like `optimist` for argument parsing, which may have security vulnerabilities or unexpected behavior with newer Node.js versions or complex CLI arguments.
Fix: Consider migrating to actively maintained test runner frameworks (e.g., Jest, Mocha, Vitest) or modern CLI argument parsers (e.g., `yargs`, `commander.js`) for new projects. For existing projects, be aware of potential security risks and compatibility issues.
gotcha Direct integration with modern `async/await` patterns is challenging due to its callback-based API. While it can be wrapped in Promises, the core design predates widespread async/await adoption in Node.js.
Fix: Wrap `test-cmd`'s callback-based functions in Promises using `util.promisify` or manual Promise constructors if `async/await` syntax is desired.

Install

npm install test-cmd npm
yarn add test-cmd yarn
pnpm add test-cmd pnpm

Imports

createCommand
wrong:
```
import createCommand from 'test-cmd';
```
correct:
```
const createCommand = require('test-cmd');
```
The package exclusively uses CommonJS `require` syntax. Attempting to use ESM `import` will result in errors as it's not an ESM module.
testCmd
wrong:
```
const { command } = require('test-cmd');
```
correct:
```
const testCmd = require('test-cmd');
testCmd.command(args, fn);
```
The package exports a single function. The conventional use is to assign the entire module export to a variable, then call methods on it, like `testCmd.command`.

Quickstart

Demonstrates how to import `test-cmd` using CommonJS and define a simple test command with `tape`, illustrating the expected command generation.

const createCommand = require('test-cmd');
const tape = require('tape');

// Simulate a simple command that echoes arguments
const mockCommand = (args) => {
  return `echo 'Hello, ${args.join(' ')}'`;
};

// Define a test using tape and test-cmd
tape('test-cmd basic usage', (t) => {
  t.plan(1); // Expect one assertion

  const myTestCmd = createCommand();

  myTestCmd.command(['world'], (run) => {
    // In a real scenario, 'run' would execute a shell command.
    // Here, we simulate it.
    const simulatedOutput = mockCommand(run.argv);
    
    // 'run' object would typically contain child process stdout/stderr
    // For this mock, we just check the generated command string.
    t.equal(simulatedOutput, "echo 'Hello, world'", 'should generate the correct echo command');
    t.end();
  });

});

// To run this: save as e.g., `my-test.js`, then `node my-test.js`
// This quickstart mocks the actual command execution for simplicity, 
// but `test-cmd` would typically spawn a child process.

view raw JSON →