adachsoft/cli-process-tester

Integration testing helpers for CLI applications in PHPUnit.

v0.1.0 2026-04-23 09:04 UTC

Requires

• php: ^8.3
• adachsoft/command-executor-lib: ^2.0

Requires (Dev)

• adachsoft/php-code-style: ^0.4.4
• friendsofphp/php-cs-fixer: ^3.95
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^13.1
• rector/rector: ^2.4

MIT

• Arkadiusz Adach

• cli
• phpunit
• DSL
• process
• integration-testing

README

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