Fake Process Sequences

Purpose and Scope

FakeProcessSequence enables stateful testing scenarios by returning different results on successive invocations of the same command. This class allows tests to simulate processes that exhibit different behavior across multiple executions, such as retry scenarios, progressive state changes, or time-dependent operations.

For basic fake process results that don't change across invocations, see Fake Process Results. For complex single-execution fakes with detailed configuration, see Fake Process Descriptions. For general information about the faking system, see Faking Overview.

Sources: src/FakeProcessSequence.php1-93

---

Overview

FakeProcessSequence maintains an ordered array of process results or descriptions that are returned sequentially on each invocation. When used as a fake handler in Factory::fake(), the sequence automatically shifts to the next result each time the command is executed.

Sources: src/FakeProcessSequence.php10-27 src/FakeProcessSequence.php81-92

---

Creating Sequences

Sequences are created by instantiating FakeProcessSequence with optional initial processes and a failWhenEmpty flag:

Constructor Parameter	Type	Default	Description
$processes	array	[]	Initial array of process results to add to the sequence
$failWhenEmpty	bool	true	Whether to throw OutOfBoundsException when sequence is exhausted

Sources: src/FakeProcessSequence.php23-27

---

Adding Results to Sequences

The push() method adds results to the end of the sequence. It accepts multiple input types and normalizes them to FakeProcessDescription or ProcessResultContract instances:

Input Type	Normalized To	Description
string	FakeProcessResult	Creates result with given string as output
array	FakeProcessResult	Creates result with array elements as output lines
FakeProcessDescription	FakeProcessDescription	Used directly without conversion
ProcessResultContract	ProcessResultContract	Used directly without conversion

Push Method Flow

Example usage:

Sources: src/FakeProcessSequence.php32-37 src/FakeProcessSequence.php53-58

---

Empty Sequence Handling

FakeProcessSequence provides three strategies for handling invocations after all results have been consumed:

Fail on Empty (Default)

When failWhenEmpty is true (default), the sequence throws OutOfBoundsException when invoked after exhaustion:

Custom Empty Response

The whenEmpty() method sets a fallback result and disables failure on empty:

Silent Empty Response

The dontFailWhenEmpty() method returns an empty success result when exhausted:

Empty Handling State Diagram

Sources: src/FakeProcessSequence.php42-48 src/FakeProcessSequence.php63-66

---

Invocation Behavior

FakeProcessSequence implements the __invoke() magic method, allowing instances to be used as callable handlers in Factory::fake(). Each invocation shifts the next result from the array:

Invocation Flow

Sources: src/FakeProcessSequence.php81-92

---

Integration with Factory

FakeProcessSequence is used as a handler value in Factory::fake() method. When the Factory encounters a sequence handler, it invokes the sequence for each matching process execution:

Sources: src/FakeProcessSequence.php81-92

---

Use Cases

Retry Logic Testing

Test code that retries failing processes until success:

Progressive State Changes

Simulate processes that affect system state over time:

Degradation Scenarios

Test behavior when a command gradually degrades:

Exhaustion Detection

Test that code handles sequence exhaustion appropriately:

Sources: src/FakeProcessSequence.php1-93

---

Method Reference

Method	Parameters	Returns	Description
__construct()	array $processes = [] bool $failWhenEmpty = true	-	Creates new sequence with optional initial processes
push()	string|array|FakeProcessDescription|ProcessResultContract $process	static	Adds a result to the end of the sequence
whenEmpty()	string|array|FakeProcessDescription|ProcessResultContract $process	static	Sets fallback result for empty sequence
dontFailWhenEmpty()	-	static	Makes empty sequence return empty success result
isEmpty()	-	bool	Checks if all results have been consumed
__invoke()	-	FakeProcessDescription|ProcessResultContract	Returns next result in sequence

Internal Methods

Method	Parameters	Returns	Description
toProcessResult()	string|array|FakeProcessDescription|ProcessResultContract $process	FakeProcessDescription|ProcessResultContract	Normalizes input to FakeProcessResult or passes through objects

Sources: src/FakeProcessSequence.php1-93

---

Class Properties

Property	Type	Visibility	Default	Description
$processes	array<int, mixed>	protected	[]	Array of remaining results in the sequence
$failWhenEmpty	bool	protected	true	Whether to throw exception when sequence is empty
$emptyProcess	FakeProcessDescription|ProcessResultContract|null	protected	null	Fallback result returned when sequence is empty

Sources: src/FakeProcessSequence.php14-26