スロット攻略 プロジェクトドキュメント

Appearance

PHPUnitテスト実行ガイド ​

目的 ​

このドキュメントは、プロジェクトでPHPUnitを使用してテストを実行する方法を初心者向けに説明します。

対象読者 ​

  • テスト経験が少ない開発者
  • このプロジェクトに新しく参加する開発者
  • PHPUnitを初めて使用する開発者

PHPUnitとは ​

PHPUnitの役割と目的 ​

PHPUnitは、PHPアプリケーションのユニットテストを実行するためのテストフレームワークです。このプロジェクトでは、以下の目的で使用しています：

  • コードの品質保証: 実装したコードが期待通りに動作することを確認
  • リファクタリングの安全性: コードを変更しても既存の機能が壊れていないことを確認
  • バグの早期発見: 本番環境にデプロイする前に問題を発見

このプロジェクトでのテストの種類 ​

このプロジェクトでは、以下の2種類のテストを用意しています：

  1. ユニットテスト (tests/Unit/)

    • 個別のクラスやメソッドの動作を検証
    • 現在23個のテストファイルが存在
    • 例: DailyArticleResultServiceTest.php、DailyDataRepositoryTest.phpなど

  2. パフォーマンステスト (tests/Performance/)

    • コードの実行速度やメモリ使用量を検証
    • 例: ConverterPerformanceTest.php（シングルトン化によるパフォーマンス向上を検証）

環境セットアップ ​

前提条件 ​

  • PHP: 8.3以上
  • Composer: 依存関係管理ツール

依存関係のインストール方法 ​

プロジェクトルートディレクトリで以下のコマンドを実行してください：

bash
# 開発依存関係を含めてインストール
composer install

# または、setupスクリプトを使用（依存関係インストール + レポートディレクトリ作成）
composer setup

これにより、PHPUnit 11.0以上とその他のテスト関連ツール（Brain Monkey、Mockeryなど）がインストールされます。

テスト実行方法 ​

基本コマンド ​

すべてのテストを実行 ​

bash
composer test

または、PHPUnitを直接実行：

bash
vendor/bin/phpunit

テストカバレッジレポートを生成 ​

bash
composer test-coverage

カバレッジレポートは reports/coverage/ ディレクトリにHTML形式で生成されます。ブラウザで reports/coverage/index.html を開くと、カバレッジレポートを確認できます。

特定のテストファイルを実行 ​

特定のテストファイルのみを実行する場合：

bash
# 特定のテストファイルを実行
vendor/bin/phpunit tests/Unit/Service/DailyArticleResultService/DailyArticleResultServiceTest.php

# または、Composerスクリプト経由で実行
vendor/bin/phpunit -- tests/Unit/Service/DailyArticleResultService/DailyArticleResultServiceTest.php

特定のテストメソッドを実行 ​

特定のテストメソッドのみを実行する場合：

bash
# --filter オプションを使用
vendor/bin/phpunit --filter test_method_name

# 例: DailyArticleResultServiceTestの特定のメソッドを実行
vendor/bin/phpunit --filter DailyArticleResultServiceTest::test_specific_method

フィルタを使った実行 ​

テストクラス名でフィルタ ​

bash
vendor/bin/phpunit --filter DailyArticleResultServiceTest

テストスイートでフィルタ ​

bash
# Unitテストのみ実行
vendor/bin/phpunit tests/Unit

# パフォーマンステストのみ実行
vendor/bin/phpunit tests/Performance

テスト構成の説明 ​

phpunit.xml の設定内容 ​

プロジェクトルートにある phpunit.xml ファイルで、PHPUnitの動作を設定しています。

主要な設定項目 ​

  • bootstrap: tests/bootstrap.php - テスト実行前に読み込まれるファイル
  • colors: true - カラー出力を有効化
  • processIsolation: false - テストを個別のプロセスで実行しない（高速化）
  • stopOnFailure: false - エラーが発生しても全テストを実行
  • cacheDirectory: .phpunit.cache - キャッシュディレクトリ
  • executionOrder: depends,defects - 依存関係と欠陥のあるテストを優先実行

