Laravel 10.x テスト: テストの準備

イントロダクションIntroduction

Laravelはユニットテストも考慮して構築されています。実際、PHPUnitをサポートしており、最初から含まれています。アプリケーションのためにphpunit.xmlファイルも最初から準備されています。さらにフレームワークはアプリケーションを記述的にテストするために便利なヘルパメソッドも用意しています。Laravel is built with testing in mind. In fact, support for testing with PHPUnit is included out of the box and a phpunit.xml file is already set up for your application. The framework also ships with convenient helper methods that allow you to expressively test your applications.

デフォルトでは、アプリケーションのtestsディレクトリには、FeatureとUnitの２つのディレクトリを用意しています。単体テストは、コードの非常に小さな孤立した部分に焦点を当てたテストです。実際、ほとんどの単体テストはおそらく単一のメソッドに焦点を合わせています。「ユニット」テストディレクトリ内のテストはLaravelアプリケーションを起動しないため、アプリケーションのデータベースやその他のフレームワークサービスにアクセスできません。By default, your application's tests directory contains two directories: Feature and Unit. Unit tests are tests that focus on a very small, isolated portion of your code. In fact, most unit tests probably focus on a single method. Tests within your "Unit" test directory do not boot your Laravel application and therefore are unable to access your application's database or other framework services.

機能テストでは、複数のオブジェクトが相互作用する方法や、JSONエンドポイントへの完全なHTTPリクエストなど、コードの広い部分をテストします。一般的に、ほとんどのテストは機能テストである必要があります。これらのタイプのテストは、システム全体が意図したとおりに機能しているという信頼性を一番提供します。Feature tests may test a larger portion of your code, including how several objects interact with each other or even a full HTTP request to a JSON endpoint. Generally, most of your tests should be feature tests. These types of tests provide the most confidence that your system as a whole is functioning as intended.

ExampleTest.phpファイルはFeatureとUnitの両方のテストディレクトリで提供されます。新しいLaravelアプリケーションをインストールした後なら、vendor/bin/phpunitまたはphp artisan testコマンドを実行してテストを実行できます。An ExampleTest.php file is provided in both the Feature and Unit test directories. After installing a new Laravel application, execute the vendor/bin/phpunit or php artisan test commands to run your tests.

環境Environment

