Setting up WordPress tests with CircleCI and WP-CLI

CircleCI is a continuous integration platform that can be used to automatically build, test, and deploy software. It’s relatively easy to set up with any existing GitHub or Bitbucket project.

Setting up tests

WP-CLI includes a handy command for setting up WordPress tests for a plugin or theme using different CI services. To set up the tests for CircleCI, you can use either wp scaffold plugin-tests --ci=circle or wp scaffold theme-tests --ci=cirlce.

This will add several things to your project:

  • circle.yml – The configuration for CircleCI
  • phpunit.xml.dist – A configuration file for PHPUnit
  • A ‘tests’ folder containing:
  • bootstrap.php – A PHPUnit bootstrapping file that loads the WordPress tests along with the plugin or theme being tested.
  • test-sample.php – a sample PHPUnit Test class extending the WP_UnitTestCase class.
  • A ‘bin’ folder that contains the script for setting up the WordPress test environment, if you don’t already have one set up. Note that VVV is preconfigured to use the main development test environment.

With these files in place, you can now log into CircleCI and add the project, which will automatically set up a build next time you push a commit to your remote repo in GitHub or BitBucket.

Configuring CircleCI

CircleCI sets up builds in several configurable phases. Here’s what the default configuration from WP-CLI looks like:

 version: 5.6.22
 PATH: $HOME/.composer/vendor/bin:$PATH

 - sudo apt-get update; sudo apt-get install subversion

 - bash bin/ wordpress_test ubuntu '' latest
 - |
 composer global require wp-coding-standards/wpcs
 phpcs --config-set installed_paths $HOME/.composer/vendor/wp-coding-standards/wpcs
 - phpcs --standard=phpcs.ruleset.xml $(find . -name '*.php')
 - phpunit

For our purposes, we’re going to look at three phases: machine, dependencies, and test. Each phase has three event you  into:

  • pre – commands to run before this phase.
  • override – commands to run instead of the default commands.
  • post – commands to run after your this phase has finished.

First, the machine phase configures details so you can do things like changing the PHP version to match your production environment and set up environment variables.

The dependencies phase install all dependencies for the project. It loads dependencies from popular dependency configuration files in your project, like package.json, composer.json, etc.

In the default WP-CLI setup, the build installs subversion before loading project dependencies so it can checkout the WordPress test suite using svn during the test phase of the build.

In the test phase, the default setup installs the WordPress test suite using the bin/ script, installs the WordPress coding standards and registeres them with PHP Codesniffer. Once everything is set up, the test phase will run the codesniffer checks with phpcs and will then run your unit tests with phpunit.

With all this in place, you can now add additional tests or configuration steps and get near instant feedback if a code change would introduce any problems to your codebase.