Weave Code
Pest Plugin Test Time Laravel Package
spatie/pest-plugin-test-time
A Pest plugin for controlling time in tests. Freeze or advance Carbon’s current time with testTime()->freeze() and addMinute(), and use the toBeCarbon expectation to assert Carbon date and time values clearly.
spatie/pest-plugin-test-time is a lightweight Pest plugin for controlling time in tests. It wraps Carbon’s setTestNow() and provides the testTime() helper to freeze the current time or move it forward with methods like addMinute().
It also adds the toBeCarbon expectation for concise Carbon assertions, supporting full timestamps, date-only checks, or explicit formats.
- Freeze time with
testTime()->freeze() - Manipulate time using helpers like
addMinute() - Assert Carbon values with
toBeCarbon - Compare full dates, date-only values, or custom formats
- Requires a project using Carbon
Frequently asked questions about Pest Plugin Test Time
- How do I install spatie/pest-plugin-test-time in a Laravel app?
- Install it as a dev dependency with composer require spatie/pest-plugin-test-time --dev. Pest's plugin discovery registers it automatically, so there is no service provider or manual configuration to manage. It belongs only in require-dev and never ships to production.
- Does spatie/pest-plugin-test-time work with PHPUnit-only test suites?
- No. It is a Pest plugin, not a PHPUnit extension, so PHPUnit-only suites get neither testTime() nor the toBeCarbon expectation. In a mixed-runner codebase the helper only applies to Pest tests, which can create partial coverage. Use Carbon::setTestNow() directly for PHPUnit tests.
- Which PHP, Pest, and Carbon versions does spatie/pest-plugin-test-time support?
- Release 2.3.0 requires PHP 8.4 via Pest 5 and drops Carbon 2, so it ties your test-tooling upgrades to your PHP and framework upgrade path. Projects on PHP 8.2/8.3 or Pest 3/4 must pin an older minor. Check the package's composer.json against your exact Pest, PHP, and Carbon versions before adopting.
- How do I freeze time in a Pest test using testTime()?
- Call testTime()->freeze() at the start of a date-sensitive Pest test to stop Carbon's clock at the current instant. You can then move it with fluent methods such as addMinute() or subDay() before running assertions. The helper wraps Carbon's setTestNow(), so the frozen value is what Carbon::now() returns for the rest of that process.
- Does testTime() reset frozen Carbon time automatically after each test?
- Carbon's setTestNow() is process-global mutable state, so frozen time must be cleared between tests or later tests can become order-dependent. Confirm whether your installed version resets it automatically; if not, add an afterEach or teardown that calls Carbon::setTestNow() with no argument. That hygiene matters more than the freeze call itself because a missed reset reintroduces the flakiness you adopted the tool to remove.
- Does spatie/pest-plugin-test-time work with Pest's parallel test runner?
- Pest's parallel runner isolates tests in separate processes, which limits cross-test leakage between workers. Within each process, however, Carbon's test clock is still global, so resetting frozen time after every test remains necessary. Verify reset behavior against your Pest version before relying on it in parallel CI.
- How do I assert a Carbon value with the toBeCarbon expectation?
- Use expect($carbon)->toBeCarbon('2022-05-31 01:02:03') to assert the full date and time. You can compare only the date with toBeCarbon('2022-05-31') or pass an explicit format as the second argument, such as toBeCarbon('2022', 'Y'). The expectation is registered by the plugin and works on Carbon instances.
- What time sources does testTime() not affect?
- testTime() only affects Carbon's test clock through setTestNow(). It does not change PHP's time() or mktime(), non-Carbon clock abstractions, database NOW() values, queued job timestamps already persisted, or client-side JavaScript time. If any of those drive your domain logic, freezing Carbon can give false confidence.
- Should I use testTime()->freeze() or Laravel's travelTo() in tests?
- Both approaches ultimately control Carbon's test clock, so pick one convention and document it to avoid review churn. testTime()->freeze() is Pest-native and pairs with addMinute()/subMinute() plus the toBeCarbon expectation. Laravel's travelTo() and travelBack() are framework helpers that may fit better in PHPUnit tests or mixed suites. Using both is possible but should be deliberate.
- Is spatie/pest-plugin-test-time a production dependency?
- No. It is a development-only Composer dependency intended for require-dev and has essentially no runtime footprint. It has no config, service provider, persistence, or network surface, and it never ships to production. That small blast radius is why it is safe to add to a Laravel + Pest codebase.
Weaver
How can I help you explore Laravel packages today?