PreviousNext: 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
/ 19 August 2021

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 / Selenium2DDriverTests

Prerequisites

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

Debug

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

Servers

Name: drupal.ddev.site
Host: drupal.ddev.site – 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

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.

docker-compose.env.yml

version: '3.6' services: web: # DDev already sets this, add it here to debug Kernel tests. # May be fixed by https://github.com/drud/ddev/pull/3149 environment: - PHP_IDE_CONFIG=serverName=drupal.ddev.site

# Required for Drupal Test Traits. Will be fixed in ddev soon. # @see https://github.com/drud/ddev/issues/3158 working_dir: /var/www/html

docker-compose.chromedriver.yml

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

docker-compose.chrome.yml

version: '3.6' services: chrome: container_name: ddev-${DDEV_SITENAME}-chrome image: previousnext/chrome-headless:65 labels: com.ddev.site-name: ${DDEV_SITENAME} com.ddev.approot: $DDEV_APPROOT external_links: - ddev-router:${DDEV_SITENAME}.${DDEV_TLD} web: links: - 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="http://drupal.ddev.site"/

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"]'/