 |
VOOZH | about |
|
VOOZH | about |
This document explains the process assertion methods available on the Factory class for verifying process execution in tests. These methods enable test-driven development by allowing you to assert which processes ran, how many times they ran, and with what configurations.
For information about setting up process faking, see page 6.1 (Faking Overview). For details on configuring fake process behavior, see page 6.3 (Fake Process Descriptions) and page 6.4 (Fake Process Sequences).
When the Factory is in recording mode (after calling fake()), every process execution is captured and stored in an internal recording array. This mechanism forms the foundation for all assertion methods.
<old_str>
Diagram: Assertion Method Decision Tree
Sources: src/Factory.php19-29
The $recorded array at src/Factory.php24-29 stores tuples of [PendingProcess, ProcessResult] for each executed process. The PendingProcess object contains the command, environment variables, timeout settings, and other configuration. The ProcessResult contains the execution outcome including output, error output, and exit code.
Processes are recorded via the recordIfRecording() method at src/Factory.php112-119 which checks if recording is active before calling record() at src/Factory.php124-129:
| Method | Purpose | Parameters |
|---|---|---|
isRecording() | Check if factory is in recording mode | None |
recordIfRecording() | Conditionally record a process | PendingProcess, ProcessResultContract |
record() | Unconditionally record a process | PendingProcess, ProcessResultContract |
The Factory provides five assertion methods for verifying process execution. All assertions use PHPUnit's assertion system src/Factory.php11 and can be chained due to their fluent interface (returning $this).
Sources: src/Factory.php152-222
| Method | Purpose | Signature |
|---|---|---|
assertRan() | Verify at least one matching process ran | (Closure|string $callback): static |
assertRanTimes() | Verify exact number of matching processes | (Closure|string $callback, int $times = 1): static |
assertNotRan() | Verify no matching processes ran | (Closure|string $callback): static |
assertDidntRun() | Alias for assertNotRan() | (Closure|string $callback): static |
assertNothingRan() | Verify no processes ran at all | (): static |
Each assertion method (except assertNothingRan()) accepts either a string or a closure for matching processes. This dual interface provides flexibility for simple and complex matching scenarios.
Sources: src/Factory.php154 src/Factory.php171 src/Factory.php191
When you pass a string, it is matched against the command property of the PendingProcess:
The string is converted to a closure at src/Factory.php154:
When you pass a closure, it receives both the PendingProcess and ProcessResult objects, allowing complex assertions:
The closure is invoked at src/Factory.php158 (for assertRan) with both array elements:
Verifies that at least one process matching the criteria was executed. This is useful for ensuring a critical process ran during your test, regardless of how many times it ran.
Diagram: Factory::assertRan() Execution Flow
Sources: src/Factory.php152-164
The method at src/Factory.php152-164 performs the following steps:
[PendingProcess, ProcessResult] pairPHPUnit::assertTrue() to verify count > 0Simple string matching:
Closure with environment check:
Checking successful execution:
Verifies that a process matching the criteria was executed exactly N times. This is essential for testing retry logic, polling mechanisms, or ensuring processes don't run more often than expected.
Diagram: Factory::assertRanTimes() Execution Flow
Sources: src/Factory.php169-184
The method at src/Factory.php169-184 differs from assertRan() by using PHPUnit::assertSame() src/Factory.php177-181 to verify an exact count:
Testing retry logic:
Ensuring single execution:
Testing polling:
Verifies that no process matching the criteria was executed. The assertDidntRun() method at src/Factory.php206-209 is an alias for assertNotRan().
Diagram: Factory::assertNotRan() and Factory::assertDidntRun() Execution Flow
Sources: src/Factory.php189-209
The method at src/Factory.php189-201 asserts that the filtered count equals zero:
Ensuring expensive operations are skipped:
Verifying conditional execution:
Using the alias:
Verifies that no processes were executed at all during the test. This is useful for testing code paths that should not trigger any process execution.
Diagram: Factory::assertNothingRan() Execution Flow
Sources: src/Factory.php214-222
This is the simplest assertion, checking if the $recorded array is empty at src/Factory.php216-219:
Unlike other assertions, this method takes no parameters and checks the entire recording array.
Testing cached results:
Testing feature flags:
Testing early returns:
When testing code that might run commands with different arguments:
Sources: src/Factory.php152-164
Verify processes run with correct environment configuration:
Sources: src/Factory.php152-164
Assert based on execution results:
Sources: src/Factory.php152-164
Verify processes have appropriate timeout settings:
Sources: src/Factory.php152-164
Make assertions about the output produced:
Sources: src/Factory.php152-164
All assertion methods return $this, enabling fluent assertion chains:
Sources: src/Factory.php152-222
Combine with assertRanTimes() to verify retry behavior:
Sources: src/Factory.php169-184
| Method | Use When | Returns True If |
|---|---|---|
assertRan() | Need to verify a process executed at least once | Count of matching processes > 0 |
assertRanTimes() | Need exact execution count (retries, polling) | Count of matching processes == N |
assertNotRan() | Need to verify a process was skipped | Count of matching processes == 0 |
assertDidntRun() | Same as assertNotRan() (alias) | Count of matching processes == 0 |
assertNothingRan() | Need to verify no processes executed at all | Recorded array is empty |
Sources: src/Factory.php152-222
Refresh this wiki