CLI Assured

CLI Assured is a Java DSL for testing or executing command line applications.

Although we strive to keep all changes backwards compatible, as long as the project has not reached version 1.0.0, backwards incompatible changes may happen without notice.

Hello World!

Here an example how you would typically use CLI Assured:

import org.cliassured.CliAssured;

CliAssured
    // Call the echo command with parameter "Hello World!"
    .command("echo", "Hello World!")
    .then()
        .stdout()
            // Fail if there is no line equal to "Hello World!" in stdout
            .hasLines("Hello World!")
            // Fail if there is no line matching the given regular expression
            .hasLinesMatching("Hello .*")
            // Fail if foo or bar occur in stdout
            .doesNotHaveLinesContaining("foo", "bar")
            // Fail unless stdout has exactly one line
            .hasLineCount(1)
            // Possibly more asserts here
            // Log everything received from stdout
            .log()
    // Start the echo process on the operating system
    .execute()
    // Fail if "Hello World!" was not in stdout or exit code was not 0
    .assertSuccess();

Refer to CLI Assured API reference for more examples and for more information about the individual CLI Assured API methods.

Main characteristics

  • Fluent API

    • Methods return an adjusted copy rather that mutating the instance (unless specified otherwise)

  • Given-when-then structure known e.g. from REST Assured

  • Give user control over details but do not stand in way to do simple things

  • Avoid holding the entire command output in memory unless needed or wanted by the user

    • Allow testing commands outputting large amounts of data

    • Output line asserts:

      • Defined before the command process is started

      • Evaluated line-by-line on the thread consuming stdout or stderr

    • Allow handling binary content

Prerequisites

CLI Assured requires Java 8+ for basic usage, but Java 9+ is better if you need newer Process API for accessing PID or child processes.

Maven coordinates

<dependency>
  <groupId>org.cli-assured</groupId>
  <artifactId>cli-assured</artifactId>
  <version><!-- Use the latest --></version>
</dependency>

Find the latest version on Maven Central.

Project information

Structure of this documentation

The documentation is divided into the following main parts: