Skip to main content
Version: 1.x

Testing

Mantle provides a powerful testing framework to help you write and run tests for your WordPress applications. It is designed to be simple to use and IDE-friendly. For use with existing projects using core's testing framework, Mantle Testkit can be used to replace the core test suite with Mantle's testing framework.

Introduction​

Mantle provides a PHPUnit test framework to make it easier to test your code with WordPress. It is focused on making testing your application faster and easier, allowing unit testing to become top of mind when building your site. Mantle includes many convenient helpers to allow you to expressively test your applications.

use App\Tests\TestCase;

class ExampleTest extends TestCase {
	public function test_example(): void {
		$post = static::factory()->post->create_and_get();

		$this->get( get_permalink( $post ) )
			->assertOk()
			->assertQueriedObject( $post )
			->assertSee( $post->post_title );
	}
}

With Mantle, your application's tests live in your tests directory. Tests should extend from the App\Tests\Test_Case test case, which include booting and the use of your Mantle application inside of your test case. By default, your application's tests directory contains two directories: Feature and Unit. Unit tests are tests that focus on a very small, isolated portion of your code. In fact, most unit tests probably focus on a single method. Tests within your "Unit" test directory do not boot your Mantle application and therefore are unable to access your application's database or other framework services. The tests within "Unit" extend from the base PHPUnit test case and cannot use the rest of the testing framework.

Feature tests may test a larger portion of your code, including how several objects interact with each other or even a full HTTP request to a JSON endpoint. Generally, most of your tests should be feature tests. These types of tests provide the most confidence that your system as a whole is functioning as intended.

Interested in using the testing framework outside of a Mantle application?

Mantle Testkit is a standalone package that can be used to run Mantle's testing framework in any WordPress project. Learn more about Mantle Testkit.

Supported PHPUnit Versions​

Mantle supports PHPUnit 10-12 with 12 being the default version for new projects. Tests should be written using PSR-4 file/class naming conventions to ensure compatibility with PHPUnit 10 and later (e.g. tests/Feature/ExampleTest.php).

Mantle < 1.14 supported PHPUnit 9.x

Mantle versions prior to 1.14 supported PHPUnit 9.x. If you are using PHPUnit 9.x, you will need to use Mantle 1.13.x or earlier. When you are ready, you can migrate to PHPUnit 10+.

Creating Tests​

To create a new test case, use the make:test command. By default, the tests will be placed in the tests directory.

Note: These commands only work for Mantle applications.

bin/mantle make:test Namespace\Test_Name>

wp mantle make:test <Namespace\Test_Name>

Running Tests​

After installing alleyinteractive/mantle-framework or mantle-framework/testkit, you can begin writing and running tests for your WordPress application. Unit tests can be run directly or via Composer:

./vendor/bin/phpunit
Interested in writing tests using Pest?

Mantle's testing framework is fully compatible with Pest. You can use Pest to write your tests if you prefer its syntax and features. Learn more about using Pest with Mantle.

Running Tests in Parallel​

Mantle's testing framework supports running tests in parallel using paratest. To get started, install brianium/paratest as a development dependency:

composer require --dev brianium/paratest

paratest is a drop-in replacement for PHPUnit that runs your tests in parallel. To switch to using paratest, replace phpunit with paratest when running your tests:

./vendor/bin/paratest

When running in parallel, each test process will use its own database prefix to isolate the processes from each other. By default, the prefix will be wptests_ followed by an incrementing number (e.g. wptests_1, wptests_2, etc.).

For the most part, running tests in parallel should "just work." However, there are some cases where you may need to make adjustments to your tests to ensure they work correctly when run in parallel. For example, if your tests rely on global state (e.g. global variables, singletons, etc.), you may need to refactor your tests to avoid that global state or reset it between tests.

Background​

Why This Instead of WordPress Core's Test Suite?​

We hope nobody interprets Mantle's Test Framework as a slight against WordPress Core's test suite. We ❤️ WordPress Core's test suite and Mantle's Test Framework is unequivocally a derivative work of it.

WordPress Core's test suite ("wordpress-develop", if you will) is a wonderful test suite for testing WordPress itself. We, and many others in the WordPress community, have been repurposing it for years to help us run plugin and theme tests. That's worked fine, but it's not optimal. Mantle's Test Framework tries to incorporate the best parts of WordPress Core's test suite, but remove the unnecessary bits. Without having to worry about older versions of PHP, that also allows Mantle's Test Framework to use the latest versions of PHPUnit itself.

Drop-in Support for Core Test Suite​

The Mantle Test Framework includes support for WordPress core's test suite methods, including go_to() and $this->factory() among others. Projects are able to switch to the Mantle Test Framework without needing to rewrite any existing unit tests. See the Mantle Test Kit for more information.

Future Plans​

Mantle's Test Framework is actively being developed. Our future plans are to continue making the testing framework the best possible experience for testing WordPress projects. Testing is a critical part of building high-quality software, and we want to make that as easy as possible for WordPress developers.

Using the Testing Framework​

The testing framework is flexible enough to support running tests in a variety of environments. The most common use case is running tests in an existing WordPress project. For example, you could run tests within a plugin that is located within a larger WordPress project. This would fall under the Running Tests Within a WordPress Project guide for using an existing WordPress project to run tests against.

The framework also supports running tests within an isolated project. For example, a standalone plugin/theme that is not located inside a WordPress project. This would fall under the Running Tests in a Standalone Project guide for using an isolated project to run tests against.

Mantle's Test Framework provides a special bootstrapper and installer for WordPress. It is common in WordPress to use a separate WordPress codebase when running unit tests. In Mantle, you use the same codebase and a separate database. As long as your test suite isn't writing to any files, a singular codebase is a preferable setup, especially if you want to use XDebug to step through your test or want to rely on your IDE to discover testing framework methods.

Running Tests Within a WordPress Project​

When running tests within a WordPress project, Mantle will use the existing WordPress installation to run tests against. This is the most common use case for Mantle's Test Framework. While the codebase will be used, the database will not be. Mantle will attempt to use a default configuration to connect to locally. The default configuration will install WordPress using a localhost database named wordpress_unit_tests with the username/password pair of root/root. This can be overridden by defining your own wp-tests-config.php file in the root of your WordPress project.

Mantle can generate a wp-tests-config.php file for you

You can generate your own config file by running bin/mantle test-config.

Running Tests in a Standalone Project​

A standalone project that isn't located within an existing WordPress project can be used to run tests against. Mantle will automatically install WordPress for you without needing to run any manual bash script in your continuous integration process. This means that you only have to run composer test instead of having to run a bash script to setup WordPress, rsync it to a temporary folder, and then run your tests.

Internally, Mantle will run a shell script that will install WordPress for you at a temporary directory. For plugins, this is more than enough to provide a WordPress installation to run tests against. Your tests and project would remain where it is currently and the rest of WordPress would be installed within a temporary directory.

Themes or more integrated projects will need to rsync your project to the temporary directory to run tests against.

Rsyncing Your Project to a WordPress Installation​

Mantle can rsync your project to within a working WordPress installation without needing to run any rsync command yourself. This is useful for themes or more integrated projects that need to run tests against a fully integrated WordPress installation. Within your tests/bootstrap.php file, you can use the Installation Manager to rsync your project to the WordPress installation:

// Rsync a plugin to live as a plugin within a WordPress installation.
\Mantle\Testing\manager()
	->maybe_rsync_plugin()
	->install();

// Rsync a theme to live as a theme within a WordPress installation.
\Mantle\Testing\manager()
	->maybe_rsync_theme()
	->install();

For more information, read more about the Installation Manager.

More Reading​

Continue reading about the Mantle Testing Framework by checking out the following sections: