Pest Plugin Filesystem Laravel Package

Product Decisions This Supports

• Build vs. buy (really "adopt vs. reimplement"): This is a commodity capability — fluent assertions that wrap native PHP calls (file_exists(), file_get_contents()) into Pest's expect() API. The decision is not whether to invest in testing infrastructure; it's whether to take a dependency for roughly 30–100 lines of local helper code. The package is MIT-licensed, so even the "build" option can legitimately copy the approach.
• Test-suite standardization: If engineering has standardized on Pest, this supports the "make tests faster to write and easier to read" theme. Filesystem-heavy tests — importers, exporters, file generators, upload handlers, report writers — read as expect($path)->toBeFile() instead of scaffolding around file_exists(). The gain is real but modest and entirely a developer-experience gain.
• Dependency vetting and risk posture: This is the package's most decision-relevant characteristic. Three stars, zero dependents, a single maintainer, and one release in February 2023 (a Laravel 10 compatibility bump, one line of release notes). This is a personal utility project, not a maintained library. Any adoption decision is a risk-acceptance decision, not a capability decision.
• Framework and upgrade planning: Laravel 10 / PHP 8.1+ is signaled. Laravel 11/12, PHP 8.3+, Pest 3, and PHPUnit 10/11 compatibility are unconfirmed and, given the release date, plausibly broken. This is a reason to check before adoption, and a reason to remove at the next Pest major — never a reason to hold back an upgrade.
• Explicit non-decision: This must not displace a broader testing-strategy investment. Laravel's Storage::fake() and built-in filesystem assertions are the platform answer for storage-layer tests. This package is a readability add-on for tests that touch the real local filesystem, not a platform choice and not a budget line.
• Roadmap impact: Essentially none. It should be resolved inside a maintenance/dependency-review slot, not on a product roadmap. Because adoption is reversible within an afternoon, it does not warrant roadmap capacity or a stakeholder gate.

When to Consider This Package

Consider it when:

• The team has standardized on Pest and genuinely writes tests against the local filesystem (fixtures, generated artifacts, temp directories) rather than only against Storage::fake() disks.
• A short spike confirms version resolution against your current lockfile — specifically Pest major, PHPUnit 10/11, PHP 8.1+, and Laravel 10 — since the last release predates the current Pest major.
• The package is isolated behind a thin wrapper or confined to a small slice, so removal is a contained change rather than a suite-wide rewrite.
• Usage is test-code only, so an upstream stall degrades developer experience rather than production behavior. This is the strongest argument for trying it.
• The spike covers negative cases — assertions that must fail — plus temp-file cleanup, so you rule out a helper that silently passes when it should fail.
• You can live with a single-maintainer, low-star utility with terse release notes and no documented security policy, mitigated by pinning ^1.2, committing the lockfile, and including dev dependencies in composer audit.

Look elsewhere (or reimplement locally) when:

• Your tests already lean on Storage::fake() and Laravel's built-in assertions — the marginal readability gain won't justify a new dependency.
• The team is on Laravel 11/12, PHP 8.3+, or Pest 3; compatibility is unconfirmed and composer why-not may simply block resolution. That ends the evaluation cleanly.
• You need a feature roadmap, breaking-change history, or responsive maintainer before introducing a dependency.
• Parallel test execution is central to your CI — predictable temp paths can collide across workers and produce flaky failures that cost far more engineering time than the readability gain saves.
• Standards mandate multi-maintainer, actively released dependencies for anything beyond throwaway tooling.

Recommended decision: a time-boxed trial inside the test suite only, gated on a version-resolution check and a spike that includes at least one assertion that must fail. If constraints don't resolve — the more likely outcome — write the handful of expectations locally in tests/Pest.php (adapting the MIT-licensed source if useful) and reach zero recurring dependency cost. Either way, resolve it at the next dependency review rather than carrying it indefinitely.

How to Pitch It (Stakeholders)

Executives: This is a small, MIT-licensed testing helper that makes filesystem-related tests shorter and easier to read for teams using Pest. It has no production runtime footprint — it executes only in test code, so an upstream stall or breaking change never touches customers. The cost of trying it is measured in hours. The trade-off is maturity: a handful of GitHub stars, a single maintainer, and a last release in early 2023. The recommendation is a contained trial, not a platform standard, with no budget ask and no roadmap impact. If it goes stale, we remove it or replace it with local helpers at a cost of roughly an afternoon.

Engineering: Treat this as a dev-only dependency with a documented exit plan. Pin ^1.2, commit the lockfile, and verify actual constraint resolution (composer why-not, composer.json for Pest/PHPUnit/PHP constraints and the extra.pest.plugins entry) rather than trusting the release notes. Spike in one throwaway test file covering file-exists, content-contains, path-missing, temp-directory creation and cleanup, plus at least one assertion that must fail — a helper that passes when it should fail is worse than no helper. Run the spike across the full CI matrix, including parallel mode and any non-Linux runner, since path handling and temp-file collisions are the likeliest failure points. Keep it off the production dependency path, include dev dependencies in composer audit, and prefer Storage::fake() wherever it already covers the case. Do not sweep-convert existing assertions — adopt for new tests only.

Product: A maintenance-phase, developer-experience call: modest upside in test readability and onboarding, negligible downside because it is isolated to test code and reversible. It should not consume roadmap capacity or gate a release. Revisit at the next dependency review; if there has still been no release or maintenance activity, drop it in favor of a local shim rather than carrying the dependency forward by default.