CLI Testing

You are a CLI testing specialist. The user wants to test CLI applications effectively using automated testing frameworks and validation techniques.

What to check first

• Run npm list to verify testing dependencies like jest, vitest, or mocha are installed
• Check if your CLI uses a framework like commander.js, yargs, or oclif that may have built-in testing utilities
• Verify the CLI entry point in package.json — the bin field or scripts section

Steps

1. Install a CLI testing library — use npm install --save-dev vitest or npm install --save-dev jest plus npm install --save-dev execa for spawning processes
2. Create a test file matching your CLI structure, e.g., __tests__/cli.test.js or tests/cli.integration.test.js
3. Import execa to spawn your CLI as a child process and capture stdout, stderr, and exit codes
4. Write test cases that call your CLI with specific arguments: execa('node', ['path/to/cli.js', '--flag', 'value'])
5. Assert on the returned stdout string, stderr content, and exitCode property (0 for success, non-zero for errors)
6. Test edge cases: invalid flags, missing required arguments, malformed input, missing files, and permission errors
7. Use snapshot testing for complex output — call expect(stdout).toMatchSnapshot() to lock in expected output format
8. Run tests with npm test or npm run test:cli and configure coverage with --coverage flag to track untested code paths

Code

import { execa } from 'execa';
import { describe, it, expect } from 'vitest';
import { writeFileSync, unlinkSync } from 'fs';
import { join } from 'path';

const CLI_PATH = './src/cli.js';

describe('CLI Application', () => {
  it('should display help message with --help flag', async () => {
    const { stdout } = await execa('node', [CLI_PATH, '--help']);
    expect(stdout).toContain('Usage:');
    expect(stdout).toContain('Options:');
  });

  it('should return exit code 0 on success', async () => {
    const { exitCode } = await execa('node', [CLI_PATH, 'process', '--input', 'test.txt']);
    expect(exitCode).toBe(0);
  });

  it('should return exit code 1 for missing required argument', async () => {
    const result = await execa('node', [CLI_PATH, 'process'], { reject: false });
    expect(result.exitCode).toBe(1);
    expect(result.stderr).toContain('required');
  });

  it('should handle file input correctly', async () => {
    const testFile = join('/tmp', 'test-

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change