Mantle Testkit is a standalone package for use of the Mantle Testing Framework on non-Mantle based projects. That means that you can use the great features of the Mantle Testing Framework on your existing projects/plugins/themes without needing to do any more refactoring.

Testkit should only be used on projects that do not use or define a Mantle application. The project can still utilize other components from Mantleopen in new window outside of testkit.

This document acts as a guide to transitioning your project to using Mantle Testkit for use of the Mantle Testing Library outside of Mantle.

Want to see a `/wp-content/`-rooted project that is using Mantle?

If you're interested in seeing a /wp-content/-rooted project that is setup to use Mantle, checkout alleyinteractive/create-mantle-appopen in new window.

Getting Started

This guide assumes that we are in a wp-content/ rooted WordPress project.

Install mantle-framework/testkit as a dependency

composer require --dev mantle-framework/testkit

Change Test Case

Unit Tests should extend themselves from Testkit's Test_Case class in place of core's WP_UnitTestCase class.

use Mantle\Testkit\Test_Case as Testkit_Test_Case;

class Test_Case extends Testkit_Test_Case {

	public function test_example() {
		$this->go_to( home_url( '/' ) );
		$this->assertQueryTrue( 'is_home', 'is_archive' );

	public function test_factory() {
		$post = static::factory()->post->create_and_get(); // WP_Post.

		// ...

Adjusting Unit Test Bootstrap

Commonly unit tests live inside of plugins or themes. For this use case, we're going to adjust a theme's unit test bootstrap file to load the test framework.


The callback to install() is optional.

 * Theme Testing using Mantle Framework

namespace App\Tests;

// Install Mantle Testing Framework normally.

// Install Mantle Testing Framework with some callbacks.
	->before( ... )
	->after( ... )
	->loaded( function() {
		// The loaded callback is fired on 'wp_loaded'.
		// You can use this callback to load the main file of a plugin, theme, etc.

		// Setup any dependencies once WordPress is loaded, such as themes.
		switch_theme( 'twentytwenty' );

Running Tests

Run your tests using ./vendor/bin/phpunit or add a Composer script to allow for composer phpunit.