How to Test WordPress Plugins with PHPUnit in 2024: A Step-by-Step Guide

Testing is an essential part of WordPress plugin development and development in general, ensuring your code is robust and free of bugs. The most popular tool for testing in PHP is PHPUnit. This guide will walk you through the process of setting up and running PHPUnit tests for your WordPress plugins.

Step 1: Install WP-ENV

WP-ENV is a tool provided by the WordPress core team to set up a local development environment. It simplifies the process of managing WordPress installations for development and testing purposes.

How to Install WP-ENV

1. Ensure you have Docker installed on your system.
2. Install WP-ENV globally using npm: npm install -g @wordpress/env

Setting Up WP-ENV

1. Navigate to your plugin directory: cd path/to/your/plugin
2. Initialize WP-ENV: wp-env start

This command sets up a Docker environment with WordPress installed, making it easy to start development immediately.

Step 2: Install PHPUnit with wp scaffold plugin-tests

The wp scaffold plugin-tests command is part of WP-CLI, a powerful command-line interface for managing WordPress installations. WP-CLI allows developers to perform various tasks, such as installing and updating WordPress, managing plugins and themes, and setting up testing environments.

How to Scaffold Plugin Tests

1. From your plugin directory, run the following command: wp-env run cli --env-cwd={plugin-dir} wp scaffold plugin-tests your-plugin-slug

This command generates a tests directory and includes the necessary PHPUnit configuration files.

Step 3: Install Dependencies and Set Up a Testing Environment

Before running the tests, you can set up a separate database specifically for testing.

Running the Installation Script

1. Execute the script to set up the testing environment: wp-env run cli --env-cwd={plugin-dir}bash bin/install-wp-tests.sh wordpress_test root password mysql

Replace wordpress_test with the name of your test database, root with your database user, password with the password, and mysql if your database is hosted elsewhere than the WP-ENV mysql container.

Step 4: Configure PHPUnit

Next, you need to configure PHPUnit by creating a phpunit.xml file from the provided phpunit.xml.dist.

Creating the Configuration File

1. Duplicate the phpunit.xml.dist file:cp phpunit.xml.dist phpunit.xml
2. Edit phpunit.xml to suit your testing environment. You can specify custom bootstrap files, define environment variables, and more. You can leave it by default.

Step 5: Write the Unit Tests

Now that everything is set up, it’s time to write your unit tests. PHPUnit tests are written as PHP classes that extend WP_UnitTestCase.

Example Unit Test

Create a test file in the tests directory, for example, test-sample.php:

<?php

class SampleTest extends WP_UnitTestCase {
    public function test_sample() {
        // Replace this with some actual testing code.
        $this->assertTrue( true );
    }
}

In this example, test_sample is a simple test that always passes. Replace it with real tests for your plugin’s functionality.

Step 6: Execute the Tests

With your tests written and configured, you can now run them using PHPUnit.

Running the Tests

1. From your plugin directory, execute the following command: phpunit
   Or call it from the container with `wp-env`wp-env run cli --env-cwd={plugin-dir}vendor/bin/phpunit

This command runs all the tests in the tests directory, providing you with feedback on their success or failure.

In case you are having problems like:

Warning: Class "PHPUnit\Framework\Error\Deprecated" not found

1) Class test-xxx cannot be found in test-xxx.php

That is because you are using an incorrect version of PHPUnit and yoast/phpunit-polyfills, you should use yoast/phpunit-polyfills:”^1.0. Install the dependency via composer and adjust it on tests/bootstrap.php: wp-env run cli --env-cwd=wp-content/plugins/backend-v2-code-test-JoaquinRuiz composer require --dev yoast/phpunit-polyfills:"^1.0"

Conclusion

By following these steps, you’ve set up a comprehensive testing environment for your WordPress plugin using PHPUnit. Regularly running these tests will help you maintain high-quality code and catch bugs early in the development process.

How do you test your plugins? Do you have a different approach? Leave a comment here and share your experiences! 🙂