wpsyntex / wp-phpunit
PHPUnit library for WordPress
Requires
- php: >=7.0
- cheprasov/php-cli-args: ^3.0
- symfony/console: ^3.4 || ^4.4
- yoast/wp-test-utils: ^1.0.0
Requires (Dev)
- php-stubs/woocommerce-stubs: *
- wpsyntex/polylang-cs: dev-main
- wpsyntex/polylang-phpstan: dev-master
- wpsyntex/polylang-stubs: dev-master
This package is auto-updated.
Last update: 2024-10-21 19:15:14 UTC
README
A code library for WP Syntex projects, containing:
- scripts to install the WordPress test suite,
- scripts to install the required plugins and themes,
- scripts for building and distributing the project,
- bootstraps allowing to init unit and integration tests,
- helpers for the tests.
How to
Install the test suite
The test suite is installed in your project's tmp
folder.
To tell the installation script how to connect to your database, you can create a DB-CONFIG
file at the root of your project and formatted like follow (the file is not versioned with git of course).
Each line is optional, the default values are:
db_host: localhost db_name: wordpress_tests db_user: root db_pass: '' (an empty string)
Install the dependencies
The plugins and themes are installed in your project's tmp
folder.
Create a install-plugins.sh
file that launches all the downloads. Example:
#!/usr/bin/env bash . "$PWD/vendor/wpsyntex/wp-phpunit/bin/wp-download-tools.sh" mkdir -p $WP_PLUGINS_DIR mkdir -p $WP_THEMES_DIR # Install WP All Import Pro. downloadPluginFromEdd wp-all-import-pro 'WP All Import' https://www.wpallimport.com # Install Polylang Pro. downloadPolylangPro # Install Polylang for WooCommerce. downloadPolylangForWoocommerce # Install WooCommerce. downloadWoocommerce # Install TwentyFourteen. downloadThemeFromRepository twentyfourteen
Note: two variables are available for you to use: $WP_PLUGINS_DIR
and $WP_THEMES_DIR
. They contain the path to tmp/plugins
and tmp/themes
respectively, where the plugins and themes are installed. Those folders are not created by default so don't forget to do mkdir -p $WP_PLUGINS_DIR
and/or mkdir -p $WP_THEMES_DIR
like in the previous example, before using the download functions.
Premium plugins installed from EDD need a bit more attention because they need a license key. You can provide it by creating a LICENSE-CODES
file at the root of your project and formatted like follow (the file is not versioned with git of course):
license {PLUGIN-SLUG}:{YOUR-LICENSE} site {PLUGIN-SLUG}:{YOUR-SITE}
Depending on EDD config, the site
line may not be required.
Also, if your plugin from EDD doesn't require a license key, do the following:
license {PLUGIN-SLUG}:none
Composer scripts
Then you can create composer scripts like these ones for example:
{ "scripts": { "install-suite": "vendor/wpsyntex/wp-phpunit/bin/install-wp-suite.sh", "install-suite-with-db": "vendor/wpsyntex/wp-phpunit/bin/install-wp-suite.sh latest true", "install-plugins": "Tests/bin/install-plugins.sh", "install-tests": [ "@install-suite", "@install-plugins" ], "install-tests-with-db": [ "@install-suite-with-db", "@install-plugins" ], "build": "vendor/wpsyntex/wp-phpunit/bin/build.sh", "build-update": "vendor/wpsyntex/wp-phpunit/bin/build.sh -- -u", "dist": "vendor/wpsyntex/wp-phpunit/bin/distribute.sh -- polylang-foobar" }, "scripts-descriptions": { "install-suite": "Installs the WordPress tests suite (without installing the database).", "install-suite-with-db": "Installs the WordPress tests suite (with database creation).", "install-plugins": "Installs dependencies needed for integration tests.", "install-tests": "Installs both the WordPress tests suite (without installing the database) and the dependencies needed for integration tests.", "install-tests-with-db": "Installs both the WordPress tests suite (with database creation) and the dependencies needed for integration tests, without creating the database.", "build": "Builds the project.", "build-update": "Builds the project (runs `composer update` instead of `composer install`).", "dist": "Makes the zip file to distibute the project release." } }
Integration tests
Bootstrap for integration tests
Example for your bootstrap.php
file:
<?php /** * Bootstraps the Polylang Foobar integration tests * php version 7.0 * * @package WP_Syntex\Polylang_Foobar\Tests\Integration */ namespace WP_Syntex\Polylang_Foobar\Tests\Integration; use function WP_Syntex\Polylang_Phpunit\Integration\bootstrapSuite; require dirname( dirname( __DIR__ ) ) . '/vendor/wpsyntex/wp-phpunit/UnitTests/Integration/bootstrap.php'; bootstrapSuite( dirname( __DIR__ ), // Path to the directory containing all tests. '7.0.0', // The PHP version required to run this test suite. [ 'plugins' => [ 'polylang-pro/polylang.php' => true, 'woocommerce/woocommerce.php' => [ 'group' => 'WithWoo', 'init' => '\WP_Syntex\Polylang_Phpunit\Integration\WooCommerce\Bootstrap::initWoocommerce', ], 'polylang-wc/polylang-wc.php' => [ 'group' => 'WithWoo', ], dirname( dirname( __DIR__ ) ) . '/polylang-foobar.php' => true, ], // A list of plugins to include and activate. ] );
The previous code will:
- Require
polylang.php
andpolylang-foobar.php
. - Require
woocommerce.php
andpolylang-wc.php
if--group=WithWoo
is used when invoking phpunit. - Call
\WP_Syntex\Polylang_Phpunit\Integration\WooCommerce\Bootstrap::initWoocommerce()
afterwoocommerce.php
is required.
Use the trait in your integration tests
You can use the trait WP_Syntex\Polylang_Phpunit\Integration\TestCaseTrait
in your integration tests.
Hint: if you need to create your own methods set_up()
, wpSetUpBeforeClass
, etc, you can't simply call the ones from the trait with parent::
like you would with parent/child classes. In this case you can do that:
<?php /** * Test Case for all of the integration tests. * php version 7.0 * * @package WP_Syntex\Polylang_Foobar\Tests\Integration */ namespace WP_Syntex\Polylang_Foobar\Tests\Integration; use WP_Syntex\Polylang_Phpunit\Integration\TestCaseTrait; use WP_UnitTest_Factory; use WP_UnitTestCase; abstract class AbstractTestCase extends WP_UnitTestCase { use TestCaseTrait { wpSetUpBeforeClass as private traitWpSetUpBeforeClass; set_up as private traitSetUp; } public static function wpSetUpBeforeClass( WP_UnitTest_Factory $factory ) { self::traitWpSetUpBeforeClass( $factory ); // Do things. } public function set_up() { $this->traitSetUp(); // Do more things. } }
If you need to list some plugins among the "active ones" (get_option( 'active_plugins' )
) for your integration tests (this may be required for some plugins that test which plugins are active), you can create a class like this one in your tests:
<?php /** * Test Case for all of the integration tests. * php version 7.0 * * @package WP_Syntex\Polylang_Foobar\Tests\Integration */ namespace WP_Syntex\Polylang_Foobar\Tests\Integration; use WP_Syntex\Polylang_Phpunit\Integration\TestCaseTrait; use WP_UnitTestCase; /** * Test Case for all of the integration tests. */ abstract class AbstractTestCase extends WP_UnitTestCase { use TestCaseTrait; /** * List of active plugins. * * @var array<string> */ protected $activePlugins = [ 'wp-all-import-pro/wp-all-import-pro.php', ]; }
Some helpers are available in your tests, like toying with reflections or getting test data. You can find them in the TestCaseTrait
trait.
Unit tests
Bootstrap for unit tests
Example for your bootstrap.php
file:
<?php /** * Bootstraps the Polylang Foobar Unit Tests. * php version 7.0 * * @package WP_Syntex\Polylang_Foobar\Tests\Unit */ namespace WP_Syntex\Polylang_Foobar\Tests\Unit; use function WP_Syntex\Polylang_Phpunit\Unit\bootstrapSuite; require dirname( dirname( __DIR__ ) ) . '/vendor/wpsyntex/wp-phpunit/UnitTests/Unit/bootstrap.php'; bootstrapSuite( dirname( __DIR__ ), '7.0.0' );
Extend the abstract class in your unit tests
You can extend WP_Syntex\Polylang_Phpunit\Unit\AbstractTestCase
in your unit tests.
Brain\Monkey is available in your unit tests, since it is included in Yoast\WPTestUtils.
In your tests you can mock WordPress' most common functions by setting two custom properties. And like for integration tests, some helpers are available in your tests, from the TestCaseTrait
trait.
<?php /** * Tests for `WP_Syntex\Polylang_Foobar\barbaz()`. * php version 7.0 * * @package WP_Syntex\Polylang_Foobar\Tests\Unit */ namespace WP_Syntex\Polylang_Foobar\Tests\Unit; use WP_Syntex\Polylang_Phpunit\Unit\AbstractTestCase; /** * Tests for `WP_Syntex\Polylang_Foobar\barbaz()`. */ class Barbaz extends AbstractTestCase { /** * Stubs the WP native translation functions in the set_up(). * * @var bool */ protected static $stubTranslationFunctions = true; /** * Stubs the WP native escaping functions in the set_up(). * * @var bool */ protected static $stubEscapeFunctions = true; }