> ## 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 套件的測試環境，並驗證服務提供者、Facade、設定與 DB 的步驟。

## 什麼是 Orchestra Testbench

[Orchestra Testbench](https://github.com/orchestral/testbench) 是為套件開發準備的 Laravel 測試 helper。繼承 `Orchestra\Testbench\TestCase` 後，即便單獨的套件也能以彷彿身處 Laravel 應用程式的方式進行測試。

Laravel 官方文件[套件開發](/zh-TW/advanced/package-development)中也指引套件測試使用 Testbench。

```mermaid theme={null}
flowchart TD
    A["PHPUnit / Pest"] --> B["Package TestCase<br>extends Orchestra\\Testbench\\TestCase"]
    B --> C["以 getPackageProviders() 註冊<br>服務提供者"]
    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="需要時新增設定或 alias">
    於 `getPackageAliases()` 可與 `config/app.php` 的 `aliases` 相同方式，註冊測試中使用的 Facade alias。

    ```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>

## 基本的測試撰寫方式

先確認服務提供者是否已載入、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'));
    }
}
```

## 檔案系統與資料庫的測試

在使用 DB 的測試中，於 `defineEnvironment()` 設定 SQLite 記憶體資料庫，並載入測試對象的 migration。

```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 記憶體 DB
        $app['config']->set('database.default', 'testing');
        $app['config']->set('database.connections.testing', [
            'driver' => 'sqlite',
            'database' => ':memory:',
            'prefix' => '',
        ]);
    }

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

        // 載入套件的 migration
        $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 的 matrix 組合。設計思路請參考[套件的版本相容性管理](/zh-TW/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 應用程式，也能以近似正式運行的形式驗證套件行為。將服務提供者註冊、設定、Facade、DB 都納入測試對象，可大幅減少發布後的問題。

## 相關頁面

<Columns cols={2}>
  <Card title="Laravel 套件開發" icon="box" href="/zh-TW/advanced/package-development">
    確認以服務提供者為中心的套件實作基礎。
  </Card>

  <Card title="套件的版本相容性管理" icon="git-branch" href="/zh-TW/advanced/package-versioning">
    確認 Laravel 與 Testbench 的版本策略與 CI matrix 運行方式。
  </Card>
</Columns>


## Related topics

- [以 Testbench Workbench 推進套件開發](/zh-TW/advanced/package-workbench.md)
- [套件的 CHANGELOG 與發布管理](/zh-TW/advanced/package-changelog.md)
- [GeneratorCommand — 自訂 make: 指令的實作](/zh-TW/advanced/generator-command.md)
- [套件的靜態分析（PHPStan / Larastan）](/zh-TW/advanced/package-static-analysis.md)
- [套件自動偵測的內部結構](/zh-TW/advanced/package-discovery.md)