When running tests, Laravel will automatically set the configuration environment to testing because of the environment variables defined in the phpunit.xml file. Laravel also automatically configures the session and cache to the array driver so that no session or cache data will be persisted while testing.When running tests, Laravel will automatically set the configuration environment[/docs/{{version}}/configuration#environment-configuration] to testing because of the environment variables defined in the phpunit.xml file. Laravel also automatically configures the session and cache to the array driver so that no session or cache data will be persisted while testing.

必要に応じて、他のテスト環境設定値を自由に定義できます。testing環境変数はアプリケーションのphpunit.xmlファイルで設定していますが、テストを実行する前は必ずconfig:clear Artisanコマンドを使用して設定のキャッシュをクリアしてください。You are free to define other testing environment configuration values as necessary. The testing environment variables may be configured in your application's phpunit.xml file, but make sure to clear your configuration cache using the config:clear Artisan command before running your tests!

.env.testing環境ファイルThe .env.testing Environment File

さらに、プロジェクトのルートに.env.testingファイルを作成することもできます。このファイルは、PHPUnitテストを実行するとき、または--env=testingオプションを指定してArtisanコマンドを実行するときに、.envファイルの代わりに使用されます。In addition, you may create a .env.testing file in the root of your project. This file will be used instead of the .env file when running PHPUnit tests or executing Artisan commands with the --env=testing option.

CreatesApplicationトレイトThe CreatesApplication Trait

Laravelには、アプリケーションのベースTestCaseクラスに適用されているCreatesApplicationトレイトがあります。このトレイトは、テストを実行する前に、LaravelアプリケーションをブートストラップするcreateApplicationメソッドを持っています。Laravelの並列テスト機能など、いくつかの機能がこのトレイトへ依存しているため、このtraitを元の場所へ残しておくことは重要です。Laravel includes a CreatesApplication trait that is applied to your application's base TestCase class. This trait contains a createApplication method that bootstraps the Laravel application before running your tests. It's important that you leave this trait at its original location as some features, such as Laravel's parallel testing feature, depend on it.

テストの作成Creating Tests

新しいテストケースを作成するには、make:test Artisanコマンドを使用します。デフォルトでは、テストはtests/Featureディレクトリへ配置されます。To create a new test case, use the make:test Artisan command. By default, tests will be placed in the tests/Feature directory:

php artisan make:test UserTest

tests/Unitディレクトリ内にテストを作成したい場合は、make:testコマンドを実行するときに--unitオプションを使用します。If you would like to create a test within the tests/Unit directory, you may use the --unit option when executing the make:test command:

php artisan make:test UserTest --unit

Pest PHPテストを作成したい場合は、make:testコマンドに--pestオプションを指定してください。If you would like to create a Pest PHP[https://pestphp.com] test, you may provide the --pest option to the make:test command:

php artisan make:test UserTest --pest
php artisan make:test UserTest --unit --pest

lightbulb Note: stubのリソース公開 を使って、Testスタブをカスタマイズできます。[!NOTE]
Test stubs may be customized using stub publishing[/docs/{{version}}/artisan#stub-customization].

テストを生成したら、PHPUnitを使用する場合と同様にテストメソッドを定義します。テストを実行するには、ターミナルからvendor/bin/phpunitまたはphp artisan testコマンドを実行します。Once the test has been generated, you may define test methods as you normally would using PHPUnit[https://phpunit.de]. To run your tests, execute the vendor/bin/phpunit or php artisan test command from your terminal:

<?php

namespace Tests\Unit;

use PHPUnit\Framework\TestCase;

class ExampleTest extends TestCase
{
    /**
     * 基本的なテスト例
     */
    public function test_basic_test(): void
    {
        $this->assertTrue(true);
    }
}

warning Warning! テストクラスに独自のsetUpメソッドを定義する場合は、親のクラスのparent::setUp()／parent::tearDown()を確実に呼び出してください。通常、parent::setUp()は自分の setUpメソッドの最初で、parent::tearDown()は自分のtearDownメソッドの最後で呼び出します。[!WARNING]
If you define your own setUp / tearDown methods within a test class, be sure to call the respective parent::setUp() / parent::tearDown() methods on the parent class. Typically, you should invoke parent::setUp() at the start of your own setUp method, and parent::tearDown() at the end of your tearDown method.

テストの実行Running Tests

前述のとおり、テストが書き上がったら、phpunitを使って実行できます。As mentioned previously, once you've written tests, you may run them using phpunit:

./vendor/bin/phpunit

テスト実行にはphpunitコマンドに加え、test Artisanコマンドも使用できます。Artisanテストランナーは、開発とデバッグを容易にするため、詳細なテストレポートを提供しますIn addition to the phpunit command, you may use the test Artisan command to run your tests. The Artisan test runner provides verbose test reports in order to ease development and debugging:

php artisan test

phpunitコマンドで使用できる引数はすべてArtisan testコマンドにも渡せます。Any arguments that can be passed to the phpunit command may also be passed to the Artisan test command:

php artisan test --testsuite=Feature --stop-on-failure

テストを並列で実行Running Tests in Parallel

LaravelとPHPUnitはデフォルトで、単一のプロセス内でテストを順番に実行します。しかし、複数のプロセス間で同時にテストを実行し、テスト時間を大幅に削減できます。これを利用開始するには、"dev"の依存パッケージとしてbrianium/paratest Composerパッケージを確実にインストールしてください。次に、test Artisanコマンドを実行するときに、--parallelオプションを指定します。By default, Laravel and PHPUnit execute your tests sequentially within a single process. However, you may greatly reduce the amount of time it takes to run your tests by running tests simultaneously across multiple processes. To get started, you should install the brianium/paratest Composer package as a "dev" dependency. Then, include the --parallel option when executing the test Artisan command:

composer require brianium/paratest --dev

php artisan test --parallel

デフォルトで、Laravelはマシンで利用可能なCPUコアの数だけ、プロセスを作成します。しかし、--processesオプションでプロセス数を調整できます。By default, Laravel will create as many processes as there are available CPU cores on your machine. However, you may adjust the number of processes using the --processes option:

php artisan test --parallel --processes=4

warning Warning! テストをパラレル実行すると、PHPUnitのオプション(-do-not-cafy-resultなど)が利用できない場合があります。[!WARNING]
When running tests in parallel, some PHPUnit options (such as --do-not-cache-result) may not be available.

並列テストとデータベースParallel Testing and Databases

プライマリデータベース接続を設定さえすれば、Laravelは、テストを実行する並列プロセスごとに、テストデータベースの作成とマイグレーションを自動的に処理します。テストデータベースは、プロセスごとに一意のプロセストークンをサフィックス化します。たとえば、２つの並列テストプロセスがある場合、Laravelはyour_db_test_1とyour_db_test_2テストデータベースを作成して使用します。As long as you have configured a primary database connection, Laravel automatically handles creating and migrating a test database for each parallel process that is running your tests. The test databases will be suffixed with a process token which is unique per process. For example, if you have two parallel test processes, Laravel will create and use your_db_test_1 and your_db_test_2 test databases.

デフォルトでは、テストデータベースはtest Artisanコマンドへの呼び出し間で持続的に保持され、後続のtest呼び出しで再使用できます。ただし、--recreate-databasesオプションを使用してそれらを再作成できます。By default, test databases persist between calls to the test Artisan command so that they can be used again by subsequent test invocations. However, you may re-create them using the --recreate-databases option:

php artisan test --parallel --recreate-databases

並列テストフックParallel Testing Hooks

アプリケーションのテストでときどき、複数のテストプロセスにより安全に使用される特定のリソースを準備する必要があるかもしれません。Occasionally, you may need to prepare certain resources used by your application's tests so they may be safely used by multiple test processes.

ParallelTestingファサードを使用して、プロセスやテストケースのsetUpとtearDownで実行するコードを指定できます。指定するクロージャは、プロセストークンと現在のテストケースを含む$tokenと$testcase変数を受け取ります。Using the ParallelTesting facade, you may specify code to be executed on the setUp and tearDown of a process or test case. The given closures receive the $token and $testCase variables that contain the process token and the current test case, respectively:

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\ParallelTesting;
use Illuminate\Support\ServiceProvider;
use PHPUnit\Framework\TestCase;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 全アプリケーションサービスの初期起動処理
     */
    public function boot(): void
    {
        ParallelTesting::setUpProcess(function (int $token) {
            // ...
        });

        ParallelTesting::setUpTestCase(function (int $token, TestCase $testCase) {
            // ...
        });

        // テストデータベースが作成されたときに実行される
        ParallelTesting::setUpTestDatabase(function (string $database, int $token) {
            Artisan::call('db:seed');
        });

        ParallelTesting::tearDownTestCase(function (int $token, TestCase $testCase) {
            // ...
        });

        ParallelTesting::tearDownProcess(function (int $token) {
            // ...
        });
    }
}

並列テストトークンへのアクセスAccessing the Parallel Testing Token

アプリケーションのテストコードの他の場所から、現在の並列プロセスの「トークン」にアクセスしたい場合は、tokenメソッドを使用します。このトークンは個々のテストプロセスのための一意な文字列の識別子であり、並列テストプロセス間でリソースを分割するために使用できます。たとえば、Laravelは各並行テストプロセスで作成するテストデータベースの末尾に、このトークンを自動的に付加します。If you would like to access the current parallel process "token" from any other location in your application's test code, you may use the token method. This token is a unique, string identifier for an individual test process and may be used to segment resources across parallel test processes. For example, Laravel automatically appends this token to the end of the test databases created by each parallel testing process:

$token = ParallelTesting::token();

テストカバレージのレポートReporting Test Coverage

warning Warning! この機能を使用するには、Xdebug、またはPCOVが必要です。[!WARNING]
This feature requires Xdebug[https://xdebug.org] or PCOV[https://pecl.php.net/package/pcov].

アプリケーションのテストを実行する際に、テストケースが実際にアプリケーションコードをどの程度カバーしているかどうか、また、テストを実行する際にどれだけのアプリケーションコードが使用されているかを確認したいと思うことでしょう。これを行うには、testコマンドを実行するときに、--coverageオプションを指定します。When running your application tests, you may want to determine whether your test cases are actually covering the application code and how much application code is used when running your tests. To accomplish this, you may provide the --coverage option when invoking the test command:

php artisan test --coverage

最低限度のカバーレージ基準の強制Enforcing a Minimum Coverage Threshold

minオプションを使用すると、アプリケーションのテストカバレッジの最小値を定義できます。この閾値を満たさない場合、テストスイートは失敗します。You may use the --min option to define a minimum test coverage threshold for your application. The test suite will fail if this threshold is not met:

php artisan test --coverage --min=80.3

テストのプロファイルProfiling Tests

Artisanテストランナは、アプリケーションの最も遅いテストをリストアップする、便利なメカニズムも用意しています。testコマンドへ--profileオプションを付けて起動すると、最も遅い１０テストのリストが表示され、テストスイートを高速化するため、どのテストを改善できるかを簡単に調査できます。The Artisan test runner also includes a convenient mechanism for listing your application's slowest tests. Invoke the test command with the --profile option to be presented with a list of your ten slowest tests, allowing you to easily investigate which tests can be improved to speed up your test suite:

php artisan test --profile