Testing and Faking

This page provides an overview of the testing infrastructure in the hypervel/process package, which enables simulation of process execution without spawning actual operating system processes. The faking system allows tests to run quickly, deterministically, and without external dependencies while verifying that application code interacts with processes as expected.

This page covers the architecture and components of the testing system. For detailed information about specific aspects:

• Enabling faking and configuring handlers: see Faking Overview
• Simulating completed processes: see Fake Process Results
• Building complex fake behaviors: see Fake Process Descriptions
• Creating stateful fakes with different results per call: see Fake Process Sequences
• Simulating asynchronous process execution: see Fake Invoked Processes
• Verifying process interactions: see Process Assertions
• Enforcing comprehensive test coverage: see Preventing Stray Processes

Purpose and Architecture

The testing infrastructure serves three primary functions:

Function	Implementation	Location
Fake Handler System	Intercepts process execution and returns simulated results	Factory::fake(), Factory::$fakeHandlers
Recording System	Captures all process executions during tests	Factory::record(), Factory::$recorded
Assertion API	Verifies expected process interactions occurred	Factory::assertRan(), Factory::assertRanTimes(), etc.

The architecture uses polymorphism through contracts (ProcessResultContract, InvokedProcessContract) to ensure fake implementations match the API of real implementations. This allows application code to remain unchanged during testing.

Sources: src/Factory.php1-271

Core Testing Components

The following diagram maps the major testing components to their specific classes and responsibilities:

Component Mapping to Code Entities

Sources: src/Factory.php1-271 src/FakeProcessResult.php1-165 src/FakeProcessDescription.php1-189 src/FakeProcessSequence.php1-93

Execution Flow: Real vs Fake

The Factory class controls whether processes execute against the real operating system or against fake handlers:

Handler Resolution Logic

The Factory class matches commands to handlers using the following priority:

1. Exact command match: Handler keyed by specific command string
2. Wildcard match: Handler keyed by '*'
3. No match + strict mode: Throws exception
4. No match + lenient mode: Falls back to real execution

Sources: src/Factory.php76-99 src/Factory.php134-147

Handler Return Types

Fake handlers (closures registered via Factory::fake()) can return six different types:

Return Type	Conversion	Use Case
int	new FakeProcessResult(exitCode: $int)	Simplest fake, exit code only
string or array	new FakeProcessResult(output: $value)	Common case, just output
ProcessResult	Used directly	Full control over result
FakeProcessDescription	$desc->toProcessResult($command)	Complex behavior (iterations, streaming)
FakeProcessSequence	$sequence() returns next result	Different result per call
Throwable	Thrown immediately	Simulate exceptions

Example Handler Registrations

Sources: src/Factory.php76-99

Recording and Assertion Workflow

The following diagram shows how the recording and assertion systems work together:

Recording Array Structure

Each entry in Factory::$recorded is a two-element array:

Assertions iterate through this array to verify expected interactions.

Sources: src/Factory.php104-129 src/Factory.php150-222

Key Classes and Methods

Factory Class

The Factory class in src/Factory.php manages the entire testing system:

Method	Purpose	Lines
fake()	Enable faking and register handlers	76-99
result()	Create a FakeProcessResult	46-53
describe()	Create a FakeProcessDescription builder	58-61
sequence()	Create a FakeProcessSequence	68-71
isRecording()	Check if faking is enabled	104-107
recordIfRecording()	Conditionally record process	112-119
record()	Store process execution	124-129
preventStrayProcesses()	Enable strict mode	134-139
preventingStrayProcesses()	Check strict mode status	144-147
assertRan()	Assert process was executed	152-164
assertRanTimes()	Assert execution count	169-184
assertNotRan()	Assert process was not executed	189-201
assertDidntRun()	Alias for assertNotRan()	206-209
assertNothingRan()	Assert no processes executed	214-222

Sources: src/Factory.php1-271

FakeProcessResult Class

The FakeProcessResult class in src/FakeProcessResult.php implements ProcessResultContract to simulate completed processes:

Property/Method	Type	Purpose	Lines
$command	string	Command that was executed	32
$exitCode	int	Process exit code	33
$output	string	Standard output	16
$errorOutput	string	Error output	20
__construct()	Initialize with output/exit code	31-39
normalizeOutput()	Convert array/string to normalized string	44-58
command()	string	Get command	63-66
successful()	bool	Check if exit code is 0	79-82
failed()	bool	Check if exit code is non-zero	87-90
exitCode()	int	Get exit code	95-98
output()	string	Get standard output	103-106
errorOutput()	string	Get error output	119-122
throw()	Throw if failed	137-150
throwIf()	Conditionally throw if failed	157-164

Output Normalization

The normalizeOutput() method src/FakeProcessResult.php44-58 ensures consistent output formatting:

• Strings: Right-trim newlines, add single trailing newline
• Arrays: Each element becomes a line with trailing newline
• Empty values: Empty string

Sources: src/FakeProcessResult.php1-165

FakeProcessDescription Class

The FakeProcessDescription class in src/FakeProcessDescription.php provides a fluent builder for complex fake behavior:

Property/Method	Type	Purpose	Lines
$processId	?int	Simulated process ID	16
$output	array	Output buffer with types	23
$exitCode	int	Exit code	28
$runIterations	int	Times to report "running"	33
id()	Set process ID	38-43
output()	Add standard output line	48-59
errorOutput()	Add error output line	64-75
exitCode()	Set exit code	118-123
iterations()	Set run iterations	128-131
runsFor()	Set run iterations	136-141
toProcessResult()	Convert to FakeProcessResult	154-162

Output Buffer Structure

Each entry in $output is an array with:

Sources: src/FakeProcessDescription.php1-189

FakeProcessSequence Class

The FakeProcessSequence class in src/FakeProcessSequence.php returns different results on successive invocations:

Property/Method	Type	Purpose	Lines
$processes	array	Queue of results	24
$failWhenEmpty	bool	Throw when empty	25
$emptyProcess	Default when empty	15
__construct()	Initialize with processes	23-27
push()	Add result to sequence	32-37
whenEmpty()	Set default result	42-48
dontFailWhenEmpty()	Allow empty sequence	63-66
isEmpty()	bool	Check if depleted	71-74
__invoke()	Get next result	81-92

Invocation Behavior

When the sequence is invoked via __invoke():

1. If empty and $failWhenEmpty is true: throws OutOfBoundsException
2. If empty and $failWhenEmpty is false: returns $emptyProcess or new FakeProcessResult()
3. Otherwise: shifts and returns first element from $processes

Sources: src/FakeProcessSequence.php1-93

Integration with PendingProcess

The PendingProcess class integrates with the faking system through:

1. Fake Handler Storage: PendingProcess receives $fakeHandlers from Factory via withFakeHandlers() method
2. Handler Resolution: Before executing, checks for matching fake handler
3. Recording: After execution (real or fake), calls Factory::recordIfRecording()

This integration is transparent to application code, which simply calls run() or start() and receives either a real or fake result.

Sources: src/Factory.php255-258

Benefits of the Testing System

Benefit	Description
Speed	No actual process spawning, tests complete in milliseconds
Determinism	Fake results are predictable, eliminating flaky tests
Isolation	Tests don't depend on external binaries, file systems, or OS behavior
Edge Cases	Easy to simulate timeouts, errors, and unusual output patterns
Verification	Assertions confirm expected process interactions occurred
Flexibility	Six handler return types cover simple to complex scenarios