> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Orchestra Testbench 测试 Laravel 包

> 讲解如何用 Orchestra Testbench 搭建 Laravel 包的测试环境，验证 Service Provider、Facade、配置以及数据库。

## 什么是 Orchestra Testbench

[Orchestra Testbench](https://github.com/orchestral/testbench) 是面向包开发的 Laravel 测试辅助工具。继承 `Orchestra\Testbench\TestCase` 后，即便是包本身，也可以像在 Laravel 应用内那样进行测试。

Laravel 官方文档的[包开发](/zh/advanced/package-development)也建议使用 Testbench 来测试包。

```mermaid theme={null}
flowchart TD
    A["PHPUnit / Pest"] --> B["Package TestCase<br>extends Orchestra\\Testbench\\TestCase"]
    B --> C["用 getPackageProviders() 注册<br>Service Provider"]
    C --> D["启动内存中的 Laravel 应用"]
    D --> E["验证包的功能"]
```

## 搭建

<Steps>
  <Step title="安装 Testbench">
    ```bash theme={null}
    composer require --dev orchestra/testbench
    ```
  </Step>

  <Step title="创建基类 TestCase">
    ```php theme={null}
    <?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,
            ];
        }
    }
    ```
  </Step>

  <Step title="按需添加配置或别名">
    在 `getPackageAliases()` 中，可以像 `config/app.php` 的 `aliases` 一样注册测试中使用的 Facade 别名。

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

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

## 基本测试的写法

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

```php theme={null}
<?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 theme={null}
<?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');
    }
}
```

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

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

## 在多个 Laravel 版本上测试

Testbench 的主版本与 Laravel 主版本对应。详情请参见官方 [Version Compatibility](https://packages.tools/testbench)。

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

要持续验证多个版本，可以与 GitHub Actions 矩阵组合。设计思路请参考[包的版本兼容性管理](/zh/advanced/package-versioning)。

```yaml theme={null}
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、数据库都纳入测试对象，能显著减少发布后的问题。

## 相关页面

<Columns cols={2}>
  <Card title="Laravel 包开发" icon="box" href="/zh/advanced/package-development">
    了解以 Service Provider 为核心的包实现基础。
  </Card>

  <Card title="包的版本兼容性管理" icon="git-branch" href="/zh/advanced/package-versioning">
    了解 Laravel 与 Testbench 的版本策略以及 CI 矩阵运营。
  </Card>
</Columns>


## Related topics

- [使用 Testbench Workbench 进行包开发](/zh/advanced/package-workbench.md)
- [GeneratorCommand — 实现自定义 make: 命令](/zh/advanced/generator-command.md)
- [包的 CHANGELOG 与发布管理](/zh/advanced/package-changelog.md)
- [包的静态分析（PHPStan / Larastan）](/zh/advanced/package-static-analysis.md)
- [Laravel 包开发](/zh/advanced/package-development.md)