Testing

Previous Lesson
Next Lesson

Setting up for WP Unit Tests with NPM & WP-ENV

Testing Setting up for WP Unit Tests with NPM & WP-ENV

In this lesson we’ll learn how to set up WP PHPUnit testing using wp-env which doesn’t require additional Test DB setup. This will help you understand what is happening under the hood.

For standard / typical setup guide please follow:

PHP: PHPUnit

We will use the following tools:

  • Composer
  • NPM
  • Docker (Internally)

Let’s get started.

The following code is the minimum files / code required to run the WP PHP Unit tests.

Note: For this setup we don’t have to download the wordpress-develop repo.

Composer setup

  • Step 1
    • Create composer.json file
    • Add in basic details
  • Step 2
    • Add classmap autoload for your plugin src files
    • Add classmap autoload-dev for your test directory files.
{ 
  “name”: “namespace/plugin-name”,
  “require-dev”: {
“phpunit/phpunit”: “^8.5”,
“wp-phpunit/wp-phpunit”: “^5.9”,
“yoast/phpunit-polyfills”: “^1.0”
  },
  “autoload”: {
“classmap”: [
  “inc/”
]
  },
  “autoload-dev”: {
“classmap”: [
  “tests/”
]
  }
}

NPM Setup

The only dependency is @wordpress/env

Create following script commands

“test:php”: “wp-env run phpunit ‘phpunit -c /var/www/html/wp-content/plugins/$(basename \”$PWD\”)/phpunit.xml.dist –verbose'”,
“wp-env”: “wp-env”

Note: 

  • “wp-env run” is for starting / stopping the environment.
  • test:php for running phpunit tests
  • $(basename \\”$PWD\\”) might not work on Windows, you can use Git Bash to make it work on Windows
{
  “name”: “plugin”,
  “scripts”: {
    “test:php”: “wp-env run phpunit ‘phpunit -c /var/www/html/wp-content/plugins/$(basename \”$PWD\”)/phpunit.xml.dist –verbose'”,
    “wp-env”: “wp-env”
  },
  “devDependencies”: {
    “@wordpress/env”: “^4.9.0”
  }
}

Configure wp-env

In plugin’s root folder create .wp-env.json file, add the following code.

You can change the ports according to your system’s availability of ports

{
  “core”: null,
  “phpVersion”: “7.4”,
  “plugins”: [“.”],
“themes”: [“../../themes/yourthemedirectory/”],
  “port”: 5888,
  “env”: {
    “tests”: {
      “port”: 5889
    }
  }
}

For further details about wp-env config please visit:
https://www.npmjs.com/package/@wordpress/env

Bootstrap file

We need to define a bootstrap file which loads the required files and functions

  • Create tests/php/unit directory
  • Create bootstrap.php in tests/php directory
  • Add the follow code.
<?php
/**
* PHPUnit bootstrap file
*
* @package features-plugin-v2
*/

define( ‘TESTS_PLUGIN_DIR’, dirname( __FILE__, 2 ) );
define( ‘WP_TESTS_PHPUNIT_POLYFILLS_PATH’, dirname( TESTS_PLUGIN_DIR ) . ‘/vendor/yoast/phpunit-polyfills’ );

// Determine correct location for plugins directory to use.
define( ‘WP_PLUGIN_DIR’, dirname( dirname( TESTS_PLUGIN_DIR ) ) );

define( ‘WP_PHPUNIT__DIR’, dirname( TESTS_PLUGIN_DIR ) . ‘/vendor/wp-phpunit/wp-phpunit/’ );

// Load Composer dependencies if applicable.
if ( file_exists( dirname( TESTS_PLUGIN_DIR ) . ‘/vendor/autoload.php’ ) ) {
require_once dirname( TESTS_PLUGIN_DIR ) . ‘/vendor/autoload.php’;
}

// Detect where to load the WordPress tests environment from.

$_test_root = WP_PHPUNIT__DIR;

require_once $_test_root . ‘/includes/functions.php’;

/**
* Load plugin in test env.
*
* @return void
*/
function features_plugin_unit_test_load_plugin_file() {
require_once dirname( TESTS_PLUGIN_DIR ) . ‘/you-plugin-init-file.php’;
}

tests_add_filter( ‘muplugins_loaded’, ‘features_plugin_unit_test_load_plugin_file’ );

require $_test_root . ‘/includes/bootstrap.php’;

Configure tests using phpunit.xml.dist

In the plugin’s root directory create phpunit.xml.dist and add the following configuration:

<phpunit
bootstrap=”tests/php/bootstrap.php”
backupGlobals=”false”
colors=”true”
convertErrorsToExceptions=”true”
convertNoticesToExceptions=”true”
convertWarningsToExceptions=”true”
>
<testsuites>
<testsuite name=”unittest”>
<directory suffix=”-test.php”>./tests/php/unit</directory>
</testsuite>
</testsuites>

</phpunit>

Note:
For Mac users, you need to add the below <php> tag element inside <phpunit> to run.

    <php>
        <env name=”WP_PHPUNIT__TESTS_CONFIG” value=”/wordpress-phpunit/wp-tests-config.php”/>
    </php>
</phpunit>

Running the tests

After adding all the files, it’s time to run the tests. You can add tests code in ./tests/php/unit folder.

The file structure / hierarchy can reflect your plugin’s source structure / hierarchy with *-test.php appended.

To start running tests:

  • Step 1: Start wp-env by using npm run wp-env start
    • This will create all the docker containers required
  • Step 2: Run npm run test:php
  • This will run all the tests which are in the tests/php/unit folder and that’s it. Your WP PHPUnit testing setup is ready to roll.

Output:

Previous Lesson
Back to Course
Next Lesson