Skip to main content

Running and debugging PHPUnit tests in PHPStorm with DDev and xdebug

As a follow up to some recent blog posts, as well as improvements in PHPStorm and ddev, I’d like to share the following configuration for running and debugging tests via PHPStorm's phpunit integration.

by michael.strelan /

Have a look at the video below that demonstrates how to configure everything you need to run and debug:

  • Unit tests
  • Kernel tests
  • Functional tests
  • FunctionalJavascript tests
  • Drupal Test Traits / Selenium2DriverTests

You can also checkout the ddev-phpunit-demo repo if you want to try it out yourself with DDev and PHPUnit pre-configured.


  • PHPStorm 2021.2
  • DDev
  • XDebug 3
  • Drupal 9

You may be able to achieve the same result with an alternative docker-compose environment, but I'm using DDev here since it mostly works out of the box.

PHPStorm configuration

In this section I’ll share the final configuration I’m using. You can refer to the video above for an explanation of why some of these are needed.

All of these settings are found under the PHP section of the PHPStorm settings dialog. Before we start let’s run ddev xdebug on to ensure the PHP extension is enabled.

CLI interpreter

  • From the add dropdown choose From Docker, Vagrant, VM, WSL, Remote…
  • Select Docker compose
  • Choose the full docker compose file generated by ddev found at ./.ddev/.ddev-docker-compose-full.yaml
  • Select the web service
  • Add the environment variable COMPOSE_PROJECT_NAME=ddev-drupal (where drupal is the ddev project name in .ddev/config.yaml
  • Lifecycle: Connect to existing container (‘docker compose --exec’)
  • Path mappings - should be set for you
CLI Interpreter configuration


  • Xdebug debug port: 9000,9003. This should be set for you automatically. Note that xdebug 3 uses 9003 by default whereas xdebug 2 uses 9000. Currently ddev defaults to 9000. This setting allows us to listen on multiple ports.
  • Uncheck Force break at first line when no path mapping specified - we’ll discuss this later when we start debugging Kernel tests.
PHPStorm debug config


  • Name:
  • Host: - must match the domain name of your drupal site
  • Use path mappings
  • Map the root of your project on your local machine to the absolute path on the docker container, e.g. /home/michael/www/drupal -> /var/www/html
  • You don’t need to map the web root or vendor dir since you’re mapping the entire project
PHP server configuration

Composer (optional)

  • Path to composer.json - absolute path on your local machine
  • Execution: remote interpreter
  • CLI Interpreter: choose the interpreter we set up previously
PHPStorm composer config

Test frameworks

  • From the add dropdown choose PHPUnit by Remote Interpreter, then choose the one we set up already
  • PHPUnit library - Use Composer autoloader, set to absolute path in container, i.e. /var/www/html/vendor/autoload.php
  • Default config file - /var/www/html/phpunit.xml
PHPStorm test framework

DDev configuration

UPDATE JANUARY 2022 - Since v1.18.2 ddev now ships its own docker-compose version. This defaults to v2 which still has some compatibility issues with PHPStorm. For now you can revert ddev's docker-compose version with the following command:

ddev config global --required-docker-compose-version=v1.29.2 


For the most part DDev configures everything we need to use xdebug in PHPStorm. There are a few extra parts we need for running every kind of test. Fortunately we can extend the generated docker-compose file by adding extra files in the .ddev directory. Add the following files then run ddev restart to regenerate the full docker-compose file.


version: '3.6'
   # DDev already sets this, add it here to debug Kernel tests.
   # May be fixed by

   # Required for Drupal Test Traits. Will be fixed in ddev soon.
   # @see
   working_dir: /var/www/html


version: '3.6'
   container_name: ddev-${DDEV_SITENAME}-chromedriver
   image: drupalci/chromedriver:production
   labels: ${DDEV_SITENAME}
     com.ddev.approot: $DDEV_APPROOT
     - ddev-router:${DDEV_SITENAME}.${DDEV_TLD}
     - chromedriver:$DDEV_HOSTNAME

version: '3.6'
   container_name: ddev-${DDEV_SITENAME}-chrome
   image: previousnext/chrome-headless:65
   labels: ${DDEV_SITENAME}
     com.ddev.approot: $DDEV_APPROOT
     - ddev-router:${DDEV_SITENAME}.${DDEV_TLD}
     - chrome:$DDEV_HOSTNAME

Running and debugging tests

It's best to refer to the video above for these, but some brief info below.

Unit tests

These should essentially “just work” as they run in a single process with no database, you don’t even need to be listening for connections. Just make sure you have xdebug enabled (ddev xdebug on).

PHPStorm unit test

Kernel tests

We need to make sure the database configured in SIMPLETEST_DB is accessible to the remote PHP interpreter. In ddev you can use mysql://db:db@db/db which is the internal connection string for the database, or for better performance use sqlite://localhost/sites/simpletest/db.sqlite

Kernel tests run in a separate PHP process which means PHPStorm has a harder time dealing with them. See KernelTestBase::runTestInSeparateProcess. To intercept the subprocess we need to make sure we’re listening for connections first. We also need to ensure the PHP_IDE_CONFIG env var is actually set in the subprocess. See the docker-compose.env.yml file that enforces this.

When you debug the test you will see the debugger pauses with two tabs, one for the Kernel test and one for “Standard input code”, which is the subprocess. If you check the debug tab of the subprocess you’ll see “Cannot find a local copy of the file on server /var/www/html/web/Standard input code”. You can ignore this and hit Resume, but it’s easiest to prevent it breaking here in the first place. This is why we uncheck “Force break at first line when no path mapping specified”.

Functional tests

<env name="SIMPLETEST_BASE_URL" value=""/

Again this needs to be accessible to the php interpreter. We could use the internal ddev hostnames however then our debug server configuration won’t match up, so in this case we can use the ddev router. This is why the external_links part of the chromedriver service is important.

Functional Javascript tests

<env name="MINK_DRIVER_ARGS_WEBDRIVER" value='["chrome", {"browserName":"chrome","chromeOptions":{"args":["--disable-gpu","--headless", "--no-sandbox"]}}, "http://chromedriver:9515"]'/

Existing Site Tests / Drupal Test Traits

<env name="DTT_BASE_URL" value=""/>
<env name="DTT_API_URL" value="http://chrome:9222"/>
<env name="DTT_MINK_DRIVER_ARGS" value='["chrome", {"browserName":"chrome","chromeOptions":{"args":["--disable-gpu","--headless", "--no-sandbox"]}}, "http://chromedriver:9515"]'/>


Posted by michael.strelan
Senior Developer



Comment by itamair


Super nice tutorial that I keep as a reference.
But since my last DDV update to v1.18.2 and wit Docker Desktop (for Mac) 4.3.2. now once I configure the CLI Interpreter as Docker Compose pointing the .ddev/.ddev-docker-compose-full.yaml file, then the PhpStorm interface get stuck reporting in red the following issues:

Error while parsing
:Process 'docker-compose config'
failed. The Compose file
is invalid because: services.db.ports contains unsupported option: 'host_ip'
services.web.ports contains unsupported option: 'host_ip' services.web.ports
4 contains unsupported option: 'host_p' services.redis.volumes contains
unsupported option: 'create_host_path' services.web.volumes contains
unsupported option: 'create_host_path' services.web.volumes contains
unsupported option: 'create_host_path' services.web.volumes contains
unsupported option: 'create_host_path' services.redis.volumes contains
unsupported option: 'create_host_path' services.web.volumes contains
unsupported option: 'create_host_path'

It wasn't happening this to me 1 month ago.
May you check if this tutorial is still working fine with the above last release of DDEV and Docker Desktop 4.3.2?

Comment by michael.strelan


I can confirm the same behaviour with v1.18.2. I believe this is because ddev now ships its own docker-compose version which defaults to v2 and there is a related bug in phpstorm. You can workaround this by setting ddev's docker-compose version back to 1.29.2

ddev config global --required-docker-compose-version=v1.29.2

Comment by Benedikt


I followed your super detailed instructions and managed to configure everything as it should.
PHP Remote Interpreter and Test Framework is set up.

But when I try to run any unit test, PHP Storm runs into an error: "Failed to start docker-compose service, start it in a command line and retry".
I've had a look into the logs and apparently PHP Storm runs this command:
docker-compose -f \\wsl$\Ubuntu\home\benedikt\ddev\ddev-craftcms\.ddev\.ddev-docker-compose-full.yaml up -d web

Which then leads to:
ERROR: for ddev-ddev-craftcms-db Cannot create container for service db: Conflict. The container name "/ddev-ddev-craftcms-db" is already in use by container "07a0c37f047f27a83c7b342aebd15310754911ce3f94e8b8f69f54043f86bc47". You have to remove (or rename) that container to be able to reuse that name.

But why does PHP Storm even try to build another container when one is already there?
Shouldn't it just connect to the existing container?

Comment by michael.strelan


Did you select this option?
Connect to existing container (‘docker compose --exec’)

Comment by Darvanen


I feel a bit silly having had to discover this the hard way, but it's worth noting if you're adapting the content here that the end part of (i.e. "") MUST match the server name in your PHPStorm configuration under PHP > Servers. Hopefully this comment will help someone else not spend 2 hours figuring that out :)