Some time between when we started using it and this week, it would always fail to execute every time on my local machine but not on the machine to which we were deploying our code.
And no, it wasn’t because there were incorrect directives or comments in the unit tests and it wasn’t because PHPUnit was misconfigured (it was executing all of the tests and reporting them as expected).
So what gives?
When CloverCoverage Fails
The TL;DR version of this:
You need to have Xdebug properly installed because CloverCoverage requires a driver – that is, Xdebug – to execute properly. The problem is that if you’re using Homebrew, you can’t install it like we could at one time.
The remainder of this post will walk you through installing Xdebug, configuring it properly within your PHP configuration, setting up your PHPUnit configuration to properly, and then verifying it all checks out so the next time you run GrumPHP, you should get all green check marks.
And, as an added bonus, next time you run PHPUnit, you should get a nice looking report to go along with that. Here’s what you need to do.
First, note this is predicated on the idea that you’re:
- using Homebrew,
- have PHPUnit installed,
- have PHP 7.1 installed (I’m using PHP 7.1.19 at the time of writing this post),
- do not have Clover executing properly.
To verify a few things, run the following command in the terminal:
Make sure you’re running at least PHPUnit 7.1.4.
Next, check your PHP version:
And make sure you’re running at least PHP 7.1.19 (your output make not look the exactly like mine especially as it relates to Xdebug, but that’s the point of this point).
At this point, we’re ready to install Xdebug and begin making the necessary configuration changes.
1. Install Xdebug
The reason we have to install Xdebug differently than before is that it’s no longer supported by Homebrew. No worries though, as it’s just as easy to install via Pecl.
To install it, enter the following command in your terminal:
You should then see a message that it’s been installed and that the extension has been added to your PHP configuration file. In my experience, Pecl does not get the latter step correct.
2. Locate the Xdebug Binary on Disk
To address this, we need to:
- locate the full path of the Xdebug extension,
- place the fully qualified path to the extension in our PHP configuration file
To find the paths in which Xdebug may reside, use the following command:
You may get several paths returned (ideally, though, you should only get one). If you get more than one, look for the one installed in the path that contains the Pecl directory. It will likely look something like this:
Once you get a listing of all the places Xdebug.so is installed, copy the path of the file so that we can configure PHP to reference it and use it properly.
3. Update PHP’s Configuration
Next, we need to update PHP’s configuration. Doing this is easy as we simply need to add a single line to the PHP.ini file. Of course, if you have multiple versions of PHP running, then making sure you add this to the proper configuration file will depend on the version of PHP you’re running.
If you have multiple versions of PHP running on your machine, then you’re going to have multiple versions of the PHP configuration file. If you have a single version installed, then you’re going to have a single php.ini file.
This is typically located in /usr/local/etc/php/7.1/ as php.ini if you’re using PHP 7.1 but you’re location may be slightly different. But the follow step remains the same.
Once you’ve done this, make sure you add the following line to the php.ini file. This can be in any place in the file, really, but remember that you need to include the fully qualified path to Xdebug.so. So the file should include this line:
From there, everything should work. You can verify this by running:
And then you should see the following message:
PHP 7.1.19 (cli) (built: Jun 25 2018 10:42:21) ( NTS )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.1.0, Copyright (c) 1998-2018 Zend Technologies
with Xdebug v2.6.0, Copyright (c) 2002-2018, by Derick Rethans
with Zend OPcache v7.1.19, Copyright (c) 1999-2018, by Zend Technologies
Note the fourth line that includes a note about Xdebug. If you see this, then you’re good to go.
4. Configuring PHPUnit
At this point, the last thing that you need to do is make sure that your phpunit.xml file is configured properly. Here’s a simple example of what mine looks like (this includes support for Clover, too):
Next, you can manually run PHPUnit and see a nice output of code coverage.
Or your can run GrumPHP to see the solid green checkmark (assuming your tests are within the range you’ve defined in grump.yml).
The Final Result
Though it may seem like a lot of steps (and I suppose it is), it doesn’t take long to get this setup and running properly. Hopefully, the above walkthrough will save you a bit of time when working with PHP, PHPUnit, and so on when CloverCoverage fails (and succeeds simultaneously during continuous deployment).