【続】PHPUnitテストを「WordPress Test Suite」を使ってWPでも動かすぜ!

2026.03.10

前回、PHPUnitをサイトに導入するメモを書いてみた。

PHPUnitテストの導入方法メモ(WPは対象外)

しかし、WordPressは独自の関数を持っているため、それらをユニットテストで動かすにはさらに設定が必要となる。

今回はWP関数もPHPUnitの対象にできる環境構築の方法をメモとして残しておきたい。

※ゴリゴリ前回の続きとなるので、必ず上記の記事を参考に前段階の導入はしておくこと。

① WordPressテーマ内テスト用に最適化

普通のPHPUnitだけだと、下記のようなWP関数をテストすると、エラーが起きてしまう。

例:

get_posts()

WP_Query

get_search_query()

これらをテストするには「WordPress Test Suite(wp-phpunit/wp-phpunit)」を追加する必要がある。

上記を入れると 上記のWordPressの検索ロジックまでテスト可能となるのだ。

まずはテーマ内で下記を実行して、WordPressのユニットテストを行うためのPHPUnit環境をインストールする。

composer require --dev wp-phpunit/wp-phpunit

こうすることで、開発環境専用の依存関係として追加するオプションが composer.json の require-dev に入る。

② bootstrapファイル作成

今度は下記を作成する。

tests/bootstrap.php

これが WPテストの起動ファイルとなる。

<?php

require dirname(__DIR__) . '/vendor/autoload.php';

require dirname(__DIR__) . '/vendor/yoast/phpunit-polyfills/phpunitpolyfills-autoload.php'; // 追加依存ライブラリ追加

define('WP_TESTS_CONFIG_FILE_PATH', 'C:/wordpress-develop/wp-tests-config.php');

$_tests_dir = 'C:/wordpress-develop/tests/phpunit';

require $_tests_dir . '/includes/functions.php';

// ①デフォルトテーマを使っている場合

tests_add_filter('muplugins_loaded', function () {

    require dirname(__DIR__) . '/functions.php';

});

// ②オリジナルのテーマを使っている場合切り替え

// tests_add_filter('setup_theme', function () {

//     switch_theme('テーマ名');

// });

require $_tests_dir . '/includes/bootstrap.php';

オリジナルのテーマを使っている場合はコード内①と②のコメントアウトを切り替えればOK。

③ phpunit.xmlも変更

<?xml version="1.0" encoding="UTF-8"?>

<phpunit bootstrap="tests/bootstrap.php">

    <testsuites>

        <testsuite name="Theme Test Suite">

            <directory>tests</directory>

        </testsuite>

    </testsuites>

</phpunit>

④ 不足依存ライブラリ追加

このまま実行すると、おそらく①関連で下記の高確率でエラーが出る

Error: The PHPUnit Polyfills library is a requirement for running the WP test suite.

