Pest Plugin Test Time Laravel Package

Product Decisions This Supports

• Test-reliability investment (flaky-suite tax). Time-dependent behaviour is a leading cause of intermittently failing CI and "works on my machine" bug reports. This package makes freezing and stepping the clock a one-liner, so the decision "do we spend a sprint paying down test flakiness in billing/scheduling code?" gets a concrete, cheap answer instead of an open-ended one.
• Roadmap confidence for date-boundary features. Trials, subscriptions, renewals, proration, grace periods, expiry, reminders, SLA clocks, and timezone/DST handling all carry disproportionate defect risk. Frozen-time tests let you assert transitions (leap day, month-end, day boundary) rather than endpoints — this is the acceptance criterion that de-risks shipping those items.
• Definition-of-done / quality bar. Usable as a written standard: every time-dependent business rule has at least one frozen-clock test. That's a policy decision a PM can make and hold engineering to, independent of the tool.
• PHP 8.4 / Pest 5 upgrade sequencing. v2.3.0 targets Pest 5, requires PHP 8.4, and drops Carbon 2; v2.2.x is the Pest 2/3 line. Adopting this package couples your test tooling to that upgrade path — so it is an input to when you schedule the runtime upgrade, not just a dev dependency.
• Build vs. buy (trivially "buy"). The capability is a thin wrapper over Carbon::setTestNow() plus one expectation. Cost of buying is zero (MIT, --dev only, no config, no service provider, no production footprint). The real decision is standardization: one idiom across the team vs. every engineer rolling their own freeze/reset helper. Choose this package to end that drift.
• Low-signal adoption risk (governance). 51 stars and 0 dependents means limited community validation — the maintenance backing is the Spatie brand and an active release history through Pest 5, not ecosystem gravity. Treat it as a convention choice with a near-zero exit cost, not a platform bet.

When to Consider This Package

Consider it when:

• The team writes Pest tests (not PHPUnit) in a Laravel app and "now" flows through Carbon (now(), Carbon::now(), Carbon::parse()).
• You have real date-driven domain rules and existing flaky or slow time-dependent tests.
• You want a single house style for time control across unit, feature, and HTTP→job→notification tests (freezing is process-global, so one freeze() covers the whole path).
• Your runtime is on the modern line (Pest 5 / PHP 8.4 / Carbon 3) or you're willing to pin 2.2.x for Pest 2/3.

Look elsewhere / don't bother when:

• You're on PHPUnit. The package is Pest-only; use Carbon::setTestNow() directly. Don't add Pest just for this.
• Your time reads bypass Carbon. Native time()/mktime(), Carbon::createFromTimestamp(time()), and SQL NOW()/CURRENT_TIMESTAMP are unaffected by freezing. If that's your codebase, this package gives false confidence — fix where time is read first, or use a clock-abstraction layer.
• You need to simulate delayed queue jobs / workers in real elapsed time. Frozen time plus sleep() is a trap (it really waits; the clock doesn't move). Scope the expectation accordingly.
• Your Pest major doesn't match a supported release. Check Pest major, PHP floor, and Carbon major before standardizing — this is the one place adoption creates an upgrade obligation.
• You already have an established freeze/reset convention. The surface is tiny and substitutable; adding a dependency for a 50-line helper is defensible only if it wins on consistency.

Non-negotiable guardrails if adopted: add afterEach(fn () => Carbon::setTestNow()) (leaked frozen time produces "passes alone, fails in suite" bugs), and pass an explicit format to toBeCarbon in any shared helper rather than relying on shape inference.

How to Pitch It (Stakeholders)

To executives: This is a free, MIT-licensed, developer-only testing utility with zero production footprint — it can't affect customers, latency, or security surface. It buys us two things: less engineering time lost to intermittently failing tests, and higher confidence shipping revenue-adjacent date logic (trials, renewals, proration, expiries). The only real cost is a scheduling dependency: the current version tracks PHP 8.4 / Pest 5, so adopting it aligns with an upgrade we'd likely plan anyway. Exit cost is negligible — it's a thin wrapper over a Carbon built-in, so removing it is an afternoon, not a migration.

To engineering: composer require spatie/pest-plugin-test-time --dev. No config, no service provider, no Pest.php registration. Two idioms: testTime()->freeze('2024-01-01 09:00:00') then walk forward with addDays()/addMinute() (chainable, literal hops only — never compute expected values with now()->addDays(3), that makes tests tautological), and expect($x->renews_at)->toBeCarbon('2024-02-29') for readable assertions. Feature-test the whole HTTP → job → notification path under one freeze. Add the afterEach reset. Keep time reads in Carbon, not native PHP or raw SQL. Pin 2.2.x unless we're on Pest 5 / PHP 8.4 / Carbon 3 — verify the matrix before you standardize.