Laravel 测试中精准控制日期时间的完整指南-php教程-PHP中文网

Laravel 测试中精准控制日期时间的完整指南

本文介绍如何在 Laravel 测试中固定系统当前时间，通过 Carbon 的 setTestNow() 等机制实现可重复、可预测的日期相关逻辑测试。

本文介绍如何在 laravel 测试中固定系统当前时间，通过 carbon 的 `settestnow()` 等机制实现可重复、可预测的日期相关逻辑测试。

Laravel 默认使用 PHP 的 time() 和 date() 函数，而其底层时间处理由 Carbon（Laravel 内置的时间库）统一管理。Carbon 提供了强大的测试辅助方法，使你能在单元测试或 Feature 测试中精确指定“当前时间”，从而验证业务逻辑在特定日期（如月末、节假日、跨年等）下的行为是否正确。

✅ 基础用法：`Carbon::setTestNow()`

在测试方法中调用 Carbon::setTestNow() 即可全局冻结当前时间：

use Carbon\Carbon;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class DateDependentLogicTest extends TestCase
{
    public function test_discount_expires_on_specific_date()
    {
        // 设定测试时间为 2024-12-24 10:00:00
        Carbon::setTestNow(Carbon::create(2024, 12, 24, 10, 0, 0));

        // 此时所有 Carbon::now()、now()、today() 等均返回该固定时间
        $this->assertEquals('2024-12-24', now()->toDateString());
        $this->assertTrue(now()->isFriday()); // 2024-12-24 确实是周五

        // 调用被测业务逻辑（例如检查优惠券是否过期）
        $coupon = Coupon::find(1);
        $this->assertFalse($coupon->isExpired()); // 假设过期时间为 2024-12-31
    }
}

⚠️ 重要注意事项：
setTestNow() 的效果是进程级全局生效，因此务必在测试结束前恢复真实时间，推荐使用 tearDown() 或 afterEach() 清理：
protected function tearDown(): void
{
  Carbon::setTestNow(); // 传入 null 或不传参，即重置为真实时间
  parent::tearDown();
}
Laravel 的 now() 辅助函数、Carbon::now()、模型时间戳（created_at/updated_at）及查询构造器中的 whereDate('created_at', now()) 等，均受此设置影响。

? 进阶技巧：按需偏移时间

你还可以在单个测试中模拟时间流逝：

Laravel 13.2.0

Laravel 13.2.0 是基于 PHP 8.3+ 的高性能框架，官方推荐通过 Composer 安装。它内置 AI SDK、JSON:API Resources 及原生向量搜索，支持属性驱动开发与队列路由，大幅提升开发效率。相比旧版，13.2.0 优化了缓存 TTL 管理与实时通信，无需 Redis 即可横向扩展。作为现代 Web 开发首选，它兼顾安全与极速体验，助您快速构建企业级应用。

下载

Carbon::setTestNow(Carbon::parse('2024-01-01'));
$this->assertEquals('2024-01-01', now()->toDateString());

// 模拟 7 天后
Carbon::setTestNow(Carbon::parse('2024-01-01')->addDays(7));
$this->assertEquals('2024-01-08', now()->toDateString());

? 替代方案与扩展工具

Carbonite（推荐用于复杂场景）：
一个专为测试设计的 Carbon 扩展包，支持更灵活的时间模拟，例如自动推进时间、多线程隔离时间、甚至模拟时区切换。安装后可无缝替代原生 Carbon 测试逻辑：
```
composer require --dev kylekatarnls/carbonite
```
官方文档：https://www.php.cn/link/709ed97abb93839bfa2e67c055d5df49
避免直接 mock time() 或 date()：
不建议手动 patch PHP 内置函数（如 via runkit），既破坏可移植性，又易引发不可预知副作用。Carbon 的 setTestNow() 是 Laravel 生态中官方推荐、稳定可靠的标准实践。