Configuration API
This reference lists the builders that configure Greenlight runs.
These signatures are the public API.
ArtifactBuilder
Namespace: Greenlight\Config
Collects the configuration for attachment output and safety limits.
Size values use bytes or binary K, M, and G suffixes, with an optional final B.
final class ArtifactBuilderdirectory()
Sets the parent directory for retained attachments.
The default is build/greenlight-artifacts, relative to the command working directory.
public function directory(string $directory): selfPHPDoc:
@param non-empty-string $directory@throws InvalidConfiguration
maxAttachmentsPerTest()
Limits attachment count for one test across all attempts. The default is 32.
public function maxAttachmentsPerTest(int $count): selfPHPDoc:
@param positive-int $count@throws InvalidConfiguration
maxAttachmentSize()
Limits the size of one attachment. The default is 25M.
public function maxAttachmentSize(string $size): selfPHPDoc:
@param non-empty-string $size@throws InvalidConfiguration
maxTestSize()
Limits attachment bytes for one test across all attempts. The default is 100M.
public function maxTestSize(string $size): selfPHPDoc:
@param non-empty-string $size@throws InvalidConfiguration
maxRunAttachments()
Limits staged and retained attachment count for one run. The default is 10,000.
public function maxRunAttachments(int $count): selfPHPDoc:
@param positive-int $count@throws InvalidConfiguration
maxRunSize()
Limits staged and retained attachment bytes for one run. The default is 1G.
public function maxRunSize(string $size): selfPHPDoc:
@param non-empty-string $size@throws InvalidConfiguration
maxCompletedRuns()
Selects older completed runs for deletion when the retained run count exceeds this limit. No count-based retention limit applies by default.
public function maxCompletedRuns(int $count): selfPHPDoc:
@param positive-int $count@throws InvalidConfiguration
maxCompletedRunAge()
Selects completed runs for deletion after this many seconds from completion. No age-based retention limit applies by default.
public function maxCompletedRunAge(int $seconds): selfPHPDoc:
@param positive-int $seconds@throws InvalidConfiguration
maxRetainedSize()
Selects older completed runs for deletion when retained content exceeds this size. No size-based retention limit applies by default.
public function maxRetainedSize(string $size): selfPHPDoc:
@param non-empty-string $size@throws InvalidConfiguration
CoverageBuilder
Namespace: Greenlight\Config
Configures coverage collection and exports.
final class CoverageBuilderinclude()
Adds source paths to the coverage filter. Multiple calls add paths. Relative paths use the command working directory. An empty filter accepts all files that the driver reports.
public function include(string ...$paths): selfPHPDoc:
@param non-empty-string ...$paths@throws InvalidConfiguration
driver()
Selects pcov or xdebug without fallback to the other driver.
Omit this call for automatic selection, which tries pcov before Xdebug.
public function driver(string $driver): selfPHPDoc:
@param non-empty-string $driver@throws InvalidConfiguration
minimumPercentage()
Sets the minimum accepted total line-coverage percentage.
public function minimumPercentage(float $percentage): selfPHPDoc:
@param float $percentage A value from 0 through 100 with at most two decimal places.@throws InvalidConfiguration
maximumUncoveredLines()
Sets the maximum accepted number of uncovered executable lines.
public function maximumUncoveredLines(int $lines): selfPHPDoc:
@param int<0, max> $lines@throws InvalidConfiguration
requireDriver()
Fails the run when the selected coverage driver is not available.
public function requireDriver(bool $required = true): selfexport()
Adds a coverage export. Multiple calls add exports.
The target is a directory for html and a file for other formats.
Relative targets use the command working directory.
public function export(string $format, string $target): selfPHPDoc:
@param 'json'|'lcov'|'clover'|'cobertura'|'html' $format@param non-empty-string $target@throws InvalidConfiguration
GreenlightConfig
Namespace: Greenlight\Config
Collects the configuration that greenlight.php returns.
final class GreenlightConfigcreate()
public static function create(): selfpaths()
Replaces the base test-discovery directories. The default is ['tests'].
Greenlight combines these paths with all suite paths when the command
has no suite selector. Relative paths use the command working directory.
public function paths(array $tests): selfPHPDoc:
@param non-empty-list<non-empty-string> $tests@throws InvalidConfiguration
suite()
Declares a named suite. Greenlight adds its paths to default discovery and makes the suite available to CLI selectors.
The configurator receives a SuiteBuilder. It must add at least one path
with in(). Greenlight ignores its return value, which permits short
arrow functions.
public function suite(string $name, callable $configurator): selfPHPDoc:
@param non-empty-string $name@param callable(SuiteBuilder): mixed $configurator@throws InvalidConfiguration
workers()
Sets the maximum worker count. The default, auto, uses the detected CPU count.
A count of one runs tests in the command process without process isolation.
Process-pool execution can use fewer workers when the selected work or resource limits restrict concurrency.
public function workers(int|string $count = 'auto'): selfPHPDoc:
@param positive-int|'auto' $count@throws InvalidConfiguration
resourceLimit()
Sets the maximum number of concurrent assignments that require the named resource.
A resource without an explicit resource limit has a limit of one.
public function resourceLimit(string $name, int $limit = 1): selfPHPDoc:
@param non-empty-string $name@param positive-int $limit@throws InvalidConfiguration
coverage()
Enables coverage collection and changes its settings. Each call starts with the current configuration. Greenlight ignores the configurator return value.
public function coverage(callable $configurator): selfPHPDoc:
@param callable(CoverageBuilder): mixed $configurator
watch()
Changes watch inputs and polling limits. Use --watch to start watch mode.
Each call starts with the current configuration. Greenlight ignores the configurator return value.
public function watch(callable $configurator): selfPHPDoc:
@param callable(WatchBuilder): mixed $configurator
artifacts()
Changes attachment output, safety limits, and retention settings. Each call starts with the current configuration. Greenlight ignores the configurator return value.
public function artifacts(callable $configurator): selfPHPDoc:
@param callable(ArtifactBuilder): mixed $configurator
storage()
Sets directories for persistent state, caches, generated code, and temporary run data. Each call starts with the current configuration.
public function storage(callable $configurator): selfPHPDoc:
@param callable(StorageBuilder): mixed $configurator
failOnDeprecation()
Fails an otherwise passed test if captured output contains a
deprecation. The diagnostic becomes the failure detail. Use
ignoreDeprecationsMatching() to exempt known dependency messages.
public function failOnDeprecation(bool $enabled = true): selfPHPDoc:
@see self::ignoreDeprecationsMatching()
failOnNotice()
Fails an otherwise passed test if captured output contains a notice.
public function failOnNotice(bool $enabled = true): selffailOnWarning()
Fails an otherwise passed test if captured output contains a warning.
public function failOnWarning(bool $enabled = true): selffailOnRisky()
Fails an otherwise passed test if the test verifies no expectations.
Use #[NoExpectations] to exempt a test that intentionally verifies no
expectations.
public function failOnRisky(bool $enabled = true): selffailOnSkipped()
Fails the run if its final summary contains a skipped test. The test keeps its skipped outcome and reason.
public function failOnSkipped(bool $enabled = true): selffailOnRetriedPass()
Fails the run if a test passes after retry. The test keeps its passed outcome and attempt count.
public function failOnRetriedPass(bool $enabled = true): selfignoreDeprecationsMatching()
Exempts deprecation messages from failOnDeprecation(). A pattern matches
part of a message without case sensitivity. A pattern that contains ”*”
or ”?” matches the complete message. Multiple calls add patterns.
public function ignoreDeprecationsMatching(string ...$patterns): selfPHPDoc:
@param non-empty-string ...$patterns@throws InvalidConfiguration
plugins()
public function plugins(\Closure ...$plugins): selfPHPDoc:
@param \Closure(): Plugin ...$plugins@throws InvalidConfiguration
failFast()
Stops new work after the first failed or errored test. Active assignments can finish after the limit. This option is disabled by default.
public function failFast(bool $enabled = true): selfrandomizeOrder()
If the seed is null, Greenlight selects and prints a seed when it resolves the command.
public function randomizeOrder(?int $seed = null): selfPHPDoc:
@param int<0, max>|null $seed@throws InvalidConfiguration
InvalidConfiguration
Namespace: Greenlight\Config
A configuration builder received an invalid value or an invalid combination. Use a named factory to create an error for a specific validation failure. The constructor is private.
final class InvalidConfiguration extends \InvalidArgumentExceptionemptyArtifactDirectory()
public static function emptyArtifactDirectory(): selfartifactDirectoryContainsNullByte()
public static function artifactDirectoryContainsNullByte(): selfinvalidArtifactCountPerTest()
public static function invalidArtifactCountPerTest(): selfinvalidArtifactCountPerRun()
public static function invalidArtifactCountPerRun(): selfinvalidCompletedRunCount()
public static function invalidCompletedRunCount(): selfinvalidCompletedRunAge()
public static function invalidCompletedRunAge(): selfemptyCoveragePath()
public static function emptyCoveragePath(): selfcoveragePathContainsNullByte()
public static function coveragePathContainsNullByte(): selfemptyCoverageDriver()
public static function emptyCoverageDriver(): selfcoveragePercentageOutOfRange()
public static function coveragePercentageOutOfRange(): selfcoveragePercentageTooPrecise()
public static function coveragePercentageTooPrecise(): selfnegativeUncoveredLineLimit()
public static function negativeUncoveredLineLimit(): selfemptyCoverageExport()
public static function emptyCoverageExport(): selfunknownCoverageFormat()
public static function unknownCoverageFormat(string $format): selfcoverageTargetContainsNullByte()
public static function coverageTargetContainsNullByte(): selftestPathsNotAList()
public static function testPathsNotAList(): selftestPathNotAString()
public static function testPathNotAString(): selfemptyTestPath()
public static function emptyTestPath(): selftestPathContainsNullByte()
public static function testPathContainsNullByte(): selfmissingTestPaths()
public static function missingTestPaths(): selfemptySuiteName()
public static function emptySuiteName(): selfduplicateSuite()
public static function duplicateSuite(string $name): selfinvalidResourceName()
public static function invalidResourceName(\InvalidArgumentException $previous): selfinvalidResourceLimit()
public static function invalidResourceLimit(string $name, int $limit): selfduplicateResourceLimit()
public static function duplicateResourceLimit(string $name): selfemptyDeprecationPattern()
public static function emptyDeprecationPattern(): selfinvalidPluginFactory()
public static function invalidPluginFactory(\InvalidArgumentException $previous): selfnegativeRandomSeed()
public static function negativeRandomSeed(int $seed): selfinvalidWorkerCountString()
public static function invalidWorkerCountString(string $count): selfinvalidMemorySizeSyntax()
public static function invalidMemorySizeSyntax(string $value): selfmemorySizeOverflow()
public static function memorySizeOverflow(string $value): selfnonPositiveMemorySize()
public static function nonPositiveMemorySize(string $value): selfemptyStoragePath()
public static function emptyStoragePath(string $name): selfstoragePathContainsNullByte()
public static function storagePathContainsNullByte(string $name): selfemptySuitePath()
public static function emptySuitePath(string $name): selfsuitePathContainsNullByte()
public static function suitePathContainsNullByte(string $name): selfemptySuiteTag()
public static function emptySuiteTag(string $name): selfmissingSuitePaths()
public static function missingSuitePaths(string $name): selfsuitePathsNotAList()
public static function suitePathsNotAList(string $name): selfsuitePathNotAString()
public static function suitePathNotAString(string $name): selfsuiteTagsNotAList()
public static function suiteTagsNotAList(string $name): selfsuiteTagNotAString()
public static function suiteTagNotAString(string $name): selfinvalidWatchDebounce()
public static function invalidWatchDebounce(int $milliseconds): selfinvalidWatchFileLimit()
public static function invalidWatchFileLimit(int $maximumFiles): selfemptyWatchPath()
public static function emptyWatchPath(string $name): selfwatchPathContainsNullByte()
public static function watchPathContainsNullByte(string $name): selfwatchPathsNotAList()
public static function watchPathsNotAList(string $name): selfwatchPathNotANonEmptyString()
public static function watchPathNotANonEmptyString(string $name): selfnonPositiveWorkerCount()
public static function nonPositiveWorkerCount(int $count): selfStorageBuilder
Namespace: Greenlight\Config
Collects directory configuration for Greenlight-owned storage. Relative paths use the command working directory, including explicit area directories. Without a root or an area override, Greenlight uses the system temporary directory.
final class StorageBuilderrootDirectory()
Sets the parent for the state, cache, generated-code, and temporary directories.
An explicit area directory overrides its default below this root.
public function rootDirectory(string $directory): selfPHPDoc:
@param non-empty-string $directory@throws InvalidConfiguration
stateDirectory()
Sets the directory for saved failures and test-class durations.
public function stateDirectory(string $directory): selfPHPDoc:
@param non-empty-string $directory@throws InvalidConfiguration
cacheDirectory()
Sets the directory for the discovery cache.
public function cacheDirectory(string $directory): selfPHPDoc:
@param non-empty-string $directory@throws InvalidConfiguration
generatedCodeDirectory()
Sets the directory for generated double proxy classes.
public function generatedCodeDirectory(string $directory): selfPHPDoc:
@param non-empty-string $directory@throws InvalidConfiguration
temporaryDirectory()
Sets the directory for temporary run data, sockets, and attachment staging.
public function temporaryDirectory(string $directory): selfPHPDoc:
@param non-empty-string $directory@throws InvalidConfiguration
SuiteBuilder
Namespace: Greenlight\Config
Configures a named suite.
final class SuiteBuilder__construct()
public function __construct(private readonly string $name)PHPDoc:
@param non-empty-string $name
in()
public function in(string ...$paths): selfPHPDoc:
@param non-empty-string ...$paths@throws InvalidConfiguration
tag()
public function tag(string ...$tags): selfPHPDoc:
@param non-empty-string ...$tags@throws InvalidConfiguration
WatchBuilder
Namespace: Greenlight\Config
Configures additional watch inputs and polling limits. The defaults are a 200 millisecond debounce, no additional paths or patterns, and a 100,000-file limit for each poll.
final class WatchBuilderdebounceMilliseconds()
Sets the quiet period before a new run. The period restarts after each change. Thus, multiple consecutive saves cause one run.
public function debounceMilliseconds(int $milliseconds): selfPHPDoc:
@param positive-int $milliseconds@throws InvalidConfiguration
paths()
Adds file or directory inputs. Relative paths use the command working directory. Multiple calls add paths.
public function paths(string ...$paths): selfPHPDoc:
@throws InvalidConfiguration
include()
Selects files below additional directory inputs. Multiple calls add patterns. Exact file inputs do not require an include pattern.
public function include(string ...$patterns): selfPHPDoc:
@throws InvalidConfiguration
exclude()
Removes from all watch inputs each file that matches. Exclusion has precedence over an explicit path or include pattern. Multiple calls add patterns.
public function exclude(string ...$patterns): selfPHPDoc:
@throws InvalidConfiguration
maximumFiles()
Sets the maximum number of files that one poll can track.
public function maximumFiles(int $maximumFiles): selfPHPDoc:
@throws InvalidConfiguration