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

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.

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

Composer (optional)

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

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

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'<br>services:<br>&nbsp;web:<br>&nbsp;&nbsp; # DDev already sets this, add it here to debug Kernel tests.<br>&nbsp;&nbsp; # May be fixed by https://github.com/drud/ddev/pull/3149<br>&nbsp;&nbsp; environment:<br>&nbsp;&nbsp;&nbsp;&nbsp; - PHP_IDE_CONFIG=serverName=drupal.ddev.site

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

docker-compose.chromedriver.yml

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

docker-compose.chrome.yml

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

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"></env>

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

Existing Site Tests / Drupal Test Traits

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

Shoutouts

Original Article: