Testing Rust CLI Tools with assert_cmd and predicates

Testing Rust CLI Tools with assert_cmd and predicates

Command-line tools need to be tested as black boxes — you run them, feed them input, and assert on what comes out. Rust's testing ecosystem has excellent crates for this: assert_cmd for driving process execution and predicates for composable assertions on output.

This guide covers end-to-end testing strategies for Rust CLI applications, from basic invocation assertions to complex stdin/stdout scenarios.

Why Black-Box CLI Testing Matters

Unit tests verify individual functions. But a CLI tool is a contract: given these arguments, produce this output, exit with this code. Black-box tests enforce that contract at the boundary your users actually experience.

When you refactor internals, unit tests might need updates. Black-box CLI tests don't — they test behavior, not implementation.

Setting Up assert_cmd

Add the dependencies to Cargo.toml:

[dev-dependencies]
assert_cmd = "2"
predicates = "3"
tempfile = "3"

assert_cmd wraps std::process::Command with a fluent assertion API. predicates provides composable matchers for strings, files, and byte slices.

Basic Command Assertions

Given a CLI binary named myapp, a basic test looks like:

use assert_cmd::Command;

#[test]
fn test_version_flag() {
    let mut cmd = Command::cargo_bin("myapp").unwrap();
    cmd.arg("--version")
        .assert()
        .success()
        .stdout(predicates::str::contains("myapp 1."));
}

Command::cargo_bin("myapp") finds the binary in target/debug/ (or target/release/ in release mode), handling platform differences automatically.

The .assert() call runs the command and returns an Assert struct. From there you chain assertions:

  • .success() — exit code 0
  • .failure() — non-zero exit code
  • .code(42) — specific exit code
  • .stdout(pred) — stdout matches predicate
  • .stderr(pred) — stderr matches predicate

Using predicates for Output Matching

The predicates crate gives you composable matchers:

use assert_cmd::Command;
use predicates::prelude::*;

#[test]
fn test_help_output() {
    let mut cmd = Command::cargo_bin("myapp").unwrap();
    cmd.arg("--help")
        .assert()
        .success()
        .stdout(
            predicate::str::contains("Usage:")
                .and(predicate::str::contains("OPTIONS:"))
        );
}

#[test]
fn test_error_on_missing_input() {
    let mut cmd = Command::cargo_bin("myapp").unwrap();
    cmd.assert()
        .failure()
        .stderr(predicate::str::contains("error: missing required argument"));
}

Common predicates for strings:

  • predicate::str::contains("text") — substring match
  • predicate::str::starts_with("prefix") — prefix match
  • predicate::str::ends_with("suffix") — suffix match
  • predicate::str::is_match("regex.*pattern").unwrap() — regex match
  • predicate::str::diff("exact string") — exact equality with diff on failure

Testing with stdin

Many CLI tools read from stdin. Use .write_stdin():

#[test]
fn test_stdin_processing() {
    let input = "hello world\nfoo bar\n";
    
    let mut cmd = Command::cargo_bin("myapp").unwrap();
    cmd.arg("count-words")
        .write_stdin(input)
        .assert()
        .success()
        .stdout(predicate::str::contains("4 words"));
}

For large inputs or binary data:

#[test]
fn test_binary_stdin() {
    let data: Vec<u8> = (0..256).map(|i| i as u8).collect();
    
    let mut cmd = Command::cargo_bin("myapp").unwrap();
    cmd.arg("passthrough")
        .write_stdin(data.clone())
        .assert()
        .success()
        .stdout(predicate::eq(data.as_slice()));
}

Testing with Files

CLI tools often take file paths as arguments. Use tempfile to create isolated test fixtures:

use tempfile::NamedTempFile;
use std::io::Write;

#[test]
fn test_file_processing() {
    let mut input_file = NamedTempFile::new().unwrap();
    writeln!(input_file, "line one").unwrap();
    writeln!(input_file, "line two").unwrap();
    writeln!(input_file, "line three").unwrap();
    
    let mut cmd = Command::cargo_bin("myapp").unwrap();
    cmd.arg("process")
        .arg(input_file.path())
        .assert()
        .success()
        .stdout(predicate::str::contains("Processed 3 lines"));
}

For testing output file creation:

use tempfile::tempdir;

#[test]
fn test_output_file_creation() {
    let dir = tempdir().unwrap();
    let output_path = dir.path().join("output.txt");
    
    let mut cmd = Command::cargo_bin("myapp").unwrap();
    cmd.arg("generate")
        .arg("--output")
        .arg(&output_path)
        .assert()
        .success();
    
    assert!(output_path.exists());
    let content = std::fs::read_to_string(&output_path).unwrap();
    assert!(content.contains("generated"));
}

Environment Variables

Test environment-dependent behavior:

#[test]
fn test_env_var_config() {
    let mut cmd = Command::cargo_bin("myapp").unwrap();
    cmd.env("MYAPP_LOG_LEVEL", "debug")
        .arg("run")
        .assert()
        .success()
        .stderr(predicate::str::contains("[DEBUG]"));
}

#[test]
fn test_missing_required_env_var() {
    let mut cmd = Command::cargo_bin("myapp").unwrap();
    cmd.env_remove("REQUIRED_TOKEN")
        .arg("sync")
        .assert()
        .failure()
        .stderr(predicate::str::contains("REQUIRED_TOKEN must be set"));
}

.env_remove() is particularly useful — it strips environment variables that might be set in your CI environment and affect test behavior.

