cli-testlab

library6.0.1jsnpmunverified

cli-testlab is a specialized test framework designed for Node.js command-line interface (CLI) applications. Currently at stable version 6.0.1, it provides a streamlined API for executing shell commands, capturing their standard output and error streams, and asserting on their content. Key features include the `execCommand` function, which integrates robust assertion capabilities for positive, negative, and error-based output checks, supporting both string and array inputs for comprehensive validation. It also facilitates the management of environment variables per command execution and offers a `FileTestHelper` class for automatic cleanup of test-generated files. This library differentiates itself by focusing specifically on the unique challenges of CLI testing, offering built-in utilities that abstract away common complexities like child process management and output parsing, making it simpler to write reliable and maintainable tests for CLI tools without relying on heavy general-purpose test runners for these specific tasks.

testing devops

npm install cli-testlab

github ↗package ↗

INSTALL

IMPORT

SIG · CLI-TESTLAB

cli-testlab

testingjavascriptv6.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

execCommand

✓ import { execCommand } from 'cli-testlab'

✗ const { execCommand } = require('cli-testlab')

cli-testlab v6+ is primarily designed for ESM usage. Direct CJS require() of named exports will likely fail unless using an interoperability layer or explicit import assertions.

FileTestHelper

✓ import { FileTestHelper } from 'cli-testlab'

✗ const FileTestHelper = require('cli-testlab').FileTestHelper

Used for managing test files with automatic cleanup. Ensure proper instantiation and use in `beforeEach`/`afterEach` hooks for automated cleanup.

execCommand default

✓ import cliTestlab from 'cli-testlab'; const { execCommand } = cliTestlab;

While named imports are preferred, for full interoperability with some environments or tooling, accessing named exports from a default import might be an alternative.

This quickstart demonstrates basic command execution, output assertions, error handling, and file management with automatic cleanup using `FileTestHelper` within a typical test suite.

import { execCommand, FileTestHelper } from 'cli-testlab'; import { promises as fs } from 'node:fs'; import { resolve } from 'node:path'; describe('My CLI application', () => { let fileHelper: FileTestHelper; beforeEach(() => { fileHelper = new FileTestHelper('temp-test-dir'); }); afterEach(async () => { await fileHelper.cleanup(); }); it('should report version correctly', async () => { // Assuming 'my-cli.js' is in the same directory as the test file for simplicity // In a real project, you might use 'path.resolve' to locate it. await execCommand('node my-cli.js --version', { expectedOutput: '1.0.0', baseDir: process.cwd() // Or the directory where my-cli.js resides }); }); it('should show an error for unknown commands', async () => { await execCommand('node my-cli.js unknown-command', { expectedErrorMessage: 'Unknown command', baseDir: process.cwd() }); }); it('should create a file and clean it up', async () => { const testFilePath = fileHelper.createFile('test.txt', 'hello world'); // Assume your CLI has a command like 'my-cli.js process-file test.txt' await execCommand(`node my-cli.js process-file ${testFilePath}`, { expectedOutput: 'File processed' }); // Verify the file exists before cleanup await expect(fs.access(resolve(fileHelper.tempDir, 'test.txt'))).resolves.toBeUndefined(); }); });

Debug

Known issues

breakingMajor version 6 likely introduced breaking changes. While specific changes aren't detailed in the provided README, users upgrading from v5 or earlier should review the official changelog for API shifts, particularly regarding import paths, options for `execCommand`, or assertion behavior.

fix

Consult the official cli-testlab v6 changelog on GitHub or npm for specific migration instructions and updated API signatures.

affects: >=6.0.0

gotcha`execCommand` is an asynchronous function and must always be `await`ed. Forgetting `await` will result in tests passing prematurely or unexpected behavior, as assertions will not be evaluated.

fix

Always prepend `execCommand` calls with `await` within `async` test functions: `await execCommand(...)`.

affects: >=1.0.0

gotchacli-testlab has a minimum Node.js version requirement of 18. Running tests with older Node.js versions will lead to errors, potentially including syntax errors for modern JavaScript features or module resolution failures.

fix

Ensure your testing environment uses Node.js v18 or newer. Update Node.js or configure your project's `engines` field in `package.json` to reflect this requirement.

affects: >=6.0.0

gotchaAssertions for successful commands (`expectedOutput`, `notExpectedOutput`) are checked against `stdout`, while `expectedErrorMessage` is checked against `stderr` specifically when a command exits with a non-zero code. Mixing these or using `expectedErrorMessage` for a successful command will not work as expected.

fix

Use `expectedOutput` or `notExpectedOutput` for commands expected to succeed (exit code 0). Use `expectedErrorMessage` for commands expected to fail (non-zero exit code).

affects: >=1.0.0

gotchaForgetting to use `FileTestHelper.cleanup()` or manually clean up test-generated files can lead to 'polluted' test environments, causing flaky tests or consuming excessive disk space. While `FileTestHelper` automates this, it still needs to be explicitly invoked.

fix

Always instantiate `FileTestHelper` in a `beforeEach` hook and ensure `fileHelper.cleanup()` is called in an `afterEach` hook for reliable test isolation and resource management.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: (0 , cli_testlab__WEBPACK_IMPORTED_MODULE_0__.execCommand) is not a function

Attempting to use CommonJS `require()` syntax or an outdated bundler configuration that struggles with ESM named exports, despite the package being ESM-first.

fix

Ensure your project is configured for ESM, typically by setting `"type": "module"` in `package.json`, and use `import { execCommand } from 'cli-testlab'`. If using a bundler like Webpack or Rollup, ensure its configuration properly handles ESM modules.

Error: Command 'node my-cli.js unknown-command' failed with exit code 1 and output: '...' (stderr: '...')

The `execCommand` function throws an error if the executed command exits with a non-zero status code and no `expectedErrorMessage` is provided.

fix

If the command is expected to fail, add `expectedErrorMessage: 'Partial or full error message'` to the `execCommand` options. If it's *not* expected to fail, investigate the CLI command and its environment (`baseDir`, `env`) to understand why it's returning a non-zero exit code.

AssertionError: Expected output 'Expected text' was not found in stdout.

The `expectedOutput` assertion failed because the specified text was not present in the command's standard output.

fix

Verify the exact output of your CLI command (e.g., by running it manually or inspecting `result.stdout` in debug) and adjust the `expectedOutput` string to precisely match. Remember that assertions are case-sensitive and whitespace-sensitive.

Error: spawn <command> ENOENT

The shell could not find the specified command. This often happens if the command is not in the system's PATH, or the path to a Node.js script is incorrect.

fix

Ensure the command string is correct and includes the necessary prefix (e.g., `node` for Node.js scripts). Check the `baseDir` option to confirm the working directory for the command execution is correct and the target script/executable exists at that relative path. If it's a globally installed binary, ensure your test runner environment has the correct PATH configured.

Upgrade

Version history

6.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/kibertoad/cli-testlab ↗

packagehttps://www.npmjs.com/package/cli-testlab ↗