Japanized for WooCommerce

WordPress プラグインに自動ユニットテストを追加する方法: 完全ガイド2025年度版

in

WordPressのプラグイン開発においてのUnitTestの記事がすごく良かったので、自身の備忘録のためにも記事にしました。

How to add automated unit tests to your WordPress plugin の日本語訳と考えていただければと思います。

プラグイン開発において「自分の環境では動いたのに、ユーザーの環境では動かない」という経験はありませんか？ WordPress のバージョン、PHP のバージョン、他のプラグインとの競合……ユーザーの環境は千差万別です。

コードの品質を保ち、将来的なアップデートでのバグ（デグレード）を防ぐためには、自動ユニットテスト（単体テスト）の導入が不可欠です。

この記事では、テスト環境の構築から GitHub での自動化まで、省略されがちな設定手順も含めて徹底的にわかりやすく解説します。

1. なぜ WordPress でユニットテストが必要なのか？

ユニットテストとは、プログラムの小さな単位（関数やクラス）が「意図した通りに動くか」を自動的にチェックする仕組みです。

WordPress 開発においてテストを行うメリットは絶大です:

  • バグの早期発見: コードを変更した瞬間、既存の機能が壊れていないか即座に分かります。
  • 安心のリリース: 「主要な機能はすべてテスト済み」という状態でリリースできます。
  • ドキュメント代わりになる: テストコードを見れば、「この関数はどんなデータを入力し、何を返すのが正解か」がひと目で分かります。

今回は、WordPress の実際の動作環境（データベース含む）を模倣してテストを行う「統合テスト」に近い環境を構築します。

2. 事前準備：必要なツール

作業を始める前に、以下のツールがお使いのパソコン（ローカル環境）にインストールされている必要があります。

  • PHP & Composer: 依存パッケージの管理に必要です。
  • MySQL (または MariaDB): テスト用のデータベースを作成するために必要です。
    • 推奨設定: ユーザー名 root、パスワード root のユーザーを用意しておくとスムーズです。
  • Subversion (SVN): テストスクリプトが WordPress のテストライブラリをダウンロードする際に使用します（Git とは別に必要です）。
  • WP-CLI: WordPress のコマンドラインツール。ファイルの雛形作成に使います。
  • Git: ソースコード管理用。

3. ステップ1：テストファイルの雛形を作成する

まず、開発中のプラグインディレクトリに移動し、WP-CLI を使ってテストに必要なファイルを生成します。

ターミナル（コマンドプロンプト）で以下を実行してください。my-plugin の部分はあなたのプラグインのフォルダ名（スラッグ）に置き換えてください。

cd wp-content/plugins/my-plugin
wp scaffold plugin-tests my-plugin --ci=github

wp-env でローカル構築している場合は以下です。

cd wp-content/plugins/my-plugin
wp-env run cli wp scaffold plugin-tests my-plugin --ci=github

このコマンドで生成される重要なファイル：

  • bin/install-wp-tests.sh: テスト用 WordPress 環境をセットアップするスクリプト。
  • phpunit.xml.dist: テストの設定ファイル。
  • tests/bootstrap.php: テスト実行前に WordPress を読み込むためのファイル。

4. ステップ2：Composer でテストツールをインストール

次に、テストを実行するためのライブラリ（PHPUnit など）をインストールします。

依存パッケージのインストール

以下のコマンドを実行します。

composer require --dev yoast/phpunit-polyfills:^1.0 wp-phpunit/wp-phpunit:^6.3
  • wp-phpunit: WordPress 専用のテスト環境構築ツール。
  • phpunit-polyfills: 異なる PHP バージョン間での互換性を保つためのライブラリ。

.gitignore の設定

テスト関連の一時ファイルやライブラリが Git にコミットされないよう、.gitignore ファイルに以下を追記してください。

コード スニペット

/vendor/
.phpunit.result.cache

5. ステップ3：設定ファイルの調整（ここが重要！）

生成されたファイルをそのまま使うとエラーが出やすいため、開発環境に合わせて調整します。ここが挫折しやすいポイントなので丁寧に解説します。

1. composer.json にスクリプトを追加

コマンド一発でテスト環境を作れるよう、composer.json の "scripts" セクションに以下を追加します。

"scripts": {
    "test": "phpunit",
    "test-install": "bash bin/install-wp-tests.sh wordpress_test root 'root' 127.0.0.1 latest"
}
  • 解説: test-install コマンドは、「データベース名: wordpress_test」「ユーザー: root」「パスワード: root」でテスト環境を作れ、という命令です。お使いの MySQL 設定が違う場合はここを書き換えてください。

2. ディレクトリ構成の整理

テストファイルが増えても管理しやすいよう、フォルダを整理します。

  1. tests フォルダの中に Unit という新しいフォルダを作ります。
  2. tests/test-sample.php を tests/Unit/ の中に移動します。

3. phpunit.xml.dist の修正

テストの実行場所が変わったので、設定ファイルも書き換えます。

変更前:

<directory prefix="test-" suffix=".php">./tests/</directory>

変更後:

<testsuites>
    <testsuite name="testing">
        <directory suffix=".php">./tests/Unit/</directory>
    </testsuite>
