https://github.com/l2x6/cli-assured

Java DSL for testing command line applications
https://github.com/l2x6/cli-assured

cli java testing

Last synced: 6 months ago
JSON representation

Java DSL for testing command line applications

• Host: GitHub
• URL: https://github.com/l2x6/cli-assured
• Owner: l2x6
• License: apache-2.0
• Created: 2025-12-03T21:30:45.000Z (7 months ago)
• Default Branch: main
• Last Pushed: 2025-12-14T22:47:43.000Z (7 months ago)
• Last Synced: 2025-12-15T06:26:39.721Z (7 months ago)
• Topics: cli, java, testing
• Language: Java
• Homepage:
• Size: 184 KB
• Stars: 1
• Watchers: 0
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.adoc
  • License: LICENSE

Awesome Lists containing this project

README

          
= CLI Assured

https://github.com/l2x6/cli-assured/blob/main/LICENSE[image:https://img.shields.io/github/license/l2x6/cli-assured.svg[License]]

https://central.sonatype.com/artifact/org.l2x6.cli-assured/cli-assured[image:https://img.shields.io/maven-central/v/org.l2x6.cli-assured/cli-assured.svg[Maven

Central]]

A Java DSL for testing command line applications.

Requires Java 8+

== Maven coordinates

[source,xml]

----

  org.l2x6.cli-assured

  cli-assured

  

----

Find the latest version on https://central.sonatype.com/artifact/org.l2x6.cli-assured/cli-assured[Maven Central].

== Usage

=== Basic syntax

Test an executable available in `PATH`

[source,java]

----

import org.l2x6.cli.assured.CliAssured;

CliAssured

    .command("echo", "CLI Assured rocks!")

    .stderrToStdout() // redirect stderr to stdout

    .then()

        // Assertions for stdout

        // The same can be done with stderr(), unless you called stderrToStdout()

        .stdout()

            .hasLines("CLI Assured rocks!")

            .hasLinesContaining("rocks")

            .hasLinesMatching("CLI.*rocks")

            .doesNotHaveLinesContainingCaseInsensitive("error")

            .log() // Pass every line to org.l2x6.cli.assured.stdout logger

            .hasLineCount(1)

            .redirect(Path.of("hello.txt")) // redirect the output to hello.txt

        .exitCodeIs(0) // could be omitted as exit code 0 is enforced by default

    .execute()

    .assertSuccess(); // Report all assertion errors

----

=== Given-when-then

If you are a fan of Behavior-Driven testing, there is some syntactic sugar for you:

[source,java]

----

import org.l2x6.cli.assured.CliAssured;

CliAssured

    .given()

        .env("MESSAGE", "CLI Assured rocks!")

    .when()

        .command("sh", "-c",

                    "echo $MESSAGE;"

                  + "echo Really! 1>&2")

    .then()

        .stdout()

            .hasLines("CLI Assured rocks!")

            .hasLineCount(1)

        .stderr()

            .hasLines("Really!")

            .hasLineCount(1)

        .exitCodeIs(0)

    .execute()

    .assertSuccess();

----

=== `stdin`

[source,java]

----

import org.l2x6.cli.assured.CliAssured;

CliAssured

    .given()

        .stdin("Hello world!")

    .when()

        .command("cat")

    .then()

        .stdout()

            .hasLines("Hello world!")

            .hasLineCount(1)

    .execute()

    .assertSuccess();

----

=== `CliAssured.java()` - call the `java` executable of the current JVM

Sometimes it comes in handy to call the `java` executable of the current JVM.

For example

[source,java]

----

import org.l2x6.cli.assured.CliAssured;

CliAssured

    .java()

        .args("-jar", "path/to/my.jar")

    .execute()

    .assertSuccess();

----

Or if you want to compile and run a single java file, such as

[source,java]

.Hello.java

----

public class Hello {

    public static void main(String[] args) {

        System.out.println("Hello " + args[0]);

    }

}

----

it can be done as follows

[source,java]

----

import org.l2x6.cli.assured.CliAssured;

...

CliAssured

    .java()

       .args("path/to/Hello.java", "Joe")

    .then()

        .stdout()

            .hasLines("Hello Joe")

    .execute()

    .assertSuccess();

----

== `mvn-assured` - a Java DSL for invoking an testing Maven

=== Maven coordinates

[source,xml]

----

  org.l2x6.cli-assured

  mvn-assured

  

----

Find the latest version on https://central.sonatype.com/artifact/org.l2x6.cli-assured/mvn-assured[Maven Central].

=== Usage

[source,java]

----

Mvn.version("3.9.11")

    .installIfNeeded() // installs Maven from

                       // https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.11/apache-maven-3.9.11-bin.zip

                       // to ~/.m2/wrapper/dists/apache-maven-3.9.11/a2d47e15

                       // much like Maven Wrapper would do.

    .args("--version") // Returns an org.l2x6.cli.assured.CommandSpec,

                       // so the rest is a standard cli-assured code

    .then()

        .stdout()

            .hasLines("Apache Maven 3.9.11 (3e54c93a704957b63ee3494413a2b544fd3d825b)")

    .execute()

    .assertSuccess();

----

Or alternatively,

[source,java]

----

Mvn.fromMvnw(Paths.get(".")) // Find .mvn/wrapper/maven-wrapper.properties

                             // under the nearest ancestor,

                             // extract the distribution URL from there

                             // find Maven version from the distribution URL

                             // and use all of that to create a new Mvn instance

    .installIfNeeded() // You can omit this, if you are sure mvnw was run before

    .args("--version") // Returns an org.l2x6.cli.assured.CommandSpec,

                       // so the rest is a standard cli-assured code

    .then()

        .stdout()

            .hasLines("Apache Maven 3.9.11 (3e54c93a704957b63ee3494413a2b544fd3d825b)")

    .execute()

    .assertSuccess();

----