Process Testing

Purpose and Scope

This document describes the testing infrastructure for external process execution in Hypervel. The Process testing utilities allow developers to fake system command execution, assert on process invocations, and simulate various process behaviors including output, error output, exit codes, and timeouts without actually executing system commands.

For HTTP request testing and mocking, see HTTP Testing and Request Mocking. For general testing infrastructure and PHPUnit configuration, see PHPUnit Configuration and CI/CD.

---

Process Testing Architecture

The Process testing system is built around the Factory class, which provides a fluent API for running system commands and supports a comprehensive fake mode for testing. In fake mode, the factory intercepts process execution and returns predefined results based on pattern matching.

Sources: tests/Process/ProcessTest.php1-824

---

Factory Fake Mode

The Factory::fake() method enables test mode where process execution is intercepted and replaced with predefined results. When fake mode is enabled without arguments, all processes return successful results with empty output.

Basic Fake Mode

The most basic usage returns successful empty results for all commands:

tests/Process/ProcessTest.php175-186

Custom Fake Responses

Fake mode accepts a closure or array to customize responses. The closure receives the factory instance and should return a ProcessResult:

tests/Process/ProcessTest.php251-307

Multiple response formats are supported:

• Factory::result($output) - Creates a result with output
• Plain strings or arrays - Automatically converted to results
• Factory::describe() - Fluent result builder
• Closures returning any of the above

Preventing Stray Processes

The preventStrayProcesses() method ensures all process executions match a defined fake pattern, throwing a RuntimeException for any unmatched commands:

tests/Process/ProcessTest.php414-430

By default, commands without matching fakes execute normally. This method enforces strict test isolation.

Sources: tests/Process/ProcessTest.php175-186 tests/Process/ProcessTest.php251-307 tests/Process/ProcessTest.php414-448

---

Pattern Matching and Command Stubbing

The fake mode supports pattern-based command matching using wildcard patterns, allowing different responses for different command types.

Pattern Matching Examples

Wildcard patterns use * to match any characters:

tests/Process/ProcessTest.php335-349

Multi-Line Command Matching

Patterns work with multi-line commands, matching after whitespace normalization:

tests/Process/ProcessTest.php209-229

Exit Code Shorthand

Array values can be integers representing exit codes:

tests/Process/ProcessTest.php240-249

Exception Throwing

Patterns can map to exceptions which will be thrown when the command matches:

tests/Process/ProcessTest.php462-472

Sources: tests/Process/ProcessTest.php335-349 tests/Process/ProcessTest.php209-229 tests/Process/ProcessTest.php240-249 tests/Process/ProcessTest.php462-472

---

Creating Fake Results

The framework provides multiple ways to construct fake process results with custom output, error output, and exit codes.

Factory Result Builder

Method	Parameters	Description
Factory::result()	$output, $errorOutput, $exitCode	Creates a result with specified outputs and exit code
Factory::describe()	-	Returns a fluent ProcessDescription builder
Factory::sequence()	-	Creates a ProcessResultSequence for multiple invocations

Result Construction Methods

Factory::result() Method

tests/Process/ProcessTest.php309-333

Process Description Builder

The describe() method returns a fluent builder for complex result scenarios:

tests/Process/ProcessTest.php294-307

The builder supports:

• output($line) - Adds a line to standard output
• errorOutput($line) - Adds a line to error output
• runsFor(iterations: $n) - Simulates long-running process with incremental output

Long-Running Process Simulation

For testing asynchronous process monitoring, runsFor() simulates a process that outputs incrementally:

tests/Process/ProcessTest.php758-788

Sources: tests/Process/ProcessTest.php251-333 tests/Process/ProcessTest.php758-788

---

Sequence Management

Sequences allow different results for repeated invocations of the same command, useful for testing retry logic or stateful command interactions.

Basic Sequence Usage

tests/Process/ProcessTest.php351-370

Empty Sequence Behavior

By default, sequences throw OutOfBoundsException when exhausted:

tests/Process/ProcessTest.php393-412

The dontFailWhenEmpty() method changes this behavior to return empty results:

tests/Process/ProcessTest.php372-391

Sources: tests/Process/ProcessTest.php351-412

---

Process Assertions

The framework provides assertion methods to verify process invocations during test execution.