</testsuites>
  • prefix="test-" を削除することで、ファイル名の制約を緩めています。
  • ./tests/Unit/ を参照するように変更しました。

4. tests/bootstrap.php の修正

テスト実行時に「WordPress が見つからない」というエラーを防ぐため、tests/bootstrap.php の冒頭（<?php のすぐ下）に以下のコードを追加します。

<?php
/**
 * PHPUnit bootstrap file.
 *
 * @package My_Plugin
 */

// ▼▼▼ ここから追加 ▼▼▼
define( 'TESTS_PLUGIN_DIR', dirname( __DIR__ ) );
define( 'UNIT_TESTS_DATA_PLUGIN_DIR', TESTS_PLUGIN_DIR . '/tests/Data/' );

// WP_CORE_DIR（WordPress本体の場所）を明示的に定義してエラーを防ぐ
if ( ! defined( 'WP_CORE_DIR' ) ) {
    $_wp_core_dir = getenv( 'WP_CORE_DIR' );
    if ( ! $_wp_core_dir ) {
        $_wp_core_dir = rtrim( sys_get_temp_dir(), '/\\' ) . '/wordpress';
    }
    define( 'WP_CORE_DIR', $_wp_core_dir );
}
// ▲▲▲ 追加ここまで ▲▲▲

$_tests_dir = getenv( 'WP_TESTS_DIR' );
// ... (以下、元のコードが続く)

6. ステップ4：テスト環境（WordPress）の構築

設定ができたら、実際にテスト用の WordPress 環境をパソコン上に構築します。

composer test-install

何が行われているの？ このコマンドは、一時フォルダに WordPress 本体をダウンロードし、MySQL にテスト専用のデータベース（wordpress_test）を作成します。普段使っている開発用の WordPress とは別の、真っさらな環境が作られます。

💡 エラーが出たら？ 「ディレクトリが見つからない」等のエラーが出た場合は、以前のインストールが不完全に残っている可能性があります。一時フォルダ（Macなら /tmp/wordpress や /var/folders/...）にある wordpress フォルダと wordpress-tests-lib フォルダを削除して、再実行してください。

7. ステップ5：最初のテストコードを書く

いよいよテストコードを書きます。例として、「Book（本）」というカスタム投稿タイプが正しく登録されるかをテストします。

tests/Unit/test-book-cpt.php というファイルを作成し、以下を記述してください。

<?php
class Test_Book_CPT extends WP_UnitTestCase {

    /**
     * 各テストの実行前に必ず呼ばれる準備メソッド
     */
    public function setUp(): void {
        parent::setUp();
        
        // プラグインの投稿タイプ登録関数を実行
        // (注意: 実際のプラグイン内の関数名に合わせてください)
        // mtp_register_cpt_book(); 
        
        // リライトルールを更新（カスタム投稿タイプのテストに必須）
        flush_rewrite_rules();
    }

    /**
     * テスト1: 'book' という投稿タイプが存在するか確認
     */
    public function test_book_post_type_is_registered() {
        // WordPressの関数を使って確認
        $exists = post_type_exists( 'book' );
        
        // アサーション: $exists が true であることを期待する
        $this->assertTrue( $exists, 'Book投稿タイプが登録されていません。' );
    }

    /**
     * テスト2: 実際に投稿を作成できるか確認
     */
    public function test_can_create_book_post() {
        // ファクトリーを使って疑似的に投稿を作成
        $post_id = self::factory()->post->create( [
            'post_type'  => 'book',
            'post_title' => 'テストブック',
        ] );

        // 作成された投稿を取得
        $post = get_post( $post_id );

        // アサーション: 投稿タイプが 'book' であるか
        $this->assertEquals( 'book', $post->post_type );
    }
}

テスト実行

ターミナルで以下を実行します。

composer test

成功すると、以下のような緑色のメッセージが表示されます！ OK (2 tests, 2 assertions)

8. ステップ6：GitHub Actionsでの自動化

最後に、GitHub にコードをプッシュした際、自動でテストが走るようにします。

wp scaffold で生成された .github/workflows/phpunit.yml（または testing.yml）を開き、以下の2点を修正してください。

  1. ブランチ名の変更: デフォルトで trunk になっている場合、最近の Git の標準である main に変更します。
  2. SVNのインストール: GitHub のサーバーには SVN が入っていないことがあるため、インストール手順を追加します。

修正例:

YAML

on:
  pull_request:
    branches:
      - main  # ← trunk から main に変更
      - master

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.0' # 必要なバージョン
          extensions: mbstring, intl
          tools: phpunit

      # ▼▼▼ これを追加 ▼▼▼
      - name: Install SVN
        run: sudo apt-get update && sudo apt-get install -y subversion
      # ▲▲▲ 追加ここまで ▲▲▲

      # ... (以下、依存インストールやテスト実行のステップ)

9. まとめ

お疲れ様でした！これで、以下の環境が整いました。

  1. ローカル環境: composer test 一発で、自分の PC 上でコードの健全性をチェックできる。
  2. GitHub 環境: コードを修正してプッシュするたびに、自動でテストが行われる。

最初は設定が少し手間に感じるかもしれませんが、一度セットアップしてしまえば、将来的なバグ修正や機能追加の際の「安心感」は段違いです。ぜひ、あなたのプラグイン開発にも取り入れてみてください。