I am struggling to debug PHPUnit Tests (with xdebug) in a custom D8 Module from PHPStorm or via the command line. Is it possible to do this?

I'm running an Acquia Bolt generated site on a Drupal-VM Virtual Machine running PHP7 w/ XDebug Enabled. The site is using composer.json as the dependency manager for drupal core as well as all contrib modules. This is just a project for me to test some things, so here's the github repo.

Here is my Test Class

Here's what I have tried

Command Line

I can run my tests from within an ssh session on the VM with the following command:

$ php core/scripts/run-tests.sh --url http://data.vm --color --verbose --module data_logger

I have tried to initiate the debug session from the command line with the following:

$ export XDEBUG_CONFIG="idekey=PHPSTORM remote_enable=1 remote_connect_back=0 remote_mode=req remote_port=9000"; sudo php core/scripts/run-tests.sh --url http://data.vm --color --verbose --module data_logger

$ sudo php -dxdebug.remote_enable=1 -dxdebug.remote_mode=req -dxdebug.remote_port=9000 -dxdebug.remote_host= -dxdebug.remote_connect_back=0 core/scripts/run-tests.sh --url http://data.vm --color --verbose --module data_logger

Note, I don't think I shouldn't have to specify any of the xdebug variables on the command line because they are already set but I as grasping at straws...

The tests execute, but the debugger session never seems to start within PHPStorm.

PHP Storm

PHPStorm Miserably Fails running my custom module PHPUnit Test.

PHPStorm SUCCEEDS running and debugging the Bolt included PHPUnit tests in the tests/phpunit folder.

After setting the PHPUnit settings screen to use a remote interpreter and specifying a custom autoloader to the root vendor folder /var/www/data/vendor/autoload.php

PHPStorm PHPUnit Remote Interpreter Settings

I right click and choose run/debug on one of the files, and everything works as expected. The debugger starts and we're good to go.

The command that is displayed in the console is:

sftp://[email protected]:22/usr/bin/php -dxdebug.remote_enable=1 -dxdebug.remote_mode=req -dxdebug.remote_port=9000 -dxdebug.remote_host= /home/vagrant/.phpstorm_helpers/phpunit.php --no-configuration Drupal\\Tests\\PHPUnit\\BuildTest /var/www/data/tests/phpunit/BuildTest.php

The main difference that I see is that these tests extent TestBase where as my Test extends WebTestBase and the PHPUnit tests at the root level include a phpunit.xml file which I have tried to copy and update to point to the vendor/autoload.php as well but this didn't have any effect.

What I'm confused about is why PHPStorm seems to inherently understand that the tests/phpunit/* are PHPUnit tests when I right click on those files but when I right click on my Test class file, I get the option to debug with Javascript or as a PHP Script. Why does PHPStorm not recognize my test class as a PHPUnit test?

Bottom line, how can I debug a custom module test in PHPStorm?

Additional Context:

I can verify that xdebug is running on the VM as expected:

$ php -i | grep xdebug
xdebug support => enabled
xdebug.auto_trace => Off => Off
xdebug.cli_color => 0 => 0
xdebug.collect_assignments => Off => Off
xdebug.collect_includes => On => On
xdebug.collect_params => 0 => 0
xdebug.collect_return => Off => Off
xdebug.collect_vars => Off => Off
xdebug.coverage_enable => On => On
xdebug.default_enable => On => On
xdebug.dump.COOKIE => no value => no value
xdebug.dump.ENV => no value => no value
xdebug.dump.FILES => no value => no value
xdebug.dump.GET => no value => no value
xdebug.dump.POST => no value => no value
xdebug.dump.REQUEST => no value => no value
xdebug.dump.SERVER => no value => no value
xdebug.dump.SESSION => no value => no value
xdebug.dump_globals => On => On
xdebug.dump_once => On => On
xdebug.dump_undefined => Off => Off
xdebug.extended_info => On => On
xdebug.file_link_format => no value => no value
xdebug.force_display_errors => Off => Off
xdebug.force_error_reporting => 0 => 0
xdebug.halt_level => 0 => 0
xdebug.idekey => PHPSTORM => PHPSTORM
xdebug.max_nesting_level => 256 => 256
xdebug.max_stack_frames => -1 => -1
xdebug.overload_var_dump => On => On
xdebug.profiler_aggregate => Off => Off
xdebug.profiler_append => Off => Off
xdebug.profiler_enable => Off => Off
xdebug.profiler_enable_trigger => Off => Off
xdebug.profiler_enable_trigger_value => no value => no value
xdebug.profiler_output_dir => /tmp => /tmp
xdebug.profiler_output_name => cachegrind.out.%p => cachegrind.out.%p
xdebug.remote_addr_header => no value => no value
xdebug.remote_autostart => Off => Off
xdebug.remote_connect_back => On => On
xdebug.remote_cookie_expire_time => 3600 => 3600
xdebug.remote_enable => On => On
xdebug.remote_handler => dbgp => dbgp
xdebug.remote_host => localhost => localhost
xdebug.remote_log => /tmp/xdebug.log => /tmp/xdebug.log
xdebug.remote_mode => req => req
xdebug.remote_port => 9000 => 9000
xdebug.scream => Off => Off
xdebug.show_error_trace => Off => Off
xdebug.show_exception_trace => Off => Off
xdebug.show_local_vars => Off => Off
xdebug.show_mem_delta => Off => Off
xdebug.trace_enable_trigger => Off => Off
xdebug.trace_enable_trigger_value => no value => no value
xdebug.trace_format => 0 => 0
xdebug.trace_options => 0 => 0
xdebug.trace_output_dir => /tmp => /tmp
xdebug.trace_output_name => trace.%c => trace.%c
xdebug.var_display_max_children => 128 => 128
xdebug.var_display_max_data => 512 => 512
xdebug.var_display_max_depth => 3 => 3