Assertion Method	Parameters	Description
assertRan()	Closure $callback	Asserts a process matching the callback was executed
assertRanTimes()	Closure $callback, int $times	Asserts a process ran exactly N times
assertNotRan()	Closure $callback	Asserts no process matching the callback was executed
assertNothingRan()	-	Asserts no processes were executed at all

Assertion Examples

tests/Process/ProcessTest.php790-809

Callback Parameters

Assertion callbacks receive two parameters:

1. $process - The PendingProcess instance with command details
2. $result - The ProcessResult returned from execution

Common assertions:

• Check command string: $process->command == 'expected command'
• Check exit code: $result->exitCode() == 0
• Check output: str_contains($result->output(), 'expected')

Asserting No Execution

tests/Process/ProcessTest.php811-818

Sources: tests/Process/ProcessTest.php790-818

---

Process Pool Testing

Process pools allow concurrent execution of multiple processes with coordinated result collection. The fake mode fully supports pool testing with per-process result configuration.

Basic Pool Usage

tests/Process/ProcessTest.php41-61

Pool with Fake Results

Pools work seamlessly with pattern matching - each command in the pool is matched independently:

tests/Process/ProcessTest.php63-84

Named Process Access

Processes can be named using as() for semantic result access:

tests/Process/ProcessTest.php127-143

Output Streaming

The start() method accepts a callback for real-time output streaming:

tests/Process/ProcessTest.php102-125

The callback receives:

• $type - Output type ('out' or 'err')
• $buffer - Output chunk
• $key - Process index or name

Pool Status Methods

Method	Return Type	Description
count()	int	Number of processes in pool
successful()	bool	True if all processes succeeded
failed()	bool	True if any process failed
Array access	ProcessResult	Access results by index or name

tests/Process/ProcessTest.php86-100

Sources: tests/Process/ProcessTest.php41-143

---

Result Descriptions and Advanced Features

The Factory::describe() method returns a ProcessDescription builder for advanced result construction including simulated execution timing and incremental output delivery.

Process Description Builder

Incremental Output with runsFor()

The runsFor(iterations: $n) method simulates a process that executes over multiple iterations, delivering output incrementally:

tests/Process/ProcessTest.php758-788

This enables testing:

• Process::running() - Returns true while iterations remain
• Process::latestOutput() - Returns only new output since last check
• Process::output() - Returns cumulative output
• Asynchronous monitoring patterns

Output Callback Testing

Real-time output can be captured via callbacks in both start() and wait() methods:

tests/Process/ProcessTest.php145-173

Exception Handling

Fake results fully support exception throwing via throw() and throwIf():

tests/Process/ProcessTest.php474-508

Exception types:

• ProcessFailedException - When exit code is non-zero
• ProcessTimedOutException - Simulated timeout scenarios
• Custom exceptions - Via pattern mapping

Sources: tests/Process/ProcessTest.php145-173 tests/Process/ProcessTest.php474-537 tests/Process/ProcessTest.php758-788

---

Process Pipe Testing

Process pipes chain multiple commands where the output of one feeds into the input of the next. The fake mode supports pipe testing with pattern matching for each command in the pipe.

Array-Based Pipe

tests/Process/ProcessTest.php727-740

Closure-Based Pipe

tests/Process/ProcessTest.php695-708

Pipe Failure Handling

If any command in the pipe fails, the entire pipe result is marked as failed:

tests/Process/ProcessTest.php710-724 tests/Process/ProcessTest.php742-756

Sources: tests/Process/ProcessTest.php695-756

---

CI/CD Integration

The process testing infrastructure integrates with GitHub Actions and PHPUnit for continuous integration testing.

PHPUnit Configuration

phpunit.xml.dist1-29

Key configuration:

• Bootstrap file: tests/bootstrap.php
• Process isolation: false (uses coroutines instead)
• Test suite: Excludes Prompts, Sentry, Horizon packages
• Environment variable: RUN_BLOCKING_TESTS=false (skips timeout tests)

GitHub Actions Workflow

.github/workflows/tests.yml1-40

The workflow:

• Tests across PHP 8.2, 8.3, 8.4
• Tests across Swoole 5.1.6, 6.0.2
• Excludes integration tests (separate jobs)
• Runs PHP CS Fixer and PHPUnit

Environment Configuration

.env.example1-16

Integration tests are opt-in via environment variables and skip by default.

Sources: phpunit.xml.dist1-29 .github/workflows/tests.yml1-40 .env.example1-16 tests/bootstrap.php1-23