If you are trying to run plugin/theme integration tests, make sure the PHPUnit Polyfills library (https://github.com/Yoast/PHPUnit-Polyfills) is available and either load the autoload file of this library in your own test bootstrap before calling the WP Core test bootstrap file; or set the absolute path to the PHPUnit Polyfills library in a "WP_TESTS_PHPUNIT_POLYFILLS_PATH" constant to allow the WP Core bootstrap to load the Polyfills.

If you are trying to run the WP Core tests, make sure to set the "WP_RUN_CORE_TESTS" constant to 1 and run `composer update -W` before running the tests.

Once the dependencies are installed, you can run the tests using the Composer-installed version of PHPUnit or using a PHPUnit phar file, but the dependencies do need to be installed whichever way the tests are run.

これは、WordPressテストの依存ライブラリ不足という意味なので、テーマ内ディレクトリで記載されたライブラリをコマンドで追加すればOK

composer require --dev yoast/phpunit-polyfills

これでvendorの中に「yoast/phpunit-polyfills」が入るはず(functionsでは設定済み)

⑤ WordPress公式テストライブラリ取得

自身の環境に入っているgit経由でCドライブ直下に「wordpress-tests-lib」を入れる

作業中のテーマではなくCドライブ直下にいれること

Windows + Local環境ならowershelでgithubからのクローンをおこなう

※PCにGitが入っていることが前提で、開いたらそのままコマンドを打つだけ

git clone https://github.com/WordPress/wordpress-develop.git C:\wordpress-develop

⑥ DBを新しく作成

DBには 既存サイトが入っている場合、下記のWordPressのテスト実行によって不具合が生じる可能性がある。

テーブル削除

↓

再作成

↓

テストデータ投入(新しいテーブル)

なのでDBはテスト用DBを別途作ったほうがいいだろう。

簡単に言うと、サイトが壊れる可能性があるので、テスト専用DBを作って、それ経由でテストを行えるようにするということだ。

※自分はunittestというDBを作って実行した

⑦ WdPテスト用のDB設定ファイル設定

導入後にテーマ内で再度「vendor/bin/phpunit」を実行すると、下記のエラーが出る

Error: wp-tests-config.php is missing! Please use wp-tests-config-sample.php to create a config file.

WordPressテスト用のDB設定ファイルがまだ無いという意味なので正常な挙動なので、まずはDB接続用のconfigファイルを作っていく

※テーマないではなくcドライブにインストールしたファイルが作業対象なので、間違えないように。

[bashで実行]

cp C:/wordpress-develop/wp-tests-config-sample.php C:/wordpress-develop/wp-tests-config.php

もしくは、デフォルトで入っている「wp-tests-config-sample.php」を手動で複製

「wp-tests-config.php」にしてもOK

⑧ DB設定を編集

先ほどの⑥には予めDB接続に必要な機構が作られているので、使っているツールXamppやLocalなどからDB接続情報を取得して下記に入力。

define( 'DB_NAME', 'wordpress_test' );

define( 'DB_USER', 'root' );

define( 'DB_PASSWORD', 'root' );

define( 'DB_HOST', 'localhost' );

※注意:DB HOSTは「’DB_HOST’, ‘127.0.0.1:ポート番号’」で入れること

127.0.0.1 は 世界共通で必ず自分自身を指す特別なIPで、「その人のPC自身」という意味だ。

→Local WordPressだとDB名はすべて「local」で各サイトの識別はポート番号で行われるため。

⑨ テーマのbootstrap.php のパス確認

「tests/bootstrap.php」でテストライブラリの場所が下記になっているか確認。

$_tests_dir = 'C:/wordpress-develop/tests/phpunit';

また、下記のように依存ライブラリのパスを通しておく。

require dirname(__DIR__) . '/vendor/autoload.php';

require dirname(__DIR__) . '/vendor/yoast/phpunit-polyfills/phpunitpolyfills-autoload.php'; //追加依存ライブラリ追加

確認が取れたら、テーマディレクトリで下記のコマンドを再度実行。

vendor/bin/phpunit

実行して下記が出れば無事テストは成功だ。

PHPUnit 10.x

OK (1 test, 1 assertion)

⑩ それでもエラーが出る場合

自分の場合、下記のエラーが出てしまった。

wp_die() called

Message: Your PHP installation appears to be missing the MySQL extension which is required by WordPress.

Please check that the mysqli PHP extension is installed and enabled.

If you are unsure what these terms mean you should probably contact your host. If you still need help you can always visit the WordPress support forums.

Title: Requirements Not Met

Args:

        response: 500

        code: mysql_not_found

        exit:

        back_link:

        link_url:

        link_text:

        text_direction: ltr

        charset: UTF-8

        additional_errors: array (

)

このエラーは WordPress PHPUnit自体ではなく、CLIで使われているPHP(Local)に mysqli 拡張が無いことが原因だった。

WPはMySQL接続に mysqli 拡張が必須であり、コマンドラインでの操作ではこれがオフになっていることがある

下記のコマンドでmysqliが出てくるか否かをチェックしてみよう。

 php -m

表示されるリストの中にmysqliが出てこなければ、php.iniで有効化する必要があるので、次のステップに進もう。

導入完了までもう少しだ。

⑪ mysqliを有効化

まずはLocalからの下記を開く

※WP構築ツール「Local」を使っている場合のパスなのでXamppなどはまた異なる

C:\Users\user_name\AppData\Local\Programs\Local\resources\extraResources\lightning-services\php-8.2.27+1\bin\win64\php.ini

その後、下記の記述を探しだす。

;extension=mysqli

;extension=pdo_mysql

これらから「;」を取って保存する。

これで mysqliが有効になったので、もう一度「vendor/bin/phpunit」を実行すればOKだ。

⑫ バージョン不具合で動かない場合

基本は上記で動くが、いざWPの関数やメソッドを入れてテストするとバージョン関連のエラーが出ることがある。

実際にSampleTest.phpを下記に変えてテストしてみる

<?php

class SampleTest extends WP_UnitTestCase
{
    public function test_wordpress_environment_loaded()
    {
        // WordPressの関数が使えるか確認
        $this->assertTrue(function_exists('get_bloginfo'));

        // WordPressのバージョンが取得できるか
        $this->assertNotEmpty(get_bloginfo('version'));
    }

    public function test_create_post_with_factory()
    {
        // WordPressのテスト用ファクトリで投稿作成
        $post_id = self::factory()->post->create([
            'post_title' => 'Unit Test Post'
        ]);

        // 投稿が取得できるか確認
        $post = get_post($post_id);

        $this->assertEquals('Unit Test Post', $post->post_title);
    }
}

自分の場合、上記テストしたらでエラーが起きた。

これはWordPress Test Framework は PHPUnit 11 をまだサポートしていないため、下記のエラーが返ってきたのだ

Call to undefined method PHPUnit\Util\Test::parseTestMethodAnnotations()

エラーのフロー

WordPress test framework

古い PHPUnit API を呼ぶ

PHPUnit 11 には存在しない

エラー

⑬ PHPUnitをダウングレード

公式の推奨方法としてはPHPUnit 9 にダウングレードすることだ。

テーマディレクトリで実行してみたが、これでも依存関係の問題で削除ができない場合がある。

composer remove phpunit/phpunit

そこで、下記を実行すればOKだ。

composer require --dev phpunit/phpunit:^9 -W

ちなみに「-w」は依存しているパッケージも含めてバージョンを調整するという意味で超重要だ。

この状態でもう一度「vendor/bin/phpunit」を実行し、下記が出ればOKだ。

OK (2 tests, 3 assertions)

これでひとまず環境構築は完了だ。

これにより、WPの関数やクエリなどもPhPUnitで実行できるようになる(少なくとも自分の環境では)。

PHPUnitはテストする内容によってメソッドを設定したり、ファイル内の特定のプログラムだけ単体テストすることも可能だ。

もちろんお作法的なルールなどもあるので、構築後の使い方は次回の記事で解説したいと思う。

PHPUnitテストで使えるメソッドやお作法的なルールのメモ

PIC UP