I can verify that my test displays and runs as expected at admin/config/development/testing.

Data Logger PHPUnit SimpleTest

enter image description here

Note: I can pause the test if I initiate the test through Drupal at /admin/config/development/testing. This is not an ideal workflow as it's slow and I'd rather not switch out of the IDE. I would rather initiate the test from within PHPStorm or from the command line.

Here are my PHP, Debug, and PBGp Proxy Settings as well: PHP Storm - PHP Settings PHP Storm - Debug Settings PHP Storm - dbgp-proxy settings

  • Can you confirm whether you are talking about WebTestBase, KernelTestBase, BrowserTestBase, or UnitTestCase tests? You seem to be talking about a few different things here. Simpletest runs WebTestBase and KernelTestBase, and PhpUnit runs BrowserTestBase and UnitTestCase. (I am also somewhat oversimplifying the situation here, as how testing works has evolved a lot in the last year).
    – mpdonadio
    Commented Jun 10, 2016 at 18:25
  • @MPD I'm super new to the PHPUnit Testing within Drupal so I'm not familiar with the differences between the different tests you mentioned. My custom Module's Tests extend "WebTestBase". WebTestBase extends Testbase which is what the bolt Tests Extend. Commented Jun 10, 2016 at 18:43
  • WebTestBase are usually referred to as integration tests and are run through Simpletest (which is a module/subsystem built in Drupal itself), and not PHPUnit. I'll see if I can come up with a coherent answer about this, or ping someone who can answer this.
    – mpdonadio
    Commented Jun 10, 2016 at 19:25
  • Ahhh, I think you definitely have touched on where my confusion is. So my goal would still be to debug my custom integration test starting an xdebug session from the command line or via PHPStorm. Commented Jun 10, 2016 at 19:44
  • Slide 22 of the talk: Xdebug and Drupal8 tests (PhpUnit and Simpletest) slideshare.net/FranciscoSeva/xdebug-and-drupal - Seems to elude to a way to get this to work but I haven't had any luck. Commented Jun 10, 2016 at 19:46

1 Answer 1


This plugin for PHPStorm solves the problem perfectly. https://www.previousnext.com.au/blog/native-phpstorm-drupal-test-runner#comment-1588


Alternatively, this plugin led me to the realization that you can also do the same thing with a PHP Script Run/Debug configuration.

PHPStorm - PHP Script Run/Debug Configuration

Essentially just adding the following in the arguments field: --php /usr/bin/php --url http://webny.dev --dburl mysql://drupal:[email protected]/drupal --concurrency 1 --module simpletest_example

obvously changing out for your db settings and module/class/file

  • Unfortunately that does not work under a VM if you are using the remote interpreter for PHP (which you should be, IMO). The (official) docs need to be updated for this. As such, this plugin won't work for everyone until that configuration is resolved.
    – Kevin
    Commented Aug 23, 2016 at 18:18
  • @kevin Unless I'm mistaken, this is running on the remote php interpreter, at least how I have it setup. Here's the command that it's actually building ssh://[email protected]:22/usr/bin/php /var/www/webny/docroot/core/scripts/run-tests.sh --php /usr/bin/php --url http://webny.dev --dburl mysql://drupal:[email protected]/drupal --concurrency 1 --color --module simpletest_example I did realize after looking at this that you could do the same thing with the PHP Script Run/Debug configurations too. Updating my answer above with this screenshot. Commented Aug 24, 2016 at 15:18
  • Yeah - was an update released? Last time I added it to PHPStorm, I got a lot of IDE errors. github.com/mglaman/intellij-drupal-run-tests/issues/17
    – Kevin
    Commented Aug 24, 2016 at 15:20

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.