Getting Started

Install the package in your test environment only:

composer require spatie/test-time --dev

Start by importing the class in your tests:

use Spatie\TestTime\TestTime;

The most common first use case is freezing time at a known value for deterministic test assertions:

TestTime::freeze('2024-01-01 12:00:00');
// Now Carbon::now() always returns Jan 1, 2024 at noon
$this->assertEquals('2024', Carbon::now()->year);

Check the README and unit tests for immediate patterns.

Implementation Patterns

Test Setup: Freeze time at the start of each test or test group to avoid flaky time-sensitive assertions.
```
protected function setUp(): void
{
    parent::setUp();
    TestTime::freeze('2024-02-15 09:00:00');
}
```

Time Progression: Simulate elapsed time in integration tests using chained calls:

TestTime::addHours(2)->addMinutes(30);
$this->assertDatabaseCount('jobs', 1); // after job scheduled with delay

Granular Freezing: Use format + time string when only date precision matters:
```
TestTime::freeze('Y-m-d', '2024-06-01'); // ignores time components
```
CarbonImmutable Support: Works out-of-the-box with both Carbon and CarbonImmutable.

Reset Strategy: Always pair freeze() with unfreeze() in tearDown() if using class-level setup:

protected function tearDown(): void
{
    TestTime::unfreeze();
    parent::tearDown();
}

Global State Risk: This package modifies global time via Carbon’s internal clock manipulation. Avoid long-running test suites where time drift matters; unfreeze between suites or use per-test isolation.
Timezone Handling: Pass timezones explicitly if needed (since 1.3.1):
```
TestTime::freeze('2024-01-01 00:00:00', 'UTC');
```
freezeAtSecond() (1.2.0+) freezes to the current real second—useful for testing time-elapsed logic without hardcoding.
Watch for Test Interference: If tests share memory (e.g., in a single PHP process), ensure unfreeze() happens reliably. Consider using ensureTestTimeIsReset() helper or Laravel’s WithoutTruncation trait alternatives.
Carbon Version Compatibility: Ensure your Carbon version matches package requirements (^2.63|^3.0). Mixing Carbon 3 with legacy helpers may cause subtle issues.
Extension Point: Internally manipulates Carbon’s useTestNow()—you can manually call Carbon::useTestNow() alongside it, but don’t mix approaches in the same test to avoid confusion.