clitest for Mac

clitest – Command Line Tester

clitest is a portable POSIX shell script that performs automatic testing in Unix command lines.

It's the same concept as in Python's doctest module: you document both the commands and their expected output, using the familiar interactive prompt format, and a specialized tool tests them.

In fact, the doctest official description can also be used for clitest: The doctest module searches for pieces of text that look like interactive Python sessions, and then executes those sessions to verify that they work exactly as shown. The clitest command searches for pieces of text that look like interactive Unix command lines, and then executes those command lines to verify that they work exactly as shown.

Download & install

The full program is just a single shell script file.

Save it, make it executable and move it to a $PATH directory:

Now check if everything is fine:

Docker image

You can also run clitest in a Docker container (more info in Docker Hub).

GitHub Actions

This repository doubles as a GitHub Action, so a workflow does not have to download and install the script itself:

clitest runs on the runner rather than in a container, so the test files can invoke anything the job has already built or installed.

Quick Intro

Save the commands and their expected output in a text file:

♦ examples/intro.txt

Use clitest to run these commands and check their output:

CLI Syntax

There's no syntax to learn.

The test files are identical to the good old command line interface (CLI) you're so familiar:

♦ examples/cut.txt

That's it.

Just paste your shell session inside a text file and you have a ready-to-use test suite.

There are more examples and instructions in the examples folder. For a real-life collection of hundreds of test files, see funcoeszz test files.

Testable Documentation

Clitest can also extract and run command lines from documentation, such as Markdown files. This very README.md file you are now reading is testable with clitest README.md. All the command lines inside it will be run and checked.

No more malfunctioning shell commands in your READMEs, you can have testable documentation.

Given the following Markdown sample document:

♦ examples/cut.md

It is a technical article, not a boring code-only test file. You can read its final (formatted) version here.

You can give this article to clitest, who will identify all the shell command lines inside it, run them and check if the results are the same.

Note the use of --prefix tab option, to inform clitest that the code blocks are prefixed by a tab in this Markdown file. For files with 4-spaces indented code blocks, use --prefix 4. When using non-indented fenced code blocks (), such as this README.md, no prefix option is needed.