# 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](/docs/testing/testkit.md) can be used to replace the core test suite with Mantle's testing framework.

## Introduction[​](#introduction "Direct link to 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.

```php
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](/docs/testing/testkit.md) is a standalone package that can be used to run Mantle's testing framework in any WordPress project. [Learn more about Mantle Testkit](/docs/testing/testkit.md).

## Supported PHPUnit Versions[​](#supported-phpunit-versions "Direct link to 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+](/docs/testing/migration-phpunit-9.md).

## Creating Tests[​](#creating-tests "Direct link to 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.*

```bash
bin/mantle make:test Namespace\Test_Name>

wp mantle make:test <Namespace\Test_Name>

```

## Running Tests[​](#running-tests "Direct link to 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:

```bash
./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](/docs/testing/pest.md).

### Running Tests in Parallel[​](#running-tests-in-parallel "Direct link to Running Tests in Parallel")

Mantle's testing framework supports running tests in parallel using [`paratest`](https://github.com/brainmaestro/paratest). To get started, install `brianium/paratest` as a development dependency:

```bash
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:

```bash
./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[​](#background "Direct link to Background")

### Why This Instead of WordPress Core's Test Suite?[​](#why-this-instead-of-wordpress-cores-test-suite "Direct link to 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[​](#drop-in-support-for-core-test-suite "Direct link to 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](/docs/testing/testkit.md) for more information.

### Future Plans[​](#future-plans "Direct link to 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[​](#using-the-testing-framework "Direct link to 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](#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](#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[​](#running-tests-within-a-wordpress-project "Direct link to 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](https://github.com/alleyinteractive/mantle-ci/blob/main/wp-tests-config-sample.php) 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[​](#running-tests-in-a-standalone-project "Direct link to 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](https://github.com/alleyinteractive/mantle-ci/blob/HEAD/install-wp-tests.sh) 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](#rsyncing-your-project-to-a-wordpress-installation) to the temporary directory to run tests against.

### Rsyncing Your Project to a WordPress Installation[​](#rsyncing-your-project-to-a-wordpress-installation "Direct link to 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](/docs/testing/installation-manager.md) to rsync your project to the WordPress installation:

```php
// 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](/docs/testing/installation-manager.md).

## More Reading[​](#more-reading "Direct link to More Reading")

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

## [📄️<!-- --> <!-- -->Testkit](/docs/testing/testkit.md)

[Mantle Testkit is a standalone package for using the Mantle Testing Framework on non-Mantle based projects.](/docs/testing/testkit.md)

## [📄️<!-- --> <!-- -->Installation Manager](/docs/testing/installation-manager.md)

[The Installation Manager is a class used to install WordPress for testing.](/docs/testing/installation-manager.md)

## [📄️<!-- --> <!-- -->HTTP Tests](/docs/testing/requests.md)

[Mantle provides a fluent HTTP Request interface to make it easier to write feature/integration tests using PHPUnit and WordPress.](/docs/testing/requests.md)

## [📄️<!-- --> <!-- -->Factory](/docs/testing/factory.md)

[Mantle supports a WordPress-core backwards compatible factory that can be used in tests to quickly generate posts, terms, sites, and more.](/docs/testing/factory.md)

## [📄️<!-- --> <!-- -->Assertions](/docs/testing/assertions.md)

[Assertions available in Mantle's Test Case.](/docs/testing/assertions.md)

## [📄️<!-- --> <!-- -->WordPress State](/docs/testing/state.md)

[During unit tests, the testing framework exposes some helper methods to allow you to modify or inspect the state of WordPress.](/docs/testing/state.md)

## [📄️<!-- --> <!-- -->Deprecation and Incorrect Usage](/docs/testing/deprecation-incorrect-usage.md)

[Deprecation and incorrect usage notices can be captured and asserted against in Mantle's Test Case.](/docs/testing/deprecation-incorrect-usage.md)

## [📄️<!-- --> <!-- -->Hooks](/docs/testing/hooks.md)

[Mantle provides an interface for testing WordPress hooks in declarative and assertive formats.](/docs/testing/hooks.md)

## [📄️<!-- --> <!-- -->Remote Requests](/docs/testing/remote-requests.md)

[Mocking remote requests in unit tests.](/docs/testing/remote-requests.md)

## [📄️<!-- --> <!-- -->Snapshot Testing](/docs/testing/snapshot-testing.md)

[Snapshot testing in Mantle's testing framework.](/docs/testing/snapshot-testing.md)

## [📄️<!-- --> <!-- -->Traits and Attributes](/docs/testing/traits-attributes.md)

[Traits and attributes that can be used to add optional functionality to a test case.](/docs/testing/traits-attributes.md)

## [📄️<!-- --> <!-- -->Users and Authentication](/docs/testing/users.md)

[The Mantle Test Framework provides methods and assertions for testing users and authentication.](/docs/testing/users.md)

## [📄️<!-- --> <!-- -->Cron and Queue](/docs/testing/cron.md)

[Cron and queue jobs can be asserted in unit tests.](/docs/testing/cron.md)

## [📄️<!-- --> <!-- -->Helpers](/docs/testing/helpers.md)

[Helpers to make it easier to write tests for your project.](/docs/testing/helpers.md)

## [📄️<!-- --> <!-- -->Continuous Integration](/docs/testing/continuous-integration.md)

[Using Continuous Integration (CI) in your development can help ease your mind when adding new features to a site. This guide will help you setup your Mantle application or project that is using Mantle's testing framework for CI via GitHub Actions.](/docs/testing/continuous-integration.md)

## [📄️<!-- --> <!-- -->Parallel Testing](/docs/testing/parallel.md)

[Run your WordPress unit tests in parallel to speed up your test suite.](/docs/testing/parallel.md)

## [📄️<!-- --> <!-- -->Pest](/docs/testing/pest.md)

[Mantle's Testing Framework supports running unit tests via Pest.](/docs/testing/pest.md)

## [📄️<!-- --> <!-- -->Environmental Variables](/docs/testing/environmental-variables.md)

[Environmental variables used within the testing framework.](/docs/testing/environmental-variables.md)

## [📄️<!-- --> <!-- -->Migration from PHPUnit 9](/docs/testing/migration-phpunit-9.md)

[Mantle's Test Framework 1.0 upgrades the PHPUnit version to 10.x. This is a](/docs/testing/migration-phpunit-9.md)