Interactive CLI Tester

A tool for testing interactive command line interfaces that require keyboard input.

⚠️ This software is still in development and not ready for production use.

You can find a complete API documentation here.

Features

• Test every command line interface - no matter in which programming language it is written 🧪
• Test interactive command line interfaces that require user input ⌨️
• Independent of the testing framework you want to use 😎
• Zero dependencies 📦

Getting Started

You can install this package using npm:

npm install --save-dev interactive-cli-tester

The following example shows how to test a simple interactive CLI build with enquirer using Jest. But you can use any Node.js testing framework you want.

import { CLITest, ANSI } from 'interactive-cli-tester';

test('Test example CLI', async () => {
    const cliTest = new CLITest('node', ['examples/readme.mjs']);

    // Start the process, you can re-use the same instance for multiple runs
    await cliTest.run();

    // Wait until the CLI asks for input
    await cliTest.waitForOutput('What do you want to do?');
    // Equivalent to pressing down arrow and enter
    await cliTest.write(ANSI.CURSOR_DOWN + ANSI.CR);

    // Expect the CLI to ask for the name
    await cliTest.waitForOutput('Input your name');
    await cliTest.write('Acme' + ANSI.CR);

    // Wait for the process to exit and check the exit code
    expect(await cliTest.waitForExit()).toBe(0);

    // Check that the output contains the expected text
    expect(cliTest.getOutput().includes('Hello Acme!')).toBe(true);
});

A complete API documentation including all available methods and options can be found here.

Code Coverage

It can be difficult to configure your testing framework to collect code coverage for Node.js child processes. For example, Jest does not support this out of the box (#5274), even though bcoe/c8 and istanbuljs/nyc do. One possible workaround for Jest is described in this comment, but this is not a perfect solution and may not work when using TypeScript.

You can find a complicated and not perfect workaround using two seperate Jest runners and nyc in my repo timokoessler/docker-deploy-api. I am not using c8 because of the issue #462.

If you have a question, have found a better way or successfully used another testing framework, please create an issue or send me a message.

Sources

• ANSI Escape Sequences

Contact

If a public GitHub issue or discussion is not the right choice for your concern, you can contact me directly:

• E-Mail: [e-mail]

License

© Timo Kössler 2024
Released under the MIT license