CLI/test

CLI/test is a CLI testing tool that allows you to write tests for command-line applications using a simple, literate syntax. Unlike bash-based test frameworks, expected output sits right next to the command that produces it, allowing tests to be read like annotated terminal sessions.

CLI/test is built around .cli test files and the clitest runner, with optional integrations: the clitest-lib crate for Rust tests, and clitest-mdbook so book examples execute at build time.

Tests are as simple as:

$ echo "Hello, world!"
! Hello, world!

Design

CLI/test tests read as annotated terminal sessions: the command and its expected output sit side by side, not split across separate assertion blocks. Built on Grok patterns, you can match structured or variable output without brittle regular expressions. The runner executes each $ command in order and stops on the first failure.

Building blocks

• Commands ($ …): run shell commands and match their output. See Basic Usage.
• Directives (%EXIT, %SET, …) control exit codes, timeouts, and captures. See Basic Usage.
• Patterns (!, ?, grok) match stdout literally, with regex, or with named patterns. See Pattern Matching and Grok Patterns.
• Control structures (if, for, background, defer, retry, …): express complex scenarios. See Control Structures.
• Variables and environment: reference captured output and manage working directories. See Environment and Variables.

A complete minimal file:

#!/usr/bin/env clitest --v0

$ echo "Hello, world!"
! Hello, world!

$ cat nonexistent-file
%EXIT fail
*

Integrations

• Standalone .cli files: write tests, then run clitest tests/*.cli locally or in CI. Each file is self-contained and readable as documentation.
• Executable scripts: with the shebang in place, mark the file executable and run it directly; the shebang invokes clitest for you.
• Rust integration tests: embed scripts in Rust tests with the clitest! macro from clitest-lib.
• The code blocks in this book are tested with the latest release of *CLI/Test.

See Getting Started for a feature summary, Installation to start using CLI/test, or Basic Usage to learn the syntax.