Subcommand Testing

For tools with subcommands (like cargo or git), test each subcommand independently:

#[test]
fn test_init_subcommand() {
    let dir = tempdir().unwrap();
    
    let mut cmd = Command::cargo_bin("myapp").unwrap();
    cmd.current_dir(&dir)
        .arg("init")
        .arg("--name")
        .arg("my-project")
        .assert()
        .success()
        .stdout(predicate::str::contains("Initialized my-project"));
    
    assert!(dir.path().join("myapp.toml").exists());
}

#[test]
fn test_init_fails_if_already_initialized() {
    let dir = tempdir().unwrap();
    
    // Initialize once
    Command::cargo_bin("myapp").unwrap()
        .current_dir(&dir)
        .arg("init")
        .assert()
        .success();
    
    // Try again — should fail
    Command::cargo_bin("myapp").unwrap()
        .current_dir(&dir)
        .arg("init")
        .assert()
        .failure()
        .stderr(predicate::str::contains("already initialized"));
}

Testing Exit Codes Precisely

Exit codes are part of your CLI's API. Different errors should have different codes:

#[test]
fn test_exit_code_not_found() {
    let mut cmd = Command::cargo_bin("myapp").unwrap();
    cmd.arg("get")
        .arg("nonexistent-resource")
        .assert()
        .code(2);  // "not found" exit code
}

#[test]
fn test_exit_code_permission_error() {
    let mut cmd = Command::cargo_bin("myapp").unwrap();
    cmd.arg("delete")
        .arg("protected-resource")
        .assert()
        .code(3);  // "permission denied" exit code
}

Documenting and testing exit codes prevents regressions in scripts that depend on your tool.

Snapshot Testing CLI Output

For complex output that's hard to assert with predicates, combine assert_cmd with insta for snapshot testing:

use insta::assert_snapshot;

#[test]
fn test_list_output_format() {
    let mut cmd = Command::cargo_bin("myapp").unwrap();
    let output = cmd.arg("list")
        .arg("--format")
        .arg("table")
        .output()
        .unwrap();
    
    assert!(output.status.success());
    let stdout = String::from_utf8(output.stdout).unwrap();
    assert_snapshot!(stdout);
}

Run cargo test with INSTA_UPDATE=new to generate initial snapshots. Review them with cargo insta review.

Testing Interactive Prompts

For CLIs with interactive prompts, simulate user input via stdin:

#[test]
fn test_interactive_confirmation() {
    let mut cmd = Command::cargo_bin("myapp").unwrap();
    cmd.arg("delete")
        .arg("something")
        .write_stdin("y\n")  // Simulate user typing 'y' and pressing Enter
        .assert()
        .success()
        .stdout(predicate::str::contains("Deleted successfully"));
}

#[test]
fn test_interactive_rejection() {
    let mut cmd = Command::cargo_bin("myapp").unwrap();
    cmd.arg("delete")
        .arg("something")
        .write_stdin("n\n")
        .assert()
        .success()  // Exit 0 but nothing deleted
        .stdout(predicate::str::contains("Aborted"));
}

Organizing CLI Tests

Put integration tests in tests/ at the crate root, not src/:

myapp/
├── src/
│   └── main.rs
├── tests/
│   ├── cli_basic.rs
│   ├── cli_subcommands.rs
│   └── cli_edge_cases.rs
└── Cargo.toml

This keeps test compilation separate from your main binary and prevents test utilities from leaking into release builds.

Use a shared helper module for common setup:

// tests/common/mod.rs
use assert_cmd::Command;

pub fn myapp() -> Command {
    let mut cmd = Command::cargo_bin("myapp").unwrap();
    cmd.env_remove("MYAPP_CONFIG");  // Prevent local config from affecting tests
    cmd
}

Then in tests:

mod common;

#[test]
fn test_something() {
    common::myapp()
        .arg("subcommand")
        .assert()
        .success();
}

Running CLI Tests in CI

CLI integration tests are slower than unit tests because they compile and spawn actual processes. In CI, keep them fast with parallelism:

# .github/workflows/test.yml
- name: Run tests
  run: cargo test --release
  env:
    CARGO_TEST_THREADS: 8

Use --release flag to test the optimized binary — this catches issues that only appear in release mode and is typically faster due to LLVM optimizations.

For comprehensive CI coverage, consider running CLI tests against multiple platforms using matrix builds:

strategy:
  matrix:
    os: [ubuntu-latest, macos-latest, windows-latest]

Continuous Monitoring with HelpMeTest

Unit tests and CI cover what you know to test. But CLI tools deployed in production face real-world conditions: changing environments, unexpected inputs, and integration with other tools.

HelpMeTest lets you write natural-language test scenarios that run continuously against your deployed CLI:

Scenario: CLI produces valid JSON output
Given the myapp CLI is installed
When I run "myapp export --format json"
Then the output should be valid JSON
And the exit code should be 0

These run every few minutes, catching issues between deploys — configuration drift, dependency changes, or environment issues that only manifest in production.

Summary

Testing Rust CLI tools effectively requires testing at the boundary users experience:

  • assert_cmd drives command execution with a clean fluent API
  • predicates provides composable, readable output assertions
  • tempfile isolates filesystem side effects
  • Snapshot testing handles complex output formats
  • Exit codes are part of your API — test them explicitly
  • CI matrix builds catch platform-specific issues

The goal is a test suite that runs fast, fails loudly, and documents your CLI's contract in executable form.

Read more

Start now free