テストスイート ​

xml
<testsuites>
    <testsuite name="Unit">
        <directory>tests/Unit</directory>
    </testsuite>
</testsuites>

現在は Unit テストスイートのみが定義されています。パフォーマンステストは手動で指定して実行します。

ソースコードの指定 ​

xml
<source>
    <include>
        <directory>core_src</directory>
    </include>
</source>

カバレッジレポート生成時に、core_src/ ディレクトリ内のコードを対象とします。

PHP設定 ​

xml
<php>
    <ini name="memory_limit" value="-1"/>  <!-- メモリ制限なし -->
    <ini name="error_reporting" value="-1"/>  <!-- すべてのエラーを報告 -->
    <ini name="display_errors" value="1"/>  <!-- エラーを表示 -->
</php>

テストディレクトリ構造 ​

tests/
├── bootstrap.php              # テスト実行前の初期化ファイル
├── Unit/                      # ユニットテスト
│   ├── Factory/
│   ├── Model/
│   ├── PostType/
│   ├── Repository/
│   ├── Service/
│   ├── ShortCode/
│   └── Util/
└── Performance/               # パフォーマンステスト
    └── ConverterPerformanceTest.php

bootstrap.php の役割 ​

tests/bootstrap.php は、すべてのテストの実行前に読み込まれるファイルです。以下の処理を行います：

  1. Brain Monkeyの有効化: WordPress関数のモックを有効化
  2. Composerオートローダーの読み込み: アプリケーションクラスとテストツールを読み込み
  3. WordPress関数のモック: wpdb、wp_cache_get、wp_cache_setなどのモック定義
  4. 環境変数の設定: テーマディレクトリパスなどの設定

テスト結果の見方 ​

成功時の出力 ​

テストが成功した場合、以下のような出力が表示されます：

PHPUnit 11.x.x by Sebastian Bergmann and contributors.

Runtime:       PHP 8.3.x
Configuration: /path/to/phpunit.xml

.................                                              17 / 17 (100%)

Time: 00:00.123, Memory: 12.00 MB

OK (17 tests, 45 assertions)
  • OK: すべてのテストが成功
  • 17 tests: 実行されたテストメソッドの数
  • 45 assertions: 実行されたアサーション（検証）の数

失敗時の出力 ​

テストが失敗した場合、以下のような出力が表示されます：

PHPUnit 11.x.x by Sebastian Bergmann and contributors.

Runtime:       PHP 8.3.x
Configuration: /path/to/phpunit.xml

F                                                                   1 / 1 (100%)

Time: 00:00.045, Memory: 8.00 MB

There was 1 failure:

1) Tests\Unit\Service\DailyArticleResultServiceTest::test_something
Failed asserting that false is true.

/path/to/tests/Unit/Service/DailyArticleResultServiceTest.php:42

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.
  • F: 失敗したテスト（Failure）
  • Failed asserting that false is true: アサーションの失敗内容
  • /path/to/...: 失敗が発生したファイルと行番号

エラーメッセージの読み方 ​

よくあるエラーメッセージ ​

  1. Failed asserting that...

    • アサーション（検証）が失敗
    • 期待値と実際の値が異なる

  2. Class 'App\SomeClass' not found

    • クラスが見つからない
    • オートローダーの問題、または名前空間の誤り

  3. Call to undefined function...

    • 関数が定義されていない
    • WordPress関数のモックが正しく設定されていない可能性

  4. Undefined property...

    • プロパティが定義されていない
    • モックオブジェクトの設定が不完全

カバレッジレポートの確認方法 ​

HTMLレポートの確認 ​

bash
composer test-coverage

実行後、reports/coverage/index.html をブラウザで開きます。

カバレッジレポートの見方 ​

  • 緑色: テストでカバーされている行
  • 赤色: テストでカバーされていない行
  • 黄色: 部分的にカバーされている行（条件分岐など）

カバレッジレポートでは、以下の情報を確認できます：

  • ファイルごとのカバレッジ率
  • 行ごとの実行回数
  • メソッドごとのカバレッジ率

実際のテストファイル例 ​

ユニットテストの例 ​

プロジェクトには以下のようなユニットテストが含まれています：

  • Service層のテスト: tests/Unit/Service/DailyArticleResultService/DailyArticleResultServiceTest.php
  • Repository層のテスト: tests/Unit/Repository/DailyDataRepositoryTest.php
  • Factory層のテスト: tests/Unit/Factory/ConverterFactoryTest.php
  • Util層のテスト: tests/Unit/Util/HeatMapClassGeneratorTest.php

パフォーマンステストの例 ​

  • Converterのパフォーマンステスト: tests/Performance/ConverterPerformanceTest.php
    • シングルトン化によるパフォーマンス向上を検証
    • 大量のインスタンス作成の実行時間を測定

テストファイルの構造 ​

典型的なテストファイルの構造：

php
<?php
namespace Tests\Unit\Service;

use PHPUnit\Framework\TestCase;
use App\Service\SomeService;

class SomeServiceTest extends TestCase {
    private SomeService $service;

    protected function setUp(): void {
        // テスト実行前の初期化処理
        $this->service = new SomeService();
    }

    public function test_something(): void {
        // テストの実装
        $result = $this->service->doSomething();
        $this->assertTrue($result);
    }
}

トラブルシューティング ​

よくあるエラーと解決方法 ​

1. "Class not found" エラー ​

症状: Class 'App\SomeClass' not found というエラーが発生

原因: オートローダーが正しく読み込まれていない

解決方法:

bash
# ルートおよび core_src で composer install を実行
composer install
cd core_src && composer install

2. WordPress関数のエラー ​

症状: Call to undefined function wp_cache_get() などのエラー

原因: WordPress関数のモックが正しく設定されていない

解決方法: tests/bootstrap.php が正しく読み込まれているか確認。phpunit.xml の bootstrap 設定を確認。

3. メモリ不足エラー ​

症状: Fatal error: Allowed memory size exhausted

解決方法: phpunit.xml でメモリ制限が -1（無制限）に設定されているか確認。それでも問題が発生する場合は、PHPの設定を確認：

bash
php -d memory_limit=-1 vendor/bin/phpunit

4. テストが遅い ​

原因: テストが多すぎる、または個別のテストが重い

解決方法:

  • 特定のテストファイルのみ実行
  • processIsolation が false に設定されているか確認（phpunit.xml）

5. カバレッジレポートが生成されない ​

原因: XdebugまたはPCOVがインストールされていない

解決方法: PHP拡張機能をインストール：

bash
# Xdebugをインストール（例: macOS + Homebrew）
pecl install xdebug

# または、PCOVをインストール
pecl install pcov

インストール後、php.ini に追加：

ini
; Xdebugの場合
zend_extension=xdebug.so

; PCOVの場合
extension=pcov.so

次のステップ ​

関連ドキュメント ​

テストを書く ​

新しい機能を実装する際は、必ずテストも作成してください：

  1. テストファイルを tests/Unit/ の適切なディレクトリに作成
  2. テストクラスは Tests\Unit\ 名前空間を使用
  3. PHPUnit\Framework\TestCase を継承
  4. テストメソッド名は test_ で始める

ベストプラクティス ​

  • 1つのテストメソッドで1つのことをテスト: テストが失敗したときに原因を特定しやすくする
  • 明確なアサーション: 何を検証しているかが分かるようにする
  • モックの適切な使用: 外部依存をモックして、テストを独立させる
  • テストデータの準備: setUp() メソッドで共通の初期化処理を行う

最終更新: 2026-01-17