Answers.Body: <p>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 <em>slightly</em> different -- and in six months one of those pieces will have changed in a way which breaks it.</p>
  
  <p>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.</p>
  
  <h1>Problem 1: Running PHPUnit generally (most PHP projects)</h1>
  
  <p>The idealized workflow for PHPUnit can be imagined as something like this:</p>
  
  <pre><code>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
  </code></pre>
  
  <p>Step #1-2 can be accomplished in a few ways -- e.g. download from <code>phpunit.de</code> or download <a href="https://github.com/civicrm/civicrm-buildkit/" rel="nofollow noreferrer">civicrm-buildkit</a> or run <code>apt-get install phpunit</code> or somesuch. Whatever the approach, take care to note the precise name of the executable (e.g. <code>phpunit</code> or <code>phpunit4</code> or <code>phpunit.phar</code>).</p>
  
  <p>In step #5, you call this executable, and it reads a configuration file from your project (<code>phpunit.xml.dist</code>). By default, it runs all tests in your project. However, you can run a specific test-file or test-folder, e.g.</p>
  
  <pre><code>5b: phpunit4 tests/foo/MyFullTest.php
  5c: phpunit4 tests/foo/
  </code></pre>
  
  <h1>Problem 2: Running PHPUnit with the CiviCRM test cases</h1>
  
  <p>To run the CiviCRM tests (v4.7+), there are a few additional requirements. These requirements are generally met automatically if you use <code>buildkit</code> and <code>civibuild</code>, but it may help to describe them anyway:</p>
  
  <ul>
  <li>You must have the command <a href="https://github.com/civicrm/cv" rel="nofollow noreferrer"><code>cv</code></a> installed.</li>
  <li>You must have a working CiviCRM installation.</li>
  <li>You must have an extra, headless database defined in <code>TEST_DB_DSN</code>. (To view/edit this option, use <code>cv vars:show</code> and <code>cv vars:fill</code>.)</li>
  <li>You cannot run all tests by default. Always specify a particular test-file or test-folder (e.g. <code>phpunit4 tests/phpunit/api</code>).</li>
  <li>You may need to set the environment variable <code>CIVICRM_UF</code>. For some tests (eg <code>E2E</code> and <code>WebTest</code>), this can be blank. For other tests (e.g. <code>api</code> or <code>CRM</code> or <code>Civi</code>), set <code>CIVICRM_UF=UnitTests</code>.</li>
  </ul>
  
  <p>Assuming these requirements are met, you can invoke the "E2E" tests using a conventional PHPUnit command:</p>
  
  <pre><code>phpunit4 tests/phpunit/E2E/AllTests.php
  </code></pre>
  
  <p>To run all the "CRM" tests, you would execute:</p>
  
  <pre><code>export CIVICRM_UF=UnitTests 
  phpunit4 tests/phpunit/CRM/AllTests.php
  </code></pre>
  
  <p>I suggest that you get this working before trying anything inside an IDE.</p>
  
  <p>This page may also be useful: <a href="https://github.com/civicrm/civicrm-core/blob/master/tests/README.md" rel="nofollow noreferrer">https://github.com/civicrm/civicrm-core/blob/master/tests/README.md</a></p>
  
  <h1>Problem 3: Running PHPUnit with an IDE+XDebug</h1>
  
  <p>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 <a href="http://blog.doh.ms/2011/05/13/debugging-phpunit-tests-in-netbeans-with-xdebug/" rel="nofollow noreferrer">this</a> for Netbeans, or <a href="https://www.jetbrains.com/help/phpstorm/2016.2/configuring-xdebug.html" rel="nofollow noreferrer">this</a> and <a href="https://www.jetbrains.com/help/phpstorm/2016.2/run-debug-configuration-phpunit.html" rel="nofollow noreferrer">this</a> for PHPStorm. </p>
  
  <h1>Bring it together</h1>
  
  <p>Whatever instructions are provided for the IDE, keep an eye out for how to set these additional configuration options for Civi:</p>
  
  <ul>
  <li>Specify where <code>phpunit</code> lives (e.g. <code>/usr/local/bin/phpunit.phar</code> or <code>/home/myuser/buildkit/bin/phpunit4</code>)</li>
  <li>Specify the working-directory as the CiviCRM folder (e.g. <code>/var/www/drupal/sites/all/modules/civicrm</code>).</li>
  <li>Specify the PHPUnit configuration file as CiviCRM's <code>phpunit.xml.dist</code> (e.g. <code>/var/www/drupal/sites/all/modules/civicrm/phpunit.xml.dist</code>)</li>
  <li>Specify the environment variable <code>CIVICRM_UF=UnitTests</code>.</li>
  </ul>
  
  <p>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.</p>
  
  <ul>
  <li><a href="https://wiki.civicrm.org/confluence/display/CRMDOC/Tests+in+phpstorm" rel="nofollow noreferrer">https://wiki.civicrm.org/confluence/display/CRMDOC/Tests+in+phpstorm</a></li>
  <li><a href="https://civicrm.stackexchange.com/questions/16489/how-do-i-run-php-unit-tests-w-xdebug-from-within-phpstorm-on-mac">How do I run PHP Unit Tests w/ XDEBUG from within PHPStorm [on Mac]?</a></li>
  </ul>
  
  <h1>Variation: Extension Test Suites</h1>
  
  <p>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 <code>phpunit.xml.dist</code> and its own <code>bootstrap.php</code> file. Configure your IDE to use those resources, e.g.</p>
  
  <ul>
  <li>Specify where <code>phpunit</code> lives (e.g. <code>/usr/local/bin/phpunit.phar</code> or <code>/home/myuser/buildkit/bin/phpunit4</code>)</li>
  <li>Specify the working-directory as the extension's folder (e.g. <code>/var/www/drupal/sites/default/civicrm/ext/org.example.mymod</code>).</li>
  <li>Specify the PHPUnit configuration file as the extension's <code>phpunit.xml.dist</code> (e.g. <code>/var/www/drupal/sites/default/civicrm/ext/org.example.mymod/phpunit.xml.dist</code>)</li>
  <li>Specify the environment variable <code>CIVICRM_UF=UnitTests</code>.</li>
  </ul>
  
  <h1>Legacy: <code>tools/scripts/phpunit</code></h1>
  
  <p>CiviCRM v4.7 works with a standard executable of phpunit 4.x. However, in older versions, you had to use an alternative executable, <code>tools/scripts/phpunit</code>. Unfortunately, this executable required a different syntax which made it incompatible with IDE's and other tools. You can still use the <code>tools/scripts/phpunit</code> syntax in v4.7, but I consider it a distraction.</p>
  
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2016-11-18T18:37:18.810Z
Answers.Text: Thank you! I had PHPUnit running on Civi tests for a long time, but using the legacy wrapper command.  I was unaware of the README.md you linked to here; with that, I was able to get PHPUnit running without the legacy wrapper, which is what stymied me.  I don't have this working with Netbeans yet, but now that I've bypassed the wrapper, we've reduced this to an already-solved problem, so I'll mark as accepted.  Thanks again!
Answers.UserDisplayName: Jon G - Megaphone Tech
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2017-01-02T17:26:09.873Z
Answers.Text: I've added a link to a complete set of instructions for PHPStorm: http://civicrm.stackexchange.com/questions/16489/how-do-i-run-php-unit-tests-w-xdebug-from-within-phpstorm-on-mac
Answers.UserDisplayName: KarinG - Semper IT
Answers.ContentLicense: CC BY-SA 3.0
Answers.CreationDate: 2016-11-18T05:39:32.667Z
Answers.LastActivityDate: 2017-01-02T19:26:18.573Z
Answers.LastEditDate: 2017-04-13T12:53:13.167Z
Answers.UserDisplayName: Tim Otten
Body: <p>Ideally in conjunction with an IDE (I use Netbeans, but will fire up pretty much anything that gets this to work).</p>
  
Tags: <developer><debugging><unit-testing><xdebug>
Title: How can I use Xdebug with CiviCRM unit tests?
ThreadText: # How can I use Xdebug with CiviCRM unit tests?
  
  (Asked by: username_0 on 2016-11-18)
  
  Ideally in conjunction with an IDE (I use Netbeans, but will fire up pretty much anything that gets this to work).
  
  **Tags:** developer, debugging, unit-testing, xdebug
  
  
  ---
  
  ## 1 answers
  
  ### Answer by username_1 on 2016-11-18. Score: 9 | Accepted answer
  
  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.
  
  > **Comments:**
  > **username_0**: Thank you! I had PHPUnit running on Civi tests for a long time, but using the legacy wrapper command.  I was unaware of the README.md you linked to here; with that, I was able to get PHPUnit running without the legacy wrapper, which is what stymied me.  I don't have this working with Netbeans yet, but now that I've bypassed the wrapper, we've reduced this to an already-solved problem, so I'll mark as accepted.  Thanks again!  
  > **username_2**: I've added a link to a complete set of instructions for PHPStorm: http://civicrm.stackexchange.com/questions/16489/how-do-i-run-php-unit-tests-w-xdebug-from-within-phpstorm-on-mac  
  
  ---
  
  