{"id":12983,"library":"command-line-test","title":"Command Line Test Utility for Node.js","description":"command-line-test is a focused Node.js utility library designed for performing integration tests against command-line interfaces and executables. Currently at version 1.0.10, it provides a unified API to execute shell commands and processes using Node.js's `child_process` module capabilities, including `fork`, `spawn`, `exec`, and `execFile`. The library simplifies the capture and analysis of standard output (`stdout`), standard error (`stderr`), and exit codes from executed commands, making it ideal for verifying CLI tool behavior. It supports asynchronous operations via Promises, traditional Node.js callbacks, and generator-based `yield` (often used with frameworks like `co` or `co-mocha`). Its primary differentiator is its straightforward approach to command execution and result parsing within a test environment, offering a stable and mature solution for CLI automation testing. The project appears to be in a maintenance phase, with infrequent updates since its stable 1.x release series.","status":"maintenance","version":"1.0.10","language":"javascript","source_language":"en","source_url":"git://github.com/macacajs/command-line-test","tags":["javascript","test","unittest"],"install":[{"cmd":"npm install command-line-test","lang":"bash","label":"npm"},{"cmd":"yarn add command-line-test","lang":"bash","label":"yarn"},{"cmd":"pnpm add command-line-test","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is a CommonJS module. Use `require` for direct import in Node.js environments.","symbol":"CliTest","correct":"const CliTest = require('command-line-test');"},{"note":"While the primary export is the class directly, some might expect a named export or a default export for ESM. This is incorrect as it's a CJS module exporting a class.","wrong":"import CliTest from 'command-line-test';","symbol":"CliTest","correct":"const CliTest = require('command-line-test').CliTest;"},{"note":"Attempting to import `CliTest` as a named export from an ES Module will fail because the package is a CommonJS module and does not provide native named exports for ESM consumers.","wrong":"import { CliTest } from 'command-line-test';","symbol":"CliTest","correct":"const CliTest = require('command-line-test');"}],"quickstart":{"code":"const CliTest = require('command-line-test');\nconst assert = require('assert');\n\nasync function runCliTestExample() {\n  const cliTest = new CliTest();\n\n  console.log('--- Testing `cat package.json` ---');\n  try {\n    const res = await cliTest.exec('cat package.json');\n    // res object contains error, stdout, stderr\n    const pkg = JSON.parse(res.stdout);\n    console.log(`Package name: ${pkg.name}`);\n    assert.strictEqual(pkg.name, 'command-line-test', 'Expected package name to match');\n    console.log('Test successful: Successfully read and parsed package.json.');\n  } catch (error) {\n    console.error('Test failed:', error.message, error.stderr);\n  }\n\n  console.log('\\n--- Testing a non-existent command ---');\n  try {\n    const res = await cliTest.exec('nonexistent-command');\n    // This should ideally throw or return an error in 'res.error'\n    console.log('Unexpected success for nonexistent command. Output:', res);\n  } catch (error) {\n    console.log('Test caught expected error for nonexistent command.');\n    assert.ok(error.message.includes('command not found') || error.stderr.includes('command not found'), 'Expected 'ENOENT' or 'command not found' error');\n  }\n}\n\n// A minimal assert implementation if not using a test runner\n// or for demonstrating simple assertions within the quickstart.\n// In a real project, use a proper assertion library like 'should' or 'chai'.\n// For demonstration, a basic `assert` is good enough.\n\nrunCliTestExample();","lang":"javascript","description":"Demonstrates how to use `command-line-test` to execute a shell command and process its `stdout` and `stderr` using Promises. It includes an example of a successful command and one designed to fail."},"warnings":[{"fix":"Always use `const CliTest = require('command-line-test');` when importing the library.","message":"This package is a CommonJS module (`require` syntax) and does not provide native ES Module (`import` syntax) exports. Attempting to use `import` directly may lead to errors or require specific build tool configurations.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Prefer the Promise-based API (`cliTest.exec().then(...)` or `await cliTest.exec(...)`) for modern Node.js projects to avoid potential compatibility issues with generator runtimes. If using `yield`, ensure your test environment is configured to transpile or run generators.","message":"The documentation and examples show usage with generator functions (using the `yield` keyword). While this works with `co`-style runners (e.g., `co-mocha`), modern Node.js development primarily uses `async/await` for asynchronous control flow. Ensure your test runner and environment support generators if you choose this pattern, otherwise use the Promise-based API.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For complex arguments, consider passing an array of arguments to `cliTest.spawn` or `cliTest.execFile` instead of a single command string to `cliTest.exec`, which leverages Node.js's safer argument handling. Alternatively, ensure proper shell quoting/escaping for your specific shell.","message":"When running shell commands, pay close attention to shell escaping for arguments, especially when dealing with paths containing spaces or special characters. Incorrect escaping can lead to command interpretation errors or security vulnerabilities.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify the command name is correct and that it is installed and accessible via your system's PATH environment variable. For local binaries, provide the full path or ensure your `node_modules/.bin` is in the PATH if using `npm run` scripts.","cause":"The command specified in `cliTest.exec` or `cliTest.spawn` was not found in the system's PATH.","error":"Error: spawn <command> ENOENT"},{"fix":"Either use `async/await` for asynchronous operations, configure your test setup with Babel to transpile generators, or ensure a `co`-compatible test runner is used. The Promise-based API is generally recommended for modern JavaScript.","cause":"You are using `yield` in a test function without a transpiler (like Babel) or a runtime (like `co`) that provides the `regeneratorRuntime` for generator functions.","error":"ReferenceError: regeneratorRuntime is not defined"},{"fix":"Ensure you are using `const CliTest = require('command-line-test');` to import the module, as it is a CommonJS package that exports the `CliTest` class directly.","cause":"The `command-line-test` module was imported incorrectly, leading to `CliTest` not being the expected class constructor.","error":"TypeError: CliTest is not a constructor"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}