How can I use Xdebug with CiviCRM unit tests?

Question

Ideally in conjunction with an IDE (I use Netbeans, but will fire up pretty much anything that gets this to work).

Answer 1

Xdebug configuration is a somewhat temperamental issue -- the details depend on the IDE, the PHP build, host OS, target application, test suite, etc. Providing a good answer to this is tricky -- e.g. I could describe my configuration (Mac OS X, PHPStorm 2016.2, MAMP 3.4, PHP 5.4, buildkit/dmaster), but the odds are that most people reading it will need something slightly different -- and in six months one of those pieces will have changed in a way which breaks it.

Rather than a comprehensive step-by-step guide, we might look at a few distinct problems. After you've looked at these separately, it's easier to tackle them together.

Problem 1: Running PHPUnit generally (most PHP projects)

The idealized workflow for PHPUnit can be imagined as something like this:

1: wget https://phar.phpunit.de/phpunit-old.phar -O /usr/local/bin/phpunit4
2: chmod +x /usr/local/bin/phpunit4
3: git clone https://example.com/my-php-project.git
4: cd my-php-project
5: phpunit4

Step #1-2 can be accomplished in a few ways -- e.g. download from phpunit.de or download civicrm-buildkit or run apt-get install phpunit or somesuch. Whatever the approach, take care to note the precise name of the executable (e.g. phpunit or phpunit4 or phpunit.phar).

In step #5, you call this executable, and it reads a configuration file from your project (phpunit.xml.dist). By default, it runs all tests in your project. However, you can run a specific test-file or test-folder, e.g.

5b: phpunit4 tests/foo/MyFullTest.php
5c: phpunit4 tests/foo/

Problem 2: Running PHPUnit with the CiviCRM test cases

To run the CiviCRM tests (v4.7+), there are a few additional requirements. These requirements are generally met automatically if you use buildkit and civibuild, but it may help to describe them anyway:

• You must have the command cv installed.
• You must have a working CiviCRM installation.
• You must have an extra, headless database defined in TEST_DB_DSN. (To view/edit this option, use cv vars:show and cv vars:fill.)
• You cannot run all tests by default. Always specify a particular test-file or test-folder (e.g. phpunit4 tests/phpunit/api).
• You may need to set the environment variable CIVICRM_UF. For some tests (eg E2E and WebTest), this can be blank. For other tests (e.g. api or CRM or Civi), set CIVICRM_UF=UnitTests.

Assuming these requirements are met, you can invoke the "E2E" tests using a conventional PHPUnit command:

phpunit4 tests/phpunit/E2E/AllTests.php

To run all the "CRM" tests, you would execute:

export CIVICRM_UF=UnitTests 
phpunit4 tests/phpunit/CRM/AllTests.php

I suggest that you get this working before trying anything inside an IDE.

This page may also be useful: https://github.com/civicrm/civicrm-core/blob/master/tests/README.md

Problem 3: Running PHPUnit with an IDE+XDebug

This part varies widely, and I can't do it justice. I'd usually do a Google search like "phpstorm mamp xdebug phpunit" or "netbeans ubuntu xdebug phpunit" or "eclipse vagrant xdebug phpunit". For most permutations of IDE and PHP runtime, you should be able to find some guidance like this for Netbeans, or this and this for PHPStorm.

Bring it together

Whatever instructions are provided for the IDE, keep an eye out for how to set these additional configuration options for Civi:

• Specify where phpunit lives (e.g. /usr/local/bin/phpunit.phar or /home/myuser/buildkit/bin/phpunit4)
• Specify the working-directory as the CiviCRM folder (e.g. /var/www/drupal/sites/all/modules/civicrm).
• Specify the PHPUnit configuration file as CiviCRM's phpunit.xml.dist (e.g. /var/www/drupal/sites/all/modules/civicrm/phpunit.xml.dist)
• Specify the environment variable CIVICRM_UF=UnitTests.

As a demonstration, the following includes screenshots about setting those options within a specific version of PHPStorm. However, the precise windows+fields may be different in your IDE.

• https://wiki.civicrm.org/confluence/display/CRMDOC/Tests+in+phpstorm
• How do I run PHP Unit Tests w/ XDEBUG from within PHPStorm [on Mac]?

Variation: Extension Test Suites

Beginning in 2016, the recommended practice for testing extensions is to create your own test-suite inside each extension -- e.g. each extension should have its own phpunit.xml.dist and its own bootstrap.php file. Configure your IDE to use those resources, e.g.

• Specify where phpunit lives (e.g. /usr/local/bin/phpunit.phar or /home/myuser/buildkit/bin/phpunit4)
• Specify the working-directory as the extension's folder (e.g. /var/www/drupal/sites/default/civicrm/ext/org.example.mymod).
• Specify the PHPUnit configuration file as the extension's phpunit.xml.dist (e.g. /var/www/drupal/sites/default/civicrm/ext/org.example.mymod/phpunit.xml.dist)
• Specify the environment variable CIVICRM_UF=UnitTests.

Legacy: tools/scripts/phpunit

CiviCRM v4.7 works with a standard executable of phpunit 4.x. However, in older versions, you had to use an alternative executable, tools/scripts/phpunit. Unfortunately, this executable required a different syntax which made it incompatible with IDE's and other tools. You can still use the tools/scripts/phpunit syntax in v4.7, but I consider it a distraction.