Facilitates the execution of the PHPUnit testing framework.
Description
This class MUST NOT be overridden and SHALL configure testing parameters dynamically.
'reports:tests'
'Runs PHPUnit tests.'
['phpunit', 'tests']
Constants
Properties
Methods
Adds the standard cache directory option to the current command.
Adds the standard cache control option to the current command.
Adds the standard JSON output options to the current command.
Configures the testing command input constraints.
Triggers the PHPUnit engine based on resolved paths and settings.
Resolves whether cache writes SHOULD be enabled for the current invocation.
Determines whether JSON output was requested.
Determines whether pretty JSON output was requested.
Returns the explicit cache flag that SHOULD be forwarded to nested commands.
Resolves a nested cache directory for a child command.
Attempts to decode structured PHPUnit output while preserving any non-JSON prelude that was emitted before the final reporter payload.
Logs a failed command result and returns the failure exit code.
Forces the PHPUnit subprocess to expose the agent reporter payload.
Determines whether the current invocation explicitly passed `--cache-dir`.
Detects whether a tests path option still points at the default project tests directory.
Determines whether structured JSON output SHOULD be enabled implicitly.
Determines whether cache writes were explicitly disabled for the current invocation.
Determines whether a boolean input option was enabled.
Logs a non-terminal command message unless structured JSON output is active.
Normalizes a project-relative path for resilient default-option comparisons.
Creates the bootstrap shim path passed to PHPUnit.
Resolves minimum-coverage value from injected environment abstraction.
Safely constructs an absolute path tied to a defined capability option.
Builds structured context for the executed PHPUnit process.
Builds the structured payload that will be emitted for agent-oriented runs.
Logs a successful command result and returns the success exit code.
Appends minimum-coverage validation data to the structured PHPUnit output payload.
public
string
AGENT_ENVIRONMENT_VALUE
=
'fast-forward/dev-tools'
public
string
AGENT_ENVIRONMENT_VARIABLE
=
'AI_AGENT'
public
string
CONFIG
=
'phpunit.xml'
Description
identifies the local configuration file for PHPUnit processes
public
string
ENV_MINIMUM_COVERAGE
=
'FAST_FORWARD_MIN_COVERAGE'
private
string
PROCESS_LABEL
=
'Running PHPUnit Tests'
private
BootstrapShimGenerator
$bootstrapShimGenerator
private
ComposerJsonInterface
$composer
private
CoverageSummaryLoaderInterface
$coverageSummaryLoader
private
EnvironmentInterface
$environment
private
FileLocatorInterface
$fileLocator
private
FilesystemInterface
$filesystem
private
ProcessBuilderInterface
$processBuilder
private
ProcessQueueInterface
$processQueue
private
ProjectCapabilitiesResolverInterface
$projectCapabilitiesResolver
public
__construct(CoverageSummaryLoaderInterface
$coverageSummaryLoader, ComposerJsonInterface
$composer, FilesystemInterface
$filesystem, BootstrapShimGenerator
$bootstrapShimGenerator, FileLocatorInterface
$fileLocator, ProcessBuilderInterface
$processBuilder, ProcessQueueInterface
$processQueue, ProjectCapabilitiesResolverInterface
$projectCapabilitiesResolver, EnvironmentInterface
$environment) : mixed
Parameters
Description
the loader used for coverage-php summaries
Description
the composer.json reader for autoload information
Description
the filesystem utility used for path resolution
Description
the generator used to build the PHPUnit bootstrap shim
$fileLocator
:
FileLocatorInterface
Description
the file locator used to resolve PHPUnit configuration
Description
the builder used to assemble the PHPUnit process
Description
the queue used to execute PHPUnit
Description
the project capability resolver
Description
the environment resolver for CLI-scoped flags
Adds the standard cache directory option to the current command.
protected
addCacheDirOption(
string
$description,
string
$default) : static
Parameters
$description
:
string
Description
the cache directory option description
$default
:
string
Description
the command-specific default cache directory
Return values
Adds the standard cache control option to the current command.
protected
addCacheOption(
string
$description) : static
Parameters
$description
:
string
Description
the cache option description
Return values
Adds the standard JSON output options to the current command.
protected
addJsonOption() : static
Return values
Configures the testing command input constraints.
protected
configure() : void
Description
The method MUST specify valid arguments for testing paths, caching directories, bootstrap scripts, and coverage instructions. It SHALL align with robust testing standards.
Triggers the PHPUnit engine based on resolved paths and settings.
protected
execute(InputInterface
$input, OutputInterface
$output) : int
Description
The method MUST assemble the necessary commands to initiate PHPUnit securely. It SHOULD optionally construct advanced configuration arguments such as caching and coverage.
Parameters
$input
:
InputInterface
Description
the runtime instruction set from the CLI
$output
:
OutputInterface
Description
the console feedback relay
Return values
Description
the status integer describing the termination code
Resolves whether cache writes SHOULD be enabled for the current invocation.
protected
isCacheEnabled(InputInterface
$input[,
bool
$default = true]) : bool
Parameters
$input
:
InputInterface
Description
the current command input
$default
:
bool
=
true
Description
the command-specific default cache behavior when the option is omitted
Return values
Determines whether JSON output was requested.
protected
isJsonOutput(InputInterface
$input) : bool
Description
The pretty-json flag SHALL imply JSON output.
Parameters
$input
:
InputInterface
Return values
Determines whether pretty JSON output was requested.
protected
isPrettyJsonOutput(InputInterface
$input) : bool
Parameters
$input
:
InputInterface
Return values
Returns the explicit cache flag that SHOULD be forwarded to nested commands.
protected
resolveCacheArgument(InputInterface
$input) : string|null
Parameters
$input
:
InputInterface
Description
the current command input
Return values
Resolves a nested cache directory for a child command.
protected
resolveCacheDirArgument(InputInterface
$input[,
string
$path = '']) : string|null
Parameters
$input
:
InputInterface
Description
the current command input
$path
:
string
=
''
Description
the child cache path relative to the current command cache root
Return values
private
configureCoverageArguments(InputInterface
$input, ProcessBuilderInterface
$processBuilder,
bool
$requiresCoverageReport) : ProcessBuilderInterface, string|null}
Parameters
$input
:
InputInterface
Description
the raw parameter definitions
Description
the process builder to extend with coverage arguments
$requiresCoverageReport
:
bool
Description
indicates whether a coverage-php report is required
Return values
Description
the extended builder and generated coverage-php report path
Attempts to decode structured PHPUnit output while preserving any non-JSON prelude that was emitted before the final reporter payload.
private
decodeStructuredProcessOutput(
string
$rawOutput) : array{array|null, string|null}
Parameters
$rawOutput
:
string
Description
the captured subprocess output
Return values
Description
decoded payload and preserved supplemental output
Logs a failed command result and returns the failure exit code.
private
failure(
string
$message, InputInterface
$input[,
array<string, mixed>
$context = []][,
string|null
$file = null][,
int|null
$line = null]) : int
Parameters
$message
:
string
Description
the failure message
$input
:
InputInterface
Description
the originating command input
$context
:
array<string, mixed>
=
[]
Description
optional extra log context
$file
:
string|null
=
null
Description
the related file path when known
$line
:
int|null
=
null
Description
the related line when known
Return values
Forces the PHPUnit subprocess to expose the agent reporter payload.
private
forceAgentReporter(Process
$process) : void
Parameters
$process
:
Process
Description
the configured PHPUnit process
Determines whether the current invocation explicitly passed `--cache-dir`.
private
hasExplicitCacheDirArgument(InputInterface
$input) : bool
Parameters
$input
:
InputInterface
Description
the current command input
Return values
Detects whether a tests path option still points at the default project tests directory.
private
isDefaultTestsPath(
string
$testsPath) : bool
Parameters
$testsPath
:
string
Description
the tests path argument received from the CLI
Return values
Description
true when the provided path is equivalent to the default tests directory
Determines whether structured JSON output SHOULD be enabled implicitly.
private
isImplicitJsonOutputEnabled() : bool
Description
Commands MAY opt into runtime-environment-aware behavior by exposing a
$runtimeEnvironment property. Commands that do not expose it SHALL fall
back to the shared runtime-environment service from the DevTools container.
Return values
Determines whether cache writes were explicitly disabled for the current invocation.
private
isNoCacheRequested(InputInterface
$input) : bool
Description
The Composer application already provides a global --no-cache flag, so commands
SHALL reuse that switch instead of redefining a local negated variant.
Parameters
$input
:
InputInterface
Description
the current command input
Return values
Determines whether a boolean input option was enabled.
private
isOptionEnabled(InputInterface
$input,
string
$option) : bool
Parameters
$input
:
InputInterface
$option
:
string
Return values
Logs a non-terminal command message unless structured JSON output is active.
private
log(
string
$message, InputInterface
$input[,
array<string, mixed>
$context = []][,
string
$logLevel = LogLevel::INFO]) : void
Parameters
$message
:
string
Description
the progress message
$input
:
InputInterface
Description
the originating command input
$context
:
array<string, mixed>
=
[]
Description
optional extra log context
$logLevel
:
string
=
LogLevel::INFO
Description
the PSR-3 log level used for the message
Normalizes a project-relative path for resilient default-option comparisons.
private
normalizeProjectRelativePath(
string
$path) : string
Parameters
$path
:
string
Description
the project-relative path to normalize
Return values
Description
the normalized project-relative path
Creates the bootstrap shim path passed to PHPUnit.
private
resolveBootstrapPath(InputInterface
$input) : string
Parameters
$input
:
InputInterface
Description
the raw parameter definitions
Return values
Description
the generated bootstrap shim path
private
resolveMinimumCoverage(InputInterface
$input) : float|null
Parameters
$input
:
InputInterface
Description
the raw parameter definitions
Return values
Description
the validated minimum coverage percentage, if configured
Resolves minimum-coverage value from injected environment abstraction.
private
resolveMinimumCoverageFromEnvironment() : string|false|null
Return values
Description
the configured coverage threshold or a falsey fallback
Safely constructs an absolute path tied to a defined capability option.
private
resolvePath(InputInterface
$input,
string
$option) : string
Description
The method MUST compute absolute properties based on the supplied input parameters. It SHALL strictly return a securely bounded path string.
Parameters
$input
:
InputInterface
Description
the raw parameter definitions
$option
:
string
Description
the requested option key to resolve
Return values
Description
validated absolute path string
Builds structured context for the executed PHPUnit process.
private
resolveProcessResultContext(OutputInterface
$processOutput,
int
$exitCode,
bool
$structuredOutput) : array<string, array<string, mixed>|OutputInterface>
Parameters
$processOutput
:
OutputInterface
Description
the output sink used while the process ran
$exitCode
:
int
Description
the exit code returned by the process queue
$structuredOutput
:
bool
Description
whether the command captured subprocess output for structured logging
Return values
private
resolveRuntimeEnvironment() : RuntimeEnvironmentInterface|null
Return values
Builds the structured payload that will be emitted for agent-oriented runs.
private
resolveStructuredProcessResultPayload(OutputInterface
$processOutput,
int
$exitCode) : array<string, mixed>
Parameters
$processOutput
:
OutputInterface
Description
the output sink used while the process ran
$exitCode
:
int
Description
the exit code returned by the process queue
Return values
Description
the structured process payload
Logs a successful command result and returns the success exit code.
private
success(
string
$message, InputInterface
$input[,
array<string, mixed>
$context = []][,
string
$logLevel = LogLevel::INFO]) : int
Parameters
$message
:
string
Description
the success message
$input
:
InputInterface
Description
the originating command input
$context
:
array<string, mixed>
=
[]
Description
optional extra log context
$logLevel
:
string
=
LogLevel::INFO
Description
the PSR-3 log level used for the successful result
Return values
private
validateMinimumCoverage(
string
$coverageReportPath,
float
$minimumCoverage) : array{int, string, array}
Parameters
$coverageReportPath
:
string
Description
the generated coverage-php report path
$minimumCoverage
:
float
Description
the required line coverage percentage
Return values
Description
validation result, human message, and structured coverage context
Appends minimum-coverage validation data to the structured PHPUnit output payload.
private
withStructuredCoverageValidationContext(
array<string, mixed>
$context,
array<string, float|int|string|null>
$coverageContext,
float
$minimumCoverage,
int
$validationResult,
string
$message) : array<string, mixed>
Parameters
$context
:
array<string, mixed>
Description
the command result context
$coverageContext
:
array<string, float|int|string|null>
Description
structured coverage metrics
$minimumCoverage
:
float
Description
the required coverage percentage
$validationResult
:
int
Description
the post-PHPUnit validation status
$message
:
string
Description
the validation message
Return values
Description
the enriched structured command context