adachsoft/cli-process-tester

CLI Process Tester

A PHP library for writing integration tests for CLI applications using real processes via adachsoft/command-executor-lib.

Provides a fluent, readable DSL with assertions for testing CLI commands as black boxes.

Installation

composer require adachsoft/cli-process-tester

Usage

Extend CliTestCase in your tests:

<?php

use AdachSoft\CliProcessTester\CliTestCase;

class HelloCommandTest extends CliTestCase
{
    public function test_hello(): void
    {
        $this->cli('php bin/app hello --name=Arkadiusz')
            ->assertExitCode(0)
            ->assertStdoutContains('Hello Arkadiusz')
            ->assertNoStderr();
    }
}

API

CliTestCase

• protected function cli(string $command): CliAssertion - Creates assertion builder for given command.

CliAssertion

Fluent interface with lazy execution (process runs only on first assertion, result is cached).

Configuration:

• withInput(string $stdin): self - Provides input to STDIN.
• withTimeout(int $seconds): self - Sets execution timeout.

Assertions (all return self for chaining):

• assertExitCode(int $expected): self
• assertStdoutContains(string $expected): self
• assertStdoutEquals(string $expected): self
• assertStderrContains(string $expected): self
• assertNoStderr(): self
• assertOutputMatchesRegex(string $regex): self

Examples

Test with STDIN

$this->cli('php -r "echo fread(STDIN, 1024);"')
    ->withInput("Hello from STDIN")
    ->assertStdoutContains("Hello from STDIN")
    ->assertExitCode(0);

Test with timeout

$this->cli('php -r "sleep(3);"')
    ->withTimeout(1)
    // will throw exception on timeout

Test error case

$this->cli('php -r "fwrite(STDERR, \"Error\"); exit(1);"')
    ->assertExitCode(1)
    ->assertStderrContains("Error")
    ->assertNoStderr(); // this would fail

Testing the library

composer test
# or
vendor/bin/phpunit

The library uses real proc_open through the command executor and provides stable, predictable API with no global state or magic.

Requirements

• PHP 8.3+
• PHPUnit 13+
• adachsoft/command-executor-lib

License

MIT