使用 Orchestra Testbench 测试 Laravel 包

什么是 Orchestra Testbench

Orchestra Testbench 是面向包开发的 Laravel 测试辅助工具。继承 Orchestra\Testbench\TestCase 后，即便是包本身，也可以像在 Laravel 应用内那样进行测试。 Laravel 官方文档的包开发也建议使用 Testbench 来测试包。

搭建

安装 Testbench

composer require --dev orchestra/testbench

创建基类 TestCase

<?php

namespace Vendor\Package\Tests;

use Orchestra\Testbench\TestCase as BaseTestCase;
use Vendor\Package\PackageServiceProvider;

abstract class TestCase extends BaseTestCase
{
    /**
     * $app 是 Testbench 启动的 Laravel 应用实例。
     */
    protected function getPackageProviders($app): array
    {
        return [
            PackageServiceProvider::class,
        ];
    }
}

按需添加配置或别名

在 getPackageAliases() 中，可以像 config/app.php 的 aliases 一样注册测试中使用的 Facade 别名。

protected function getPackageAliases($app): array
{
    return [
        'Package' => \Vendor\Package\Facades\Package::class,
    ];
}

protected function defineEnvironment($app): void
{
    // 在此覆盖测试用配置
    $app['config']->set('package.enabled', true);
}

基本测试的写法

首先确认 Service Provider 是否被加载、Facade 是否按预期工作、配置是否生效。

<?php

namespace Vendor\Package\Tests\Feature;

use Vendor\Package\Facades\Package;
use Vendor\Package\PackageServiceProvider;
use Vendor\Package\Tests\TestCase;

class PackageBootstrapTest extends TestCase
{
    public function test_service_provider_is_registered(): void
    {
        $this->assertTrue($this->app->providerIsLoaded(PackageServiceProvider::class));
    }

    public function test_facade_returns_expected_value(): void
    {
        // 通过 Facade 验证功能
        $this->assertSame('ok', Package::status());
    }

    public function test_package_config_is_available(): void
    {
        // 验证 defineEnvironment() 中设置的值
        $this->assertTrue(config('package.enabled'));
    }
}

文件系统与数据库的测试

对使用数据库的测试，在 defineEnvironment() 中配置 SQLite 内存数据库，并加载被测试的迁移。

<?php

namespace Vendor\Package\Tests;

use Orchestra\Testbench\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    protected function defineEnvironment($app): void
    {
        // 使用 SQLite 内存数据库
        $app['config']->set('database.default', 'testing');
        $app['config']->set('database.connections.testing', [
            'driver' => 'sqlite',
            'database' => ':memory:',
            'prefix' => '',
        ]);
    }

    protected function setUp(): void
    {
        parent::setUp();

        // 加载包的迁移
        $this->loadMigrationsFrom(__DIR__.'/../database/migrations');
    }
}

public function test_it_persists_data(): void
{
    \DB::table('widgets')->insert(['name' => 'test']);

    $this->assertDatabaseHas('widgets', ['name' => 'test']);
}

在多个 Laravel 版本上测试

Testbench 的主版本与 Laravel 主版本对应。详情请参见官方 Version Compatibility。

Laravel	Testbench
12.x	10.x
13.x	11.x

要持续验证多个版本，可以与 GitHub Actions 矩阵组合。设计思路请参考包的版本兼容性管理。

strategy:
  fail-fast: false
  matrix:
    php: [8.3, 8.4]
    laravel: ["^12.0", "^13.0"]
    include:
      - laravel: "^13.0"
        testbench: "^11.0"
      - laravel: "^12.0"
        testbench: "^10.0"

小结

有了 Testbench，你无需手工准备 Laravel 应用，也能在接近生产的形态下验证包的行为。将 Service Provider 注册、配置、Facade、数据库都纳入测试对象，能显著减少发布后的问题。

Laravel 包开发

了解以 Service Provider 为核心的包实现基础。

包的版本兼容性管理

了解 Laravel 与 Testbench 的版本策略以及 CI 矩阵运营。

​什么是 Orchestra Testbench

​搭建

​基本测试的写法

​文件系统与数据库的测试

​在多个 Laravel 版本上测试

​小结

​相关页面