Fake Process Results

Purpose and Scope

This page documents the FakeProcessResult class, which implements the ProcessResultContract interface to simulate completed process outcomes during testing. FakeProcessResult allows tests to define precise process behavior—exit codes, output, and error output—without executing actual commands.

For information about enabling the faking system and configuring handlers, see Faking Overview. For building complex fake process behavior, see Fake Process Descriptions. For simulating asynchronous process execution, see Fake Invoked Processes.

---

Overview

The FakeProcessResult class provides a lightweight simulation of process execution results. It stores all necessary data (command, exit code, output streams) as simple properties and implements the same interface as the real ProcessResult class, enabling polymorphic usage throughout the application.

Class Structure

Sources: src/FakeProcessResult.php1-165 src/Contracts/ProcessResult.php1-59

---

Creating Fake Process Results

Constructor Parameters

The FakeProcessResult constructor accepts four parameters, all with sensible defaults for quick result creation:

Parameter	Type	Default	Description
$command	string	''	The command string that was "executed"
$exitCode	int	0	The process exit code (0 = success)
$output	array|string	''	Standard output from the process
$errorOutput	array|string	''	Error output from the process

Sources: src/FakeProcessResult.php31-39

Basic Usage Examples

Sources: src/FakeProcessResult.php31-39

Output Normalization

The FakeProcessResult class automatically normalizes both $output and $errorOutput parameters to ensure consistent newline handling. This normalization occurs in the constructor via the normalizeOutput() method.

Sources: src/FakeProcessResult.php44-58

Normalization Rules

1. Empty input (empty string or empty array): Returns empty string ''
2. String input: Trims trailing newlines, adds exactly one newline at the end
3. Array input: Each element is treated as a line, trimmed of trailing newlines, newline added, then all lines imploded

Normalization Examples

Input	Normalized Output
''	''
'line1'	'line1\n'
'line1\n'	'line1\n'
'line1\n\n'	'line1\n'
['line1', 'line2']	'line1\nline2\n'
['line1\n', 'line2\n']	'line1\nline2\n'

Sources: src/FakeProcessResult.php44-58

---

Inspecting Fake Results

Command and Status Methods

The FakeProcessResult class provides methods to inspect the simulated process outcome:

Method	Return Type	Description
command()	string	Returns the command string
successful()	bool	Returns true if exit code is 0
failed()	bool	Returns true if exit code is not 0
exitCode()	int	Returns the process exit code

Sources: src/FakeProcessResult.php60-98

Sources: src/FakeProcessResult.php78-98

Output Inspection Methods

Method	Return Type	Description
output()	string	Returns the normalized standard output
seeInOutput(string $output)	bool	Checks if output contains the given string
errorOutput()	string	Returns the normalized error output
seeInErrorOutput(string $output)	bool	Checks if error output contains the given string

Sources: src/FakeProcessResult.php100-130

Usage Examples

Sources: src/FakeProcessResult.php100-130

---

Error Handling

The FakeProcessResult class implements the same error handling methods as the real ProcessResult, allowing tests to verify exception throwing behavior.

throw() Method

The throw() method throws a ProcessFailedException if the process failed (exit code is not 0). If successful, it returns $this for chaining.

Sources: src/FakeProcessResult.php137-150

Optional Callback Parameter

The throw() method accepts an optional callback that receives the result and exception before throwing. This allows for logging or custom handling:

Sources: src/FakeProcessResult.php137-150

throwIf() Method

The throwIf() method conditionally throws based on a boolean condition. This is useful for context-dependent error handling:

Sources: src/FakeProcessResult.php157-164

---

Immutability and Command Assignment

The withCommand() method creates a new FakeProcessResult instance with a different command string, preserving all other properties. This is useful when a fake handler returns a generic result that needs to be associated with a specific command.

Sources: src/FakeProcessResult.php71-74

Usage in Handler Context

The withCommand() method is automatically invoked by the faking system when a fake handler returns a FakeProcessResult:

Sources: src/FakeProcessResult.php71-74

---

Integration with the Faking System

Handler Return Patterns

Fake handlers can return FakeProcessResult instances directly, or the faking system will create them automatically from simpler return types:

Sources: src/FakeProcessResult.php71-74

Complete Example

Sources: src/FakeProcessResult.php1-165 src/Contracts/ProcessResult.php1-59

---

Method Reference

Constructor

Sources: src/FakeProcessResult.php31-39

Command Methods

Method	Signature	Description
command()	(): string	Returns the command string
withCommand(string)	(string): FakeProcessResult	Returns new instance with different command

Sources: src/FakeProcessResult.php60-74

Status Methods

Method	Signature	Description
successful()	(): bool	Returns true if exit code is 0
failed()	(): bool	Returns true if exit code is not 0
exitCode()	(): int	Returns the exit code

Sources: src/FakeProcessResult.php78-98

Output Methods

Method	Signature	Description
output()	(): string	Returns normalized standard output
seeInOutput(string)	(string): bool	Checks if output contains string
errorOutput()	(): string	Returns normalized error output
seeInErrorOutput(string)	(string): bool	Checks if error output contains string

Sources: src/FakeProcessResult.php100-130

Error Handling Methods

Method	Signature	Description
throw(?callable)	(?callable): static	Throws ProcessFailedException if failed
throwIf(bool, ?callable)	(bool, ?callable): static	Conditionally throws if condition is true

Sources: src/FakeProcessResult.php137-164

Protected Methods

Method	Signature	Description
normalizeOutput(array|string)	(array|string): string	Normalizes output to consistent newline format

Sources: src/FakeProcessResult.php44-58