CLI Testing Library

Common errors

• TypeError: expect(...).toBeInTheConsole is not a function

  cause The custom matchers for CLI Testing Library have not been correctly imported and extended into your test runner's `expect` object.
  fix For Jest, add `import 'cli-testing-library/jest'` to your test setup file or at the top of relevant test files. For Vitest, use `import 'cli-testing-library/vitest'`.

• Error: Cannot find module 'cli-testing-library/extend-expect' from ...

  cause You are attempting to import the `extend-expect` module using a deprecated path, which was removed in version 3.0.0.
  fix Update your import statement to use the new test runner-specific paths: `import 'cli-testing-library/jest'` for Jest, or `import 'cli-testing-library/vitest'` for Vitest.

• TypeError: Cannot read properties of undefined (reading 'contents')

  cause Your code is attempting to access `item.contents` on the `stdout` or `stderr` array, but is running against a version of `cli-testing-library` older than v2.0.0, where `stdout`/`stderr` contained raw strings/buffers.
  fix Either upgrade `cli-testing-library` to v2.0.0 or newer to match the expected object shape, or adjust your code to access the raw string/buffer directly (e.g., `output.stdout[0]`) if remaining on an older version.

Warnings

• breaking The `extend-expect` import path for custom matchers has been split into test-runner specific paths. Directly importing `cli-testing-library/extend-expect` will fail.
  Fix: Update your imports to `import 'cli-testing-library/jest'` for Jest or `import 'cli-testing-library/vitest'` for Vitest. Ensure this import is executed before your tests.
• breaking The shape of `stderr` and `stdout` arrays returned by `render` changed from `Array<string | Buffer>` to `Array<{contents: string | Buffer, timestamp: number}>`.
  Fix: If you were directly accessing elements in `stdout` or `stderr`, adjust your code to access `item.contents` instead of `item` directly. For example, `output.stdout[0].contents`.
• breaking The underlying `chalk` dependency has been replaced with `picocolors` for performance and bundle size. While typically an internal change, direct usage of `chalk` functionality exposed through `cli-testing-library` might be affected.
  Fix: Review any code that might have indirectly relied on `chalk`'s API or behavior. Most users will not be directly impacted, but if issues arise, consider migrating to `picocolors` directly if styling is critical.
• gotcha CLI Testing Library may not function properly in Windows CI environments (e.g., GitHub Actions on Windows).
  Fix: Consider running your CLI tests on Linux-based CI environments. If a fix is found, contribute to the tracking issue on GitHub (https://github.com/crutchcorn/cli-testing-library/issues/13).

Install

• npm install cli-testing-library npm
• yarn add cli-testing-library yarn
• pnpm add cli-testing-library pnpm

Imports

• render
  wrong:

  const { render } = require('cli-testing-library')

  correct:

  import { render } from 'cli-testing-library'

  While CommonJS `require` works, the library ships with ESM first, and modern Node.js projects prefer `import`.
• userEvent
  wrong:

  import userEvent from 'cli-testing-library/userEvent'

  correct:

  import { userEvent } from 'cli-testing-library'

  The `userEvent` utility is a named export from the main package, not a separate module.
• Jest Matchers
  wrong:

  import 'cli-testing-library/extend-expect'

  correct:

  import 'cli-testing-library/jest'

  Since v3.0.0, the `extend-expect` path was broken down. Use `cli-testing-library/jest` for Jest or `cli-testing-library/vitest` for Vitest to enable custom matchers like `toBeInTheConsole`.

Quickstart

This quickstart demonstrates how to render a Node.js CLI, simulate user interactions (arrow keys, enter), and assert on the console output using custom Jest matchers like `toBeInTheConsole`.

import { resolve } from 'path';
import { render } from 'cli-testing-library';
import 'cli-testing-library/jest'; // Extend Jest's expect with CLI matchers

describe('Interactive CLI Testing', () => {
  test('Should be able to make terminal input and view in-progress stdout', async () => {
    // Assuming a simple Node.js script that prompts for input
    const scriptPath = resolve(__dirname, './fixtures/stdio-inquirer.js');
    const { clear, findByText, queryByText, userEvent } = await render('node', [
      scriptPath,
    ]);

    // Wait for the first prompt to appear
    const initialPrompt = await findByText('First option');
    expect(initialPrompt).toBeInTheConsole();

    // Verify current selection
    expect(await findByText('❯ One')).toBeInTheConsole();

    // Clear console output for better readability in tests
    clear();

    // Simulate arrow down key press to select 'Two'
    userEvent('[ArrowDown]');

    // Verify new selection
    expect(await findByText('❯ Two')).toBeInTheConsole();
    clear();

    // Simulate Enter key press to confirm selection
    userEvent.keyboard('[Enter]');

    // Verify the final output after selection
    expect(await findByText('First option: Two')).toBeInTheConsole();
    expect(await queryByText('First option: Three')).not.toBeInTheConsole();

    // Optional: Clean up after the test if the CLI process persists
    // await cleanup();
  }, 10000); // Increase timeout for interactive CLI tests
});