Preventing Stray Processes

Purpose & Scope

This document describes the stray process prevention feature, which ensures comprehensive test coverage by throwing exceptions when un-faked processes are attempted during testing. This feature helps prevent tests from accidentally executing real system commands when all process interactions should be simulated.

For information about enabling faking and configuring fake handlers, see 6.1 Faking Overview. For information about verifying process interactions in tests, see 6.6 Process Assertions.

---

Overview

A stray process is a process execution attempt that occurs during testing when:

• The Factory is in recording/faking mode (via fake())
• No registered fake handler matches the command being executed
• The stray prevention feature is enabled

This feature provides a safety net to ensure all process interactions in tests are explicitly defined, preventing:

• Accidental execution of real system commands during testing
• Incomplete test doubles that miss some code paths
• Non-deterministic test behavior from unexpected process calls
• Side effects from real process execution in test environments

Sources: src/Factory.php41 src/PendingProcess.php222-224 src/PendingProcess.php248-250

---

Configuration

Enabling Stray Process Prevention

The Factory::preventStrayProcesses() method enables or disables the feature:

Checking Prevention Status

The Factory::preventingStrayProcesses() method returns the current state:

Sources: src/Factory.php134-139 src/Factory.php144-147

---

State Configuration Matrix

The behavior of process execution depends on two factory states:

Recording (Faking)	Preventing Stray Processes	Behavior When No Handler Matches
false	false	Real process executes normally
false	true	Real process executes normally (prevention requires recording)
true	false	Real process executes, gets recorded
true	true	RuntimeException thrown

Key Insight: Stray process prevention only takes effect when both conditions are met:

1. Factory is recording (isRecording() returns true)
2. Prevention is enabled (preventingStrayProcesses() returns true)

Sources: src/PendingProcess.php218-224 src/PendingProcess.php243-250

---

Detection and Exception Flow

Synchronous Process Detection (run)

Diagram: Stray Process Detection in Synchronous Execution

Sources: src/PendingProcess.php212-230

Asynchronous Process Detection (start)

Diagram: Stray Process Detection in Asynchronous Execution

Sources: src/PendingProcess.php237-253

---

Exception Details

Exception Type

When a stray process is detected, a RuntimeException is thrown with a descriptive message:

RuntimeException: Attempted process [<command>] without a matching fake.

The <command> placeholder contains the actual command line that was attempted, as returned by Process::getCommandline().

Exception Thrown From

The exception originates from:

• PendingProcess::run() for synchronous execution - src/PendingProcess.php223
• PendingProcess::start() for asynchronous execution - src/PendingProcess.php249

Sources: src/PendingProcess.php222-224 src/PendingProcess.php248-250

---

Code Entity Mapping

Factory Class Components

Diagram: Code Entity Relationships for Stray Process Prevention

Sources: src/Factory.php22 src/Factory.php41 src/Factory.php76-99 src/Factory.php134-147 src/PendingProcess.php212-253 src/PendingProcess.php307-311

---

Usage Patterns

Strict Testing Mode (Recommended)

Enable stray process prevention to enforce comprehensive faking:

Lenient Testing Mode

Allow un-faked processes to execute (not recommended for most tests):

Conditional Prevention

Enable prevention based on test configuration:

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

---

Integration with Handler Matching

The stray process detection integrates with the fake handler matching system defined in PendingProcess::fakeFor():

Handler Matching Logic

Diagram: Handler Matching and Stray Detection

The matching uses Hypervel\Support\Str::is() for wildcard pattern matching:

• * matches any command (global handler)
• git * matches any git command
• git status matches exact command only

Sources: src/PendingProcess.php307-311

---

Best Practices

Always Enable in Unit Tests

Use Global Handlers for Simple Cases

When all processes should return the same result:

Be Explicit with Command Patterns

Prefer specific patterns over global wildcards:

Document Expected Commands

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

---

Implementation Details

Property Storage

The prevention state is stored in the Factory::$preventStrayProcesses property:

Source: src/Factory.php39-41

Check Sequence

Both run() and start() methods perform the same check sequence:

1. Convert command to Symfony\Component\Process\Process instance
2. Get command line string via Process::getCommandline()
3. Call fakeFor($command) to search for matching handler
4. If no handler found:
   • Check $this->factory->isRecording() (is faking enabled?)
   • Check $this->factory->preventingStrayProcesses() (is prevention enabled?)
   • If both true: throw RuntimeException
   • Otherwise: execute real process

Sources: src/PendingProcess.php218-224 src/PendingProcess.php243-250

Exception Message Format

The exception message includes the attempted command:

This provides clear debugging information about which command was not mocked.

Sources: src/PendingProcess.php223 src/PendingProcess.php249

---

Execution Path Comparison

With Stray Prevention Disabled

Step	Action
1	Command executed via run() or start()
2	Check for fake handler
3a	If handler found: execute fake
3b	If no handler: execute real process
4	Return result

With Stray Prevention Enabled

Step	Action
1	Command executed via run() or start()
2	Check for fake handler
3a	If handler found: execute fake
3b	If no handler found: check prevention
4a	If preventing: throw RuntimeException
4b	If not preventing: execute real process
5	Return result (if no exception)

Sources: src/PendingProcess.php212-230 src/PendingProcess.php237-253

---

Related Features

This feature works in conjunction with:

• Handler Registration: 6.1 Faking Overview - configuring which processes to fake
• Process Recording: src/Factory.php112-129 - tracking executed processes
• Assertions: 6.6 Process Assertions - verifying expected process interactions

The combination of these features enables comprehensive process testing:

Sources: src/Factory.php76-99 src/Factory.php112-129 src/Factory.php134-139 src/Factory.php152-222