I recently decided that I wanted to start contributing a little bit of time each week to the WordPress project. Since I’ve already written a couple of extensions and administrate quite a few WordPress sites I figure it’s time to start giving back to the project.
The Core Contributor handbook outlines quite a bit of things you need to know in order to get started but there are always things that are linked to that start to fall out of date as time marches forward.
One step that I recently wanted to take was getting set up to perform unit tests. As a developer I’ll be the first to admit guilt in not creating these for projects but for big projects like WordPress with distributed development and thousands of tickets it’s imperative that we have unit tests.
In this guide I will cover how to setup a complete WordPress development environment on Windows. I’ll be covering everything from server (localhost) to SVN to Composer to PHPUnit. We’ve got our work cut out for us so let’s get started.
Personally I find the instruction on the “First Steps” page in the handbook a bit lacking in detail, plus the complete setup is spread across several pages depending on your setup. This guide assumes that you want to install on Windows and don’t want to run a virtual machine.
Step 1 – The Environment
“The environment is everything that isn’t me.”-Albert Einstein
My personal favorite flavor of local server for window sin XAMPP. The wonderful people over at apachefriends.org have put together a solid and stable release that works well in modern Window systems. You can use a different one if you choose but I find this one the most user friendly.
Step 2 – The Checkout
“Check it out now, the funk soul brother”
First up is the discussion about SVN vs. Git. I LOVE GIT. Be that as it is and the fact that WordPress now supports both… your life will be easier if you use SVN. WordPress is well vested in SVN and deviating from that standard isn’t recommended. If you insist on using Git remember in the future if get commit privileges to the development trunk someday your commits to Git will not affect the version of WordPress that gets published. So in short you’ll end up switching to SVN eventually anyway.
Using SVN on Windows means it’s time install TortoiseSVN (if you don’t already have it). I highly recommend it and it’s is pretty much the standard when your using Windows (and don’t want to mess with command line).
Once you have it installed go to your C:/xampp/htdocs folder. Create a new folder called wordpress-svn. Right click the folder and select SVN Checkout. Punch in https://develop.svn.wordpress.org/trunk/ in the “URL of repository:” and click OK. This will download the “bleeding edge” version of WordPress.
Remember that you should do update each day you plan on working on WordPress. You can update your version to the “HEAD” by simply right clicking the folder and selecting SVN Update.
Step 3 – The Install
WordPress started in 2003 with a single bit of code to enhance the typography of everyday writing and with fewer users than you can count on your fingers and toes. Since then it has grown to be the largest self-hosted blogging tool in the world, used on millions of sites and seen by tens of millions of people every day.
Now if your using standard setting you should be able to go to http://localhost/wordpress-svn/src/ and start the install process (Make sure you have Apache and MySQL running).
WordPress will step you through the install process. Select your language, then provide your database information. If you followed along with me and left everything else default your credentials will be:
- Database Name: wordpress-svn
- Username: root
- Password: blank (literally leave the field empty)
- Database Host: localhost (default)
- Table Prefix: wp_ (default)
Run the install then login… DONE. (I love how easy this system is to install)
Step 4 – The Test
The test of a first-rate intelligence is the ability to hold two opposed ideas in mind at the same time and still retain the ability to function.-F. Scott Fitzgerald
In the handbook under “automated testing” (which should really be labeled unit testing for clarity) they point to this article written by Alex Mills in 2012. While it’s a great article to help you get started it turns out that PHPUnit has recently decided to stop supporting the installation method he used in the near future.
Since PHPUnit is no longer supporting PEAR for installation I recommend using Composer to handle PHPUnit as a dependency. They indicate on their installation page the “easiest method” is to use a PHAR archive to do the installation, but since we are targeting Windows for our environment and not a Linux distro it’s not really the easiest.
Here is the method I used to get started:
- Go get Composer (if you don’t have it already)
- I used the installer and installed the Shell Menus
- Restart your computer. (or all explorer and CMD.exe instances)
- Create your composer.json file in your C:/xampp/htdocs/wordpress-svn folder
- Here is what I put in my composer file:
- Most of this isn’t necessary but it’s nice to have. the only line you really need is
- Now launch CMD.exe as an administrator
- Navigate to your wordpress directory
- Then run the
If you get an error saying something like: ‘php’ is not recognized as an internal or external command… it means that you need to add php to your path. To do that:
- Click Start -> Hover over “My Computer” -> Right Click and select Properties
- Select Advanced system settings from the left column
- On the Advanced Tab click the Environment Variables… button
- In the “System variables section scroll down and select the Path variable and click Edit
- If you are using the default install add
C:\xampp\php;to the end of the value string (No Spaces after the semi-colon!)
- Click OK until your back out and restart CMD.exe then try to run
Now the PHPUnit is installed and ready to go we need to connect to our test database. First rename the wp-tests-config-sample.php file in your wordpress-svn directory to wp-tests-config.php. Open it up and make changes to the following lines:
define( 'DB_NAME', 'wordpress-tests' );
define( 'DB_USER', 'root' );
define( 'DB_PASSWORD', '' );
define( 'DB_HOST', 'localhost' );
define( 'DB_CHARSET', 'utf8' );
define( 'DB_COLLATE', '' );
$table_prefix = 'wptests_'; // Only numbers, letters, and underscores please!
define( 'WP_TESTS_DOMAIN', 'localhost' );
define( 'WP_TESTS_EMAIL', 'email@example.com' );
Once you’ve saved your changes go back to the CMD and type in
phpunit (make sure your still in your wordpress-svn directory). This will run the battery of unit tests already written.
That’s it you are now ready to start making WordPress more awesome. At this point I would suggest referencing the handbook and checking out the various ways you can contribute.