VOOZH about

URL: https://deepwiki.com/hypervel/process/6.3-fake-process-descriptions

⇱ Fake Process Descriptions | hypervel/process | DeepWiki

Loading...
Loading...
Menu

Fake Process Descriptions

Purpose and Scope

This document explains the FakeProcessDescription class, which is the primary mechanism for defining simulated process behavior in the testing system. FakeProcessDescription acts as a fluent builder that allows tests to specify exactly how a fake process should behave, including its output streams, exit code, process ID, and how long it should simulate "running" for asynchronous execution.

This page focuses on the configuration API and internal structure of FakeProcessDescription. For an overview of how faking is enabled via Factory::fake(), see page 6.1 (Faking Overview). For handling multiple invocations with different behaviors, see page 6.4 (Fake Process Sequences). For verifying that processes ran during tests, see page 6.6 (Process Assertions).

Overview

The FakeProcessDescription class provides a fluent interface for specifying the complete behavior of a simulated process. Instead of executing actual system commands, it returns pre-configured output, exit codes, and simulates process lifecycle events. This enables deterministic testing without external dependencies.

Sources:

  • src/FakeProcessDescription.php:11-189

Core Architecture

The following diagram shows the structure of FakeProcessDescription and its relationships with other fake components:

FakeProcessDescription Class Structure and Flow



Sources:





Configuration Properties


FakeProcessDescription maintains four core properties that define process behavior:










































PropertyTypeDefaultPurposeDefined At
processId?int1000The simulated process ID returned by id() callssrc/FakeProcessDescription.php16
outputarray<int, array<string, string>>[]Ordered array of output entries with type and buffersrc/FakeProcessDescription.php23
exitCodeint0The process exit code (0 = success)src/FakeProcessDescription.php28
runIterationsint0Number of times running() returns true for async processessrc/FakeProcessDescription.php33


The output array stores both standard output and error output in the order they are defined, with each entry containing:


    

  • type: either 'out' (standard output) or 'err' (error output)
    • 

  • buffer: the actual output text, always terminated with a newline
    • 



Sources:





Fluent Builder API


Process Identity


The id() method sets the simulated process ID:




Sets the simulated process ID that will be returned by InvokedProcess::id() calls. The default value is 1000 if not configured.


Sources:





Standard Output Configuration


The output() method adds standard output:




Adds standard output to the process. Accepts either a single string or an array of strings. Each line is automatically normalized to end with a newline character. When an array is provided, each element is added as a separate output entry, preserving order.


Implementation Details:



Sources:





Error Output Configuration


The errorOutput() method adds error output:




Adds error output to the process. Functions identically to output() but stores entries with type set to 'err'. This allows standard output and error output to be interleaved in the order they were defined, simulating real process behavior where both streams can produce output simultaneously.


Sources:





Output Buffer Replacement


The replacement methods allow overwriting existing output:




These methods completely replace the existing output buffer instead of appending. replaceOutput() removes all existing standard output entries while preserving error output, and vice versa for replaceErrorOutput(). This is useful when you need to change the output after initial configuration.


Implementation:



Sources:





Exit Code Configuration


The exitCode() method sets the process exit code:




Sets the process exit code. Use 0 for successful processes (default) or any non-zero value to indicate failure. The exit code determines whether ProcessResult::successful() returns true or false.


Sources:





Run Duration Configuration


The iteration methods control how long the fake process simulates running:




Both methods set the runIterations property, which controls how many times FakeInvokedProcess::running() will return true before indicating the process has completed. This simulates a long-running asynchronous process that can be polled.


    

  • iterations(5) means running() returns true five times, then false
    • 

  • iterations(0) means the process completes immediately
    • 

  • iterations() is an alias for runsFor() at src/FakeProcessDescription.php128-131
    • 



Sources:





Output Buffer System


Output Buffer Structure and Resolution


The following diagram shows how the output property maintains ordering between standard and error output:




The output buffer maintains insertion order, allowing standard and error output to be interleaved. When converted to strings via resolveOutput() and resolveErrorOutput(), entries are filtered by type and concatenated. This design allows FakeInvokedProcess to simulate incremental output delivery during asynchronous execution.


Sources:





Conversion Methods


Converting to Symfony Process


The toSymfonyProcess() method creates a Symfony Process:




Creates a Symfony Process instance from the command string using Process::fromShellCommandline(). This method exists for compatibility but does not actually configure the Symfony process with the fake behavior - it simply returns a shell process wrapper. The fake behavior is applied through FakeInvokedProcess instead.


Sources:





Converting to Process Result


The toProcessResult() method converts the description to a result object:




Converts the fake description into a FakeProcessResult instance. This method:


    

  1. Calls resolveOutput() to convert output buffer entries with type='out' into a single string
    2. 

  2. Calls resolveErrorOutput() to convert output buffer entries with type='err' into a single string
    3. 

  3. Creates a FakeProcessResult with the command, exit code, and both output streams
    4. 

  4. Returns an object implementing the ProcessResult contract
    5. 



The resolution methods filter the output array by type, extract buffer values, join them, and ensure proper newline termination.


Sources:





Integration with Asynchronous Execution


Asynchronous Process Simulation Flow


The following diagram shows how FakeProcessDescription integrates with FakeInvokedProcess to simulate asynchronous process behavior:




The runIterations property controls the simulation of process runtime. Each call to running() decrements an internal counter in FakeInvokedProcess. When the counter reaches zero, the process is considered complete, and all remaining output is delivered.


Sources:





Incremental Output Delivery


Output Streaming Mechanism


For asynchronous processes with output handlers, FakeInvokedProcess uses the ordered output buffer to deliver output incrementally:




FakeInvokedProcess maintains separate index pointers that track which output entries have been delivered. Each time running() or id() is called, the next undelivered output line from the FakeProcessDescription.output array is passed to the output handler, simulating real-time output streaming.


Sources:





Usage Patterns


Basic Success Scenario




Sources:





Failure with Error Output




Sources:





Interleaved Output Streams




Sources:





Multi-line Output




Sources:





Simulating Long-Running Process




Sources:





Custom Process ID




Sources:





Implementation Details


Output Normalization


All output strings are normalized to ensure consistent newline handling:


    

  1. Input strings have trailing newlines removed via rtrim($output, "\n")
    2. 

  2. A single newline is appended: rtrim($output, "\n") . "\n"
    3. 

  3. This ensures each buffer entry represents exactly one line with a newline
    4. 



This normalization happens in the output() and errorOutput() methods to maintain consistency.


Sources:





Output Resolution Algorithm


The resolveOutput() and resolveErrorOutput() methods convert the mixed output buffer into separate strings:


    

  1. Filter the $this->output array by type ('out' or 'err')
    2. 

  2. Map each entry to its buffer value
    3. 

  3. Implode the buffers into a single string
    4. 

  4. Trim trailing newlines and add a single newline
    5. 

  5. Return empty string if no output of that type exists
    6. 



This algorithm is implemented using Hyperf Collections for functional-style processing.


Sources:





Relationship Diagram




FakeProcessDescription is created and configured by the fake handlers system (covered in Faking Overview). It serves as the source of truth for both synchronous (run()) and asynchronous (start()) execution modes. For synchronous execution, it's immediately converted to FakeProcessResult. For asynchronous execution, it's wrapped in FakeInvokedProcess which controls the simulation of process lifecycle.


Sources:


    

  • src/FakeProcessDescription.php:146-162
    • 

  • src/FakeInvokedProcess.php:43-47
    • 

  • src/FakeProcessResult.php:31-39
    •