VOOZH about

URL: https://deepwiki.com/hypervel/process/6.1-faking-overview

⇱ Faking Overview | hypervel/process | DeepWiki

Loading...
Loading...
Menu

Faking Overview

Purpose and Scope

This page introduces the faking system in the hypervel/process package, which enables testing of process-dependent code without executing real operating system processes. The faking system provides a complete simulation layer that implements the same contracts as real process execution, allowing tests to run quickly and deterministically.

This page covers the architecture and core mechanics of the faking system. For details on specific capabilities, see:

For information about real process execution, see Core Components and Process Execution.

The Dual Execution Model

The faking system implements a dual execution model where the Factory class acts as a control point that routes process creation through either real or fake execution paths. When faking is enabled, all process execution is intercepted and simulated.

Architecture Overview



Sources:





Enabling Fake Mode


The entry point for the faking system is the Factory::fake() method, which configures the factory to intercept all process execution and return fake results. This method accepts three types of input configurations.


Fake Mode Activation




Sources:



Configuration Options



























Input TypeSyntaxBehavior
NullFactory::fake()Returns empty FakeProcessResult for all processes
ClosureFactory::fake(fn($process) => ...)Calls closure for every process, receives PendingProcess instance
ArrayFactory::fake(['command' => $handler, ...])Maps specific commands to handlers, numeric keys create wildcard handlers


When an array is provided, each value can be either:


    

  • A Closure that receives the PendingProcess and returns a result
    • 

  • A direct result object (e.g., FakeProcessResult, FakeProcessSequence, FakeProcessDescription)
    • 



Sources:





Fake Handler Resolution


When a process is executed in fake mode, the Factory resolves which handler should simulate the process based on the command string and the configured fake handlers.


Handler Lookup Process




Sources:





Recording Infrastructure


The Factory maintains a complete record of all process executions when in fake mode. This recording enables post-execution assertions to verify that the correct processes were invoked with expected parameters.


Recording State Management


The Factory class tracks recording state through several properties:
































PropertyTypePurpose
recordingboolIndicates whether fake mode is active
recordedarray<int, array>Stores each executed process as [PendingProcess, ProcessResult] pair
fakeHandlersarray<string, Closure>Maps command patterns to handler closures
preventStrayProcessesboolIf true, throws exception for unfaked processes




Sources:



The recordIfRecording() method at src/Factory.php112-119 conditionally records processes only when fake mode is active, while record() at src/Factory.php124-129 unconditionally appends to the recorded array.




Fake Implementation Classes


The faking system provides concrete implementations that mirror the real execution classes but with simulated behavior.


Fake Class Hierarchy




Sources:



Factory Helper Methods


The Factory class provides convenience methods for creating fake objects:



























MethodReturn TypePurpose
result()FakeProcessResultCreates simple fake result with output, error output, and exit code
describe()FakeProcessDescriptionStarts fluent definition of detailed fake process behavior
sequence()FakeProcessSequenceCreates sequence of fake results for multiple invocations


These methods are documented at src/Factory.php46-71


FakeProcessResult


FakeProcessResult implements the ProcessResult contract and encapsulates simulated execution outcomes. It can be instantiated directly via Factory::result() or created by FakeProcessDescription::toProcessResult().


Sources:



FakeProcessDescription


FakeProcessDescription provides a fluent interface for defining detailed fake process behavior including:


    

  • Process ID assignment
    • 

  • Line-by-line standard output and error output
    • 

  • Exit codes
    • 

  • Simulated run iterations for async processes
    • 



The description can be converted to a result via toProcessResult() at src/FakeProcessDescription.php154-162


Sources:





Process Recording Workflow


The complete flow from fake configuration to assertion verification follows this pattern:




Sources:





Integration with PendingProcess


When Factory creates a PendingProcess instance via newPendingProcess(), it injects the fake handlers into the pending process. This allows the pending process to check for fake handlers during execution and route accordingly.


The injection occurs at src/Factory.php255-258 via the withFakeHandlers() method call.


Sources:





Key Design Principles


The faking system adheres to several architectural principles:


    

  1. Contract Compliance: All fake implementations return objects that implement the same contracts as real execution, ensuring transparent substitution
    2. 

  2. Recording by Default: When fake mode is enabled, all executions are automatically recorded for later assertion
    3. 

  3. Flexible Configuration: Three input modes (null, closure, array) accommodate different testing needs from simple to complex
    4. 

  4. Command Matching: Supports both exact command matching and wildcard patterns for flexible handler resolution
    5. 

  5. Safety Mechanisms: Optional preventStrayProcesses flag prevents accidental real execution during tests
    6. 



Sources: