{"id":17421,"library":"cli-testing-library","title":"CLI Testing Library","description":"CLI Testing Library provides a set of simple and complete utilities for testing command-line interface (CLI) applications, encouraging good testing practices by focusing on user interaction and observable output rather than internal implementation details. Inspired by the popular React Testing Library, it helps developers simulate user input and assert on console output (stdout, stderr). The library is currently at version 3.0.1, released in January 2025, and maintains an active development cadence with regular updates and major version bumps that introduce breaking changes and improvements. Its key differentiators include a focus on accessibility and user experience in tests, first-class TypeScript support, and integration with popular test runners like Jest and Vitest through dedicated extensions. It abstracts away the complexities of spawning and managing child processes, making CLI testing straightforward.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/crutchcorn/cli-testing-library","tags":["javascript","testing","cli","unit","integration","functional","end-to-end","e2e","typescript"],"install":[{"cmd":"npm install cli-testing-library","lang":"bash","label":"npm"},{"cmd":"yarn add cli-testing-library","lang":"bash","label":"yarn"},{"cmd":"pnpm add cli-testing-library","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for extending Jest's global expect object with CLI-specific matchers.","package":"@jest/expect","optional":false},{"reason":"Required for extending Jest's global testing environment with CLI-specific utilities.","package":"@jest/globals","optional":false},{"reason":"Required for extending Vitest's expect object with CLI-specific matchers, if using Vitest as a test runner.","package":"vitest","optional":true}],"imports":[{"note":"While CommonJS `require` works, the library ships with ESM first, and modern Node.js projects prefer `import`.","wrong":"const { render } = require('cli-testing-library')","symbol":"render","correct":"import { render } from 'cli-testing-library'"},{"note":"The `userEvent` utility is a named export from the main package, not a separate module.","wrong":"import userEvent from 'cli-testing-library/userEvent'","symbol":"userEvent","correct":"import { userEvent } from 'cli-testing-library'"},{"note":"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`.","wrong":"import 'cli-testing-library/extend-expect'","symbol":"Jest Matchers","correct":"import 'cli-testing-library/jest'"}],"quickstart":{"code":"import { resolve } from 'path';\nimport { render } from 'cli-testing-library';\nimport 'cli-testing-library/jest'; // Extend Jest's expect with CLI matchers\n\ndescribe('Interactive CLI Testing', () => {\n  test('Should be able to make terminal input and view in-progress stdout', async () => {\n    // Assuming a simple Node.js script that prompts for input\n    const scriptPath = resolve(__dirname, './fixtures/stdio-inquirer.js');\n    const { clear, findByText, queryByText, userEvent } = await render('node', [\n      scriptPath,\n    ]);\n\n    // Wait for the first prompt to appear\n    const initialPrompt = await findByText('First option');\n    expect(initialPrompt).toBeInTheConsole();\n\n    // Verify current selection\n    expect(await findByText('❯ One')).toBeInTheConsole();\n\n    // Clear console output for better readability in tests\n    clear();\n\n    // Simulate arrow down key press to select 'Two'\n    userEvent('[ArrowDown]');\n\n    // Verify new selection\n    expect(await findByText('❯ Two')).toBeInTheConsole();\n    clear();\n\n    // Simulate Enter key press to confirm selection\n    userEvent.keyboard('[Enter]');\n\n    // Verify the final output after selection\n    expect(await findByText('First option: Two')).toBeInTheConsole();\n    expect(await queryByText('First option: Three')).not.toBeInTheConsole();\n\n    // Optional: Clean up after the test if the CLI process persists\n    // await cleanup();\n  }, 10000); // Increase timeout for interactive CLI tests\n});\n","lang":"typescript","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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`.","message":"The shape of `stderr` and `stdout` arrays returned by `render` changed from `Array<string | Buffer>` to `Array<{contents: string | Buffer, timestamp: number}>`.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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).","message":"CLI Testing Library may not function properly in Windows CI environments (e.g., GitHub Actions on Windows).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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'`.","cause":"The custom matchers for CLI Testing Library have not been correctly imported and extended into your test runner's `expect` object.","error":"TypeError: expect(...).toBeInTheConsole is not a function"},{"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.","cause":"You are attempting to import the `extend-expect` module using a deprecated path, which was removed in version 3.0.0.","error":"Error: Cannot find module 'cli-testing-library/extend-expect' from ..."},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'contents')"}],"ecosystem":"npm","meta_description":null}