• Debugging PHPUnit Tests in NetBeans with XDebug

    by  • May 13, 2011 • PHP, Tips and Tricks, Tools • 4 Comments

    Every now and then you run into this weird situation in your code, where something that was supposed to zig is now zagging and it makes no sense whatsoever. For me this ends up happening in my unit tests since i’m not running everything in the browser everytime and since my tests usually run more scenarios then a regular browser run, that’s where the weird stuff happens.

    So your obvious way out is to add a few var_dumps into the code and try to understand what is happening, if you are doing that: STOP!

    Drop that mouse and step away from your keyboard, you should be debugging not adding code to the mix. So debugging in a browser is a piece of cake in most IDEs like NetBeans and Zend Studio and so forth, but debugging your tests that are running on the command line take a few more cards up your sleeve. So this is how i configured my NetBeans IDE and my PHPUnit tests to communicate and let me debug what happens inside that crazy world.

    Configure your NetBeans Debugging configuration

    This is very straight forward, go to Preferences > PHP and set the debug settings, namely the port and a session id. For example: port 9000 and Session ID netbeans-xdebug.

    Tell Xdebug what you want it to do

    This is done by adding a few settings in you php.ini or if you use additional ini files, I recommend you create a xdebug.ini. You need to configure a few things here, we want xdebug to have remote debugging always enabled and we want to configure the port and ide keys we used in netbeans as well as configuring the output to be “dbgp”. This is how it will look in you ini:

    xdebug.remote_enable= On

    Make PHPUnit send stuff to NetBeans

    So this is enough for you to do URL based debugging, but we want to debug our unit tests to pick up on those weird bugs with a easy to repeat script to lock down on it. For this to work you need to export a xdebug config variable in your local environment, so that XDebug kicks off the debugging based on this command line script. You will need to set XDEBUG_CONFIG to “idekey=netbeans-xdebug”, but setting it everytime is a nuisance, so my approach is to create a phpunit-debug file that can do this for me and allows me to kick off debugging by simply changing the executable. This is the content of this file:

    export XDEBUG_CONFIG="idekey=netbeans-xdebug";
    phpunit $@

    Make NetBeans start a debug session and not open a browser window

    One last thing is needed for things to run smoothly. When you click on debug in Netbeans the usual process is for it to open up a browser window and debug from there, but we don’t want that, so we need to tell it to not open a browser. This is done by accessing File > Project Properties > Run Configuration and clicking on the “Advanced” button, here you can select “Do no open a browser” and you are set.

    Running Debugging

    To start a debugging session you will need to follow these steps:

    1. Click on “Debug Project” button. Now Netbeans will start waiting for a connection.
    2. Go to command line and run phpunit-debug. Now debugging starts, if you selected “Stop on first line” phpunit file will be opened on your IDE, click play and you are off.

    There you go. Now you are all set to debug your tests and understand better what is triggering that failure deep down inside your suite.


    Rafael Dohms is an experienced PHP Developer, Evangelist, Speaker and Contributor. During his years of experience he has become an active member of the community and founded 3 User Groups. He moved to the Netherlands to integrate the WEBclusive team and share his passion for code quality and innovation in the Crowd funding world. In his spare time he also helps manage the AmsterdamPHP User Group, amongst other projects.


    4 Responses to Debugging PHPUnit Tests in NetBeans with XDebug

    1. May 13, 2011 at 11:51

      first! o/

    2. Pingback: Debugging PHPUnit Tests in NetBeans with XDebug | Dacoders Pvt. Ltd.

    3. Pingback: Debugging PHPUnit Tests in NetBeans with XDebug | PHP Frameworks

    4. May 19, 2011 at 13:07

      great thing, do you happen to know a way to do the same in phpstorm?

      • Rafael Dohms
        July 2, 2011 at 9:35

        It probably is but i have not had a chance to play with PHPstorm. But the steps should be very similar.

    5. Alberto
      June 6, 2011 at 21:53

      great post.

    6. July 18, 2011 at 10:24

      Great post – thanks.

      Also found out about path mapping – it's on the same dialog as the debug URL. Not seen that screen before!

    7. Pingback: Debugging Zend Framework unit tests with Xdebug and NetBeans ~ Robert Basic

    8. Nasreddine
      January 17, 2012 at 13:55

      How can I execute phpunit-xdebug file on windows machine ?

      • Ron
        August 30, 2012 at 21:36

        REM Put this in a file called phpunit-xdebug.bat
        SET XDEBUG_CONFIG=idekey=netbeans-xdebug
        phpunit %1

        • Ron
          August 31, 2012 at 0:54

          Better change the last line to

          phpunit %*

          This will use all the command line arguments instead of just the first one.

    9. ingo
      April 16, 2012 at 21:44

      hi, thanks for your post!
      i tried to get this working but failed. another alternative that worked for me is described here: https://blogs.oracle.com/netbeansphp/entry/phpuni

    10. Ron
      September 3, 2012 at 1:39

      Hi Rafael,
      I followed your instructions and succeeded in attaching NetBeans to a PHPUnit command-line session.
      All the test cases are executed correctly by PHPUnit. However, the debugger doesn't seem to hit any of the breakpoints I set in the test cases. It does, however, hit the breakpoints that I set in the PHPUnit framework code.
      I managed to drill down to the following stack trace. How do I get NetBeans to show me the code instead of this URL on the top frame? Does it have something to do with the options in the Advanced Web Configuration dialog (Path Mapping and/or Debugger Proxy)?

    11. Ranjan
      November 19, 2012 at 10:38

      xdebug is not working properly.
      It's working fine if open in new window. If i set it not open in new window. it is not working.

      Please help me out.

    12. August 6, 2013 at 16:07

      The goal of unit testing is to isolate each part of the program and show that the individual parts are correct. A unit test provides a strict, written contract that the piece of code must satisfy.

    13. Pingback: Launch the PHPStorm Remote Debugger from a PHPUnit Test – Stephen Rhoades

    14. Matthias
      December 19, 2013 at 18:56

      Very good post!

      One thing to mention, that took me some time to debug: Do not use strict mode in phpunit, because stopping at a breakpoint will trigger a timeout.

    15. anver
      January 16, 2014 at 20:49

      nice post, I tried this on windows 7 the xdebug session on netbeans says running after I run the test on phpunit but its just not hitting the breakpoint for some reason. I think the need to change this to make it
      compatible with windows.

      export XDEBUG_CONFIG="idekey=netbeans-xdebug";
      phpunit $@

      Any help with windows is greatly appreciated.


      • Ron
        January 17, 2014 at 1:33

        See my reply earlier in this thread. But actually there's no need to do anything from the command line. If you configure your NetBeans project correctly, you can debug any unit test directly from the IDE. Just right-click the *Test.php file and choose Debug.

    16. February 6, 2014 at 2:49

      Thanks for the post, absolute live saver!

      I'm running on Fedora with netbeans and phpunit locally with in memory sqlite db. The only change I had to make to get this working was setting the following script as the custom script for phpunit inside netbeans:

    17. Winterfell
      April 22, 2014 at 16:47

      Thank u !
      The option 'Do not open web browser' isn't binding.

    Leave a Reply