Pest Plugin Filesystem Laravel Package

Technical Evaluation

Architecture fit. This is a development-only test dependency, and the TPM must frame it as tooling rather than platform. It layers expressive filesystem expectations onto Pest's expect() API — file exists, directory exists, contents match, path missing — replacing raw file_exists() / file_get_contents() scaffolding in tests. Critically, it has no runtime footprint: no service provider on the request path, no migrations, no storage driver, no production dependency edge. That single fact determines the entire evaluation lens. Runtime concerns (latency, throughput, upgrade blast radius on live traffic) are irrelevant; the real concerns are developer experience, assertion correctness, and maintenance risk. The package presupposes Pest — a PHPUnit-only suite extracts zero value — and Laravel is optional, with the only Laravel-specific signal in the sources being the 1.2.0 "Laravel 10 support" note.

Integration feasibility. High and cheap. Adoption is one composer require --dev line, and the pest-plugin-* naming convention implies auto-discovery. Time to a first green test is measured in minutes, and the package can be isolated to a single test file as a spike. The genuine feasibility gate is version resolution, not installation effort.

Technical risk. Low-to-medium: "low" because it is contained to test code and trivially removable, "medium" because it is stale.

• Version lock-out is the dominant risk. The last release is February 2023. Pest 3, PHPUnit 10/11, and Laravel 11/12 have all shipped since. If 1.2.0's declared constraints exclude the current Pest major, the evaluation ends there — and given the release date, that is the likelier outcome.
• Assertion correctness is the highest-impact failure. A helper that passes when it should fail — substring "contains" where you assumed line-based, a symlink edge case, Windows path separators — is worse than no helper, because it erodes trust in the whole suite. Any pilot must deliberately test negative cases, not just happy paths.
• Supply-chain surface still applies to dev dependencies. Test tooling executes in CI with access to repository secrets; source review, pinned versions, and composer audit coverage of dev dependencies are warranted.
• Replacement cost caps the downside. The functional surface is thin wrappers over native calls. Reimplementing the needed assertions as expect()->extend() in tests/Pest.php is plausibly 30–100 lines. Vendor risk is quantifiable as "an afternoon" — the correct lens for a 3-star, zero-dependent package.

Key questions.

1. What Pest / PHPUnit / PHP constraints does 1.2.0 declare, and do they resolve against our lockfile? Does it support Pest 3?
2. Does it assert against the local filesystem directly, or wrap Flysystem / Storage? This decides whether it works with Storage::fake() disks or only real paths — a large usability difference and the determinant of whether it complements or duplicates Laravel's built-in helpers.
3. Do the helpers create and clean up temporary files/directories, and are temp paths unique under --parallel / Paratest?
4. Is cleanup guaranteed on test failure, not just success?
5. What is the package's own test coverage and CI matrix? A test helper with untested helpers is a legitimate blocker.
6. Is it single-maintainer, and has there been any activity since February 2023? What does the issue-response pattern look like?
7. Does it overlap or collide with Pest's existing file expectations, risking two idioms for the same assertion?
8. Is the MIT license and Composer metadata clean, with no unexpected transitive dependencies?

Integration Approach

Stack fit. Pest-based suites on PHP 8.1+, most plausibly Laravel applications but equally plain-PHP Pest projects. Not applicable to PHPUnit-only codebases, and not applicable where filesystem assertions target a remote or object-store disk rather than the local filesystem.

Migration path. Purely additive — no migration, and no obligation to touch existing raw file_exists() assertions. Present both outcomes as legitimate:

• Adopt if constraints resolve and a spike passes; then standardise new tests on the helper set and convert old assertions opportunistically rather than in a sweep.
• Reimplement locally if constraints do not resolve — the likely result. Mirror the needed expectations in tests/Pest.php, wrapping native calls or adapting the package's approach under its MIT license. This removes the dependency at a cost comparable to adopting it.

Compatibility. Verify rather than infer from one-line release notes: run composer why-not ralphjsmit/pest-plugin-filesystem 1.2 to see exactly what blocks resolution; read composer.json for pestphp/pest, phpunit/phpunit, and php constraints plus the extra.pest.plugins entry; and execute on the full CI matrix, not just a developer machine — including a non-Linux runner if one exists, since path handling is the likeliest divergence. Pin ^1.2 and commit the lockfile so resolution cannot drift back to 1.1.x.

Sequencing.

1. Constraint and repository-activity check; confirm plugin discovery against our Pest major.
2. Spike in one throwaway test file covering file exists, file contains, path missing, temp directory created and cleaned up, plus at least one negative assertion that must fail.
3. Run the spike across the CI matrix, including parallel mode.
4. Decide adopt vs. local shim against a one-paragraph written criterion (readability gain vs. dependency cost).
5. If adopting, convert one small high-value slice and publish a short internal style note.
6. Register the package in the dependency-review log with the shim fallback already documented.

Operational Impact

Maintenance. Assume we own it. Three stars, zero dependents, one release in 2023, and one-line release notes describe a personal utility project, not a maintained library. The realistic model: pin it, review the diff on any bump, and be ready to swap to local expectations. Budget an hour or two per quarterly dependency review — or spend that once on a shim and reach zero recurring cost.

Support. Community-only. No security policy, no SLA, no commercial backing. Mitigation is structural rather than contractual: dev-only scope, pinned version, composer audit in CI covering dev dependencies, and a documented exit plan. Dev dependencies execute inside CI and can read CI secrets, so provenance review applies here as much as to runtime packages.

Scaling. No runtime scaling dimension exists. The only scaling surface is CI behaviour: the helpers wrap native calls, so wall-clock cost is negligible. The real scaling risk is parallel execution — predictable temp paths can collide across workers and produce flaky, hard-to-reproduce failures that cost far more engineering time than the readability gain saves.

Failure modes.

• Constraint lock-out at the next Pest major, forcing removal or reimplementation mid-cycle.
• Flaky parallel tests from shared or non-unique temp paths.
• Temp-directory leakage filling long-lived CI runners and developer machines, especially if cleanup only runs on success.
• Silent assertion weakness — passing tests that should fail. Highest-impact failure, because it damages confidence in the suite rather than merely annoying developers.
• Style fragmentation — a mix of helper and native assertions, erasing the expressiveness benefit that justified adoption.
• Abandonment with no upstream fix path; acceptable only because replacement cost is an afternoon.

Ramp-up. Very low for anyone already writing Pest tests; self-describing helpers are the entire value proposition. Two onboarding requirements make or break it: a short team style note stating when to use the helpers versus Storage::fake() and Laravel's built-in assertions, and a documented shim procedure so an engineer hitting a constraint failure at upgrade time knows the escape hatch exists and is cheap. Without those two artefacts, the package becomes an inconsistently applied dependency that a future upgrade removes by accident.