Testing is important. In order to keep all of your php code working, you will need to test. It might seem like a hassle to write a test for every little function you write, but it does pay off if you care about continuity of your code.

This walkthrough will describe how you can achieve this using Eclipse as your IDE and the interface provided by the Makegood plugin.

We need quite a lot of things to get us going:

1. XAMPP server including MySQL
2. PHP (version greater than 5.2) included in XAMPP
3. Composer to install PHPUnit
4. PHPUnit
5. WordPress test package
6. Eclipse IDE
7. “Makegood” plugin for Eclipse
8. “ANSI Escape in Console” plugin for Eclipse
9. Your WordPress plugin or theme
10. Test classes for your WordPress plugin or theme

So let’s wait no longer and start.

Get a local server running php

Php is typically installed when you install a server package. If you do not have a server, you can easily install one. XAMPP is used in the examples below. Just make sure your local server has php (version >= 5.3) installed. Also make sure the xdebug and mysqli extensions are enabled for php.

Download and install Eclipse

The IDE we chose for this walkthrough is Eclipse. If you are into php development, the best Eclipse package is the one that includes php tools: the Eclipse IDE for PHP Developers.

1. Head to the Eclipse Packages Download page. There you will find the Eclipse IDE for PHP Developers for your platform (32bit | 64bit).
2. Download the package and unzip the contents of the eclipse root folder to a folder on your hard drive, e.g. C:\Eclipse_for_php_developers

Create a new project

We need to create a new project in Eclipse. For that we need a folder that contains our project’s files. You will want to test your site on your local server (by clicking in the browser). The project files therefore need to be in the htdocs folder from which your local server serves it’s files. So create a folder my-wp-test:

C:/xampp/htdocs/my-wp-test

We also need to have an empty workspace folder where Eclipse can keep all it’s data about your project. Create a new folder on your hard drive for your Eclipse workspace. This is where Eclipse will store some info about your environment:

C:\eclipse_workspace

Click the eclipse.exe in the root of the folder you just unzipped. (For convenience: you can also create a shortcode to the file and then drag that into the Windows Taskbar, so you can start it from there.) When asked for the workspace directory, give it the path to the C:\eclipse_workspace folder.

In Eclipse, click File->New->Php Project. Give it the name wordpress_testing and choose “create project at exisitng location”.  Then, enter the path of the folder where your server files are: C:/xampp/htdocs/my-wp-test

Create two databases

Create two MySQL databases, using phpadmin or whatever means.

1. The first, wp_normal, is for the regular installation that you can use to test real live data. You can also use an existing WordPress database.
2. The second, wp_tests, is for storing test data. This will be emptied before every test run, so make sure it is a new, empty, database.

Get the WordPress Test package (including WordPress)

1. Open the command line and check out the WordPress test package. It will be downloaded to the folder wordpress-develop folder within the folder from which you run the command:
2. svn co https://develop.svn.wordpress.org/trunk/ wordpress-develop
3. Now, inside the new wordpress-develop folder you will find a folder src. Copy the contents of that folder to the project folder C:\xampp\htdocs\my-wp-test. (The src folder simply contains a copy of wordpress, so this is essentially the same as installing WordPress).
4. Then, copy the tests folder from the wordpress-develop directory to C:\xampp\htdocs\my-wp-test.
5. Also, copy the fie wp-tests-config-sample.php file from the wordpress-develop folder to the my-wp-test folder. Rename the file to wp-tests-config.php, open the file and add the details of the database called wp_tests.

Setup WordPress, install plugin/theme

1. In the source folder you will find the wp-config-sample.php file. Fill in the details of the MySQL database wp_normal (or your existing database) and save the file as wp-config.php.
2. Setup WordPress by navigating to http://localhost/my-wp-test/wp-admin/wp-install.php.
3. Log into WordPress and install the theme or plugin that you want to test. Then open the file browser or command line and add a folder tests to the root of your plugin/theme folder, like:  C:\xampp\htdocs\my-wp-test\wp-content\plugins\my-plugin\tests

Get started with PHPUnit

You can download phpunit and its API using Composer. Composer will install a copy of PHPUnit for your project, including any dependencies.

1. Download composer from the Download Composer page and install it anywhere you like.
2. Make sure the folder in which the composer.exe file lives is added to the PATH system variable.
3. Run the command composer --version in any folder from the command line and you should see the composer version, e.g.: Composer version 1.4.2 2017-05-17 08:17:52

Create the composer.json file

Before we can actually use composer, we need to create a file that tells composer what to do.

In the C:\xampp\htdocs\my-wp-test folder Create a new file called composer.json. In it, paste the following composer instructions:

{
"require-dev" : {
"phpunit/phpunit" : "5.6.8"
}
}

Note that 5.6.8 is the latest version I got running. Later versions get me the following notice:

Notice: Undefined index: loadedExtensions in C:\xampp\htdocs\wp\vendor\phpunit\phpunit\src\TextUI\TestRunner.php on line 290

Now, open the command line and navigate to the C:\xampp\htdocs\my-wp-test folder. Type

composer install

Now you will have phpunit available in the C:\xampp\htdocs\my-wp-test\vendor folder!

Prepare PHPUnit/WP_Unit

To load WordPress test functionality and use the WP_Unit_TestCase methods, you will have tell PHPUnit to load WordPress. This can be done using a bootstrap file that bootstraps the WordPress bootstrap, if you follow me. Place this in the root of your project folder and call it final-bootstrap: C:\xampp\htdocs\my-wp-test\final-bootstrap.php. Here you can add or remove folders and themes before WordPress bootstraps.

<?php

/* The path to the WordPress tests folder. */
define( ‘MY_TESTS_DIR’, ‘C:/xampp/htdocs/wp/wordpress-develop/tests/phpunit/’ );
/* The path to the main file of the plugin to test. */
define( ‘TESTING_PLUGIN_DIR’, ‘C:/xampp/htdocs/wp/wordpress-develop/src/wp-content/plugins/google-maps-meets-twitter/’ );

define( ‘TEST_PLUGIN_FILE’, TESTING_PLUGIN_DIR . ‘google-maps-meets-twitter.php’ );

/* Load plugin */
require_once MY_TESTS_DIR . ‘includes/functions.php’;
function _manually_load_plugin() {
require TEST_PLUGIN_FILE;
}
tests_add_filter( ‘muplugins_loaded’, ‘_manually_load_plugin’ );

/* Start WordPress */
require MY_TESTS_DIR . ‘includes/bootstrap.php’;

 

The PHPUnit xml

To use PHPUnit within Eclipse, using Makegood, you will need to configure it using a phpunit.xml file. You can create and empty phpunit.xml file in the c:\xampp\htdocs\my-wp-test folder. Paste into this the xml contents below.

1. Make sure that bootstrap is set to the final-bootstrap.php file in the C:\xampp\htdocs\my-wp-test\ folder.
2. Also make sure that backupGlobals is set to false.

<phpunit

backupGlobals=”false”
backupStaticAttributes=”false”
beStrictAboutTestsThatDoNotTestAnything=”true”

bootstrap=”C:/xampp/htdocs/my-wp-test/final_bootstrap.php”
cacheTokens=”false”
colors=”true”
convertErrorsToExceptions=”true”
convertNoticesToExceptions=”true”
convertWarningsToExceptions=”true”
forceCoversAnnotation=”false”
mapTestClassNameToCoveredClassName=”false”
printerClass=”PHPUnit_TextUI_ResultPrinter”
processIsolation=”false”
stopOnError=”false”
stopOnFailure=”false”
stopOnIncomplete=”false”
stopOnSkipped=”false”
testSuiteLoaderClass=”PHPUnit_Runner_StandardTestSuiteLoader”
strict=”true”

verbose=”true”>
</phpunit>

 

Install and configure Makegood

Makegood needs to know where to find PHPUnit. You should tell by creating a file. We call it makegood-preload.php. Let’s put it in the root of our project C:\xampp\htdocs\my-wp-test and paste the following in it.

Makegood is a plugin for Eclipse. With it, you can start, stop and inspect PHPUnit tests from within user interface of Eclipse.

Within Eclipse, go to Help->Eclipse Marketplace. Search for makegood. Install it.

Still in Eclipse, open menu item Window->Preferences, unfold PHP and go to PHP Executables. Click “Add”. Then click Browse to add the file C:\xampp\php\php.exe. Leave SAPI Type to CLI and click OK to close the window. Still in the PHP Executables window, select the executable you just added and click Edit. On the Debugger tab, select XDebug, leave the rest of the settings and press OK a couple of times.

Go back to the Window->Preferences. There, select Debug. Make sure the php executable you just added is selected in the CLI Settings fieldset. Uncheck “Break at First Line” and click OK.

Then click on your project wordpress-testing in the Project Explorer and from the menu choose Project->Properties. There you will find Makegood. In the General tab click “Add” to add the tests folder of your my-plugin (C:\xampp\htdocs\my-wp-test\wp-content\plugins\my-plugin\tests). Als we need to add the Preload Script we just created: C:\xampp\htdocs\my-wp-test\makegood-preload.php.

In the PHPUnit tab you should add the phpunit.xml file that we created earlier. You should be able to find it in the C:\xampp\htdocs\my-wp-test\ folder. Close the settings window.

If you don’t see a Makegood tab somewhere in the IDE, head to menu Window->Show View->Other and select Makegood.

To prevent some funny characters from showing up while examining the console output in PHPUnit, you should also use the Eclipse Marketplace to install the plugin “ANSI Escape in Console” and then restart Eclipse. If you do not install ANSI Escape in Console, you might end up with several funny characters (, [39m) in the console output where colors are supposed to be. (Setting colors to false in the phpunit.xml apparently does not have any effect, so the ANSI Escape plugin helps with this.

Create a test

You can add files containing test classes to the C:\xampp\htdocs\my-wp-test\wp-content\plugins\my-plugin\tests folder. Note that all file names have to end in TestCase.php or Test.php, so FriendsTableTest.php or FootballFieldTestCase.php are valid filenames. (To change this restriction go to Project->Properties->Makegood->General and enter a regex for the Test File Pattern.)

To point PHPUnit in the right direction, you will have to tell it which class methods are actual tests. Do this by choosing one of the following:

1. Either prefix every method name with “test”
2. Or add a comment right before every method declaration: /** @test */

The name of the test class doesn’t matter, as long as it extends WP_UnitTestCase.

Like so:

<?php

//FILE: testcoordinate_check.php
class coordinateChecking extends WP_UnitTestCase {
/** @test */
public function coordinate_should_be_converted_to_floating_point_strings()
{
$this->assertEquals(1,1);
}
public function test_coordinate_should_be_converted_to_floating_point_strings()
{
$this->assertEquals(1,1);
}
}
?>

There should be a test run as soon as you save.

In case you run into the following message:

Fatal error: Cannot use Stagehand\TestRunner\Util\String as String because 'String' is a special class name in C:\Elipse_for_php_developers\plugins\com.piece_framework.makegood.stagehandtestrunner_3.1.1.v201409021510\resources\php\vendor\piece\stagehand-testrunner\src\DependencyInjection\Transformation\Transformation.php on line 46

Change the contents of the following file:

C:\Eclipse_for_php_developers\plugins\com.piece_framework.makegood.stagehandtestrunner_3.1.1.v201409021510\resources\php\composer.json

To:

{
"require": {
"php": ">=5.3.3",
"piece/stagehand-testrunner": "4.2.0"

},
"scripts": {
"post-autoload-dump": [
"Stagehand\\TestRunner\\Composer\\Script::compile"
]
}
}