Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 27 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,21 @@
# WP PHPUnit Integration

The WP PHPUnit Integration package helps you write PHPUnit tests for your WordPress packages where you prefer to have the actual implementation of WordPress functions and classes available, rather than mocking them with a library such as [Brain Monkey](https://github.com/Brain-WP/BrainMonkey).
This package helps you write PHPUnit tests for your WordPress packages where you prefer to have the actual implementation of WordPress functions and classes available, rather than mocking them with a library such as [Brain Monkey](https://github.com/Brain-WP/BrainMonkey).

Depending on your intent for your tests, it is ideal for functional or integration tests, where you can also take advantage of the database.
Depending on your intent, it is ideal for functional or integration tests, where you can also take advantage of the database.

Once you require and configure this package, it will set up a fully functional WordPress environment before the tests are run, install WordPress, symlink and activate your plugin or theme, and reset everything once the tests have finished.
Once you require and configure WP PHPUnit Integration, it will set up a fully functional WordPress environment before the tests are run (installing WordPress, symlinking and activating your plugin or theme, etc.), and reset everything once the tests have finished.

All you need is PHP. You don't need a test database service running such as MySQL or MariaDB, or to configure and start Docker containers, as this package also takes advantage of the [SQLite Database Integration](https://github.com/WordPress/sqlite-database-integration).
All you need is PHP. You don't need a database service running, such as MySQL or MariaDB, for your tests, or to configure and start Docker containers, as this package also takes advantage of the [SQLite Database Integration](https://github.com/WordPress/sqlite-database-integration).

## Setup and usage

> [!WARNING]
> This package is currently in a pre-stable release. Breaking changes may occur between versions until a stable `1.0` release is published.

### Installation

You can require this package with Composer:
As a first step, require this package with Composer:

```shell
composer require --dev syde/wp-phpunit-integration
Expand All @@ -39,13 +42,13 @@ You can also specify where you want to install WordPress by adding the following
}
```

No fixed location is required, as the WP PHPUnit Integration will automatically detect the location.
No fixed location is required, as WP PHPUnit Integration will automatically try to detect the location.

### Setup

You can use WP PHPUnit Integration for all your PHPUnit tests.

However, if you already have unit tests where you use Brain Monkey, we recommend creating separate PHPUnit configuration and bootstrap files for your integration tests, as these files can quickly grow complex over time and become messy.
However, if you already have unit tests where you use, for example, Brain Monkey, we recommend creating separate PHPUnit configuration and bootstrap files for your integration tests, as these files can quickly grow complex over time and become messy.

The following steps describe this scenario.

Expand Down Expand Up @@ -76,7 +79,7 @@ unset($packagePath, $vendorPath);

#### PHPUnit configuration

Create a `/phpunit-integration.xml.dist` file with the following content:
Next, create a `/phpunit-integration.xml.dist` file with the following content:

```xml
<phpunit
Expand All @@ -93,7 +96,7 @@ Create a `/phpunit-integration.xml.dist` file with the following content:

#### Composer scripts

Then, in your `composer.json`, add dedicated integration test scripts alongside your existing ones:
Finally, in your `composer.json`, add dedicated integration test scripts alongside your existing ones:

```json
{
Expand All @@ -106,7 +109,7 @@ Then, in your `composer.json`, add dedicated integration test scripts alongside
}
```

If you have followed these steps, you should now be able to run your integration tests with:
If you've followed these steps, you should now be able to run your integration tests with:

```shell
composer run tests:integration:no-cov
Expand Down Expand Up @@ -146,10 +149,9 @@ WP PHPUnit Integration has three distinct phases that you can customize.

The `setup` and `cleanup` phases run only once, before and after all tests are executed. As their names suggest, they trigger steps such as creating the `wp-config.php`, setting up required constants, or undoing these actions.


The `load` phase is called before both the main test process and any child processes. When the test is run in isolation, `load` is called multiple times, either before the [test class](https://docs.phpunit.de/en/10.5/attributes.html#runtestsinseparateprocesses) or [test method](https://docs.phpunit.de/en/10.5/attributes.html#runinseparateprocess), depending on your PHPUnit [configuration](https://docs.phpunit.de/en/10.5/configuration.html#the-processisolation-attribute).

Each phase can be customized by running additional logic before or after the defaults, or by replacing it entirely.
Each phase can be customized by running additional logic before or after the defaults, or by replacing it entirely:

```php
use Syde\WpPhpUnitIntegration\Bootstrap;
Expand All @@ -159,17 +161,17 @@ use Syde\WpPhpUnitIntegration\WpTestEnv;
Bootstrap::init(
$packagePath,
new BootstrapLifecycle(
setup: function () {
setup: function (): void {
// Run some setup tasks before the default ones.

WpTestEnv::setup();
},
load: function () use ($packagePath) {
load: function () use ($packagePath): void {
// Omit the default WpTestEnv::load() to use your own custom logic.

include "{$packagePath}/vendor/roots/wordpress/wp-load.php";
},
cleanup: function () {
cleanup: function (): void {
WpTestEnv::cleanup();

// Run some extra cleanup tasks after the default ones.
Expand All @@ -184,7 +186,7 @@ For convenience, `WpTestEnv` exposes some helper methods to cover most customiza

#### WP-CLI commands

`runWpCliCommand` triggers a call to WP-CLI without returning any output from it:
With `runWpCliCommand`, you can run arbitrary WP-CLI commands:

```php
WpTestEnv::runWpCliCommand([
Expand All @@ -194,7 +196,9 @@ WpTestEnv::runWpCliCommand([
]);
```

You can use any WP-CLI commands, but keep in mind that they are called with the `--skip-plugins,` `--skip-themes,` and an explicit `--path` option.
`runWpCliCommand` returns the `stdout` output, and if an error occurs, an exception is thrown with the error message returned by WP-CLI.

You can use any WP-CLI commands, but keep in mind that they are called with the `--skip-plugins`, `--skip-themes`, and an explicit `--path` option.

#### Early hooks

Expand All @@ -213,17 +217,19 @@ WpTestEnv::addEarlyFilter(

### WordPress version

To quickly test against multiple WordPress versions, set the `WP_PHPUNIT_INTEGRATION_WP_CORE_VERSION` (or simply `WP_CORE_VERSION`) environment variable. When provided, the setup process will automatically update WordPress to that specific version.
To quickly test against multiple WordPress versions, you can set the `WP_PHPUNIT_INTEGRATION_WP_CORE_VERSION` (or simply `WP_CORE_VERSION`) environment variable. When provided, the setup process will automatically update WordPress to that specific version.

```shell
WP_PHPUNIT_INTEGRATION_WP_CORE_VERSION=6.8 composer run tests:integration:no-cov
```

This environment variable is optional. Without it, the already-installed WordPress version is used.
This environment variable is optional. Without it, the already-installed WordPress version is used without attempting to update it using WP-CLI.

#### Multiple WordPress versions in GitHub Actions

To take advantage of the environment variable in GitHub Actions, amend your existing workflow as follows:
You can take advantage of this environment variable in GitHub Actions to run tests against multiple WordPress versions.

To do this, amend the [previously mentioned workflow](#github-actions) as follows:

```yaml
jobs:
Expand All @@ -247,8 +253,7 @@ jobs:

## Copyright and License

This package is [open-source software](https://opensource.org/license/MIT) distributed under
the terms of the MIT License. For the full license, see [LICENSE](./LICENSE).
This package is [open-source software](https://opensource.org/license/MIT) distributed under the terms of the MIT License. For the full license, see [LICENSE](./LICENSE).

## Contributing

Expand Down
10 changes: 6 additions & 4 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -37,11 +37,13 @@
},
"repositories": [
{
"name": "wpackagist",
"type": "composer",
"url": "https://repo.packagist.com/inpsyde/"
},
{
"packagist.org": false
"url": "https://wpackagist.org",
"only": [
"wpackagist-plugin/*",
"wpackagist-theme/*"
]
}
],
"minimum-stability": "dev",
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
"lint:md:fix": "wp-scripts lint-md-docs README.md docs/**/*.md -- --fix"
},
"devDependencies": {
"@wordpress/scripts": "wp-6.9"
"@wordpress/scripts": "wp-7.0"
},
"engines": {
"node": "~24.0"
Expand Down
Loading