Debug any of Drupal's PHPUnit tests in PhpStorm with a DDEV Environment

I'm a big fan of both PhpStorm and DDEV for Drupal development work. Both are very powerful tools, and I'm sure I only scratch the surface of what they're capable of. I'm always learning new tricks that make PHP development a more enjoyable experience. The latest: configuring PhpStorm to allow me to run Drupal module tests in DDEV using the PhpStorm UI instead of SSHing into the DDEV web container and running them via the CLI.

I learned how to do this by following the steps in this excellent post by @sasunegomo, and then combining that with this blog post by @nmdmatt and our own series on Automated Testing in Drupal.

The end result? I can now run and debug tests in the same environment where the code is being developed while using the handy tools provided by PhpStorm.


This setup requires a couple of steps:

  1. Add a Chromedriver docker image to DDEV to run headless Chrome for FunctionalJavascript tests
  2. Create a docker-compose file based on your DDEV configuration that PhpStorm can understand
  3. Configure PhpStorm to use the docker-compose provided PHP binary when executing PHP commands
  4. Configure PhpStorm to use the new remote interpreter for Composer and PHPUnit

Add a ChromeDriver service to DDEV

If you want to run any of Drupal's FunctionalJavascript tests you'll need to have ChromeDriver (or some other WebDriver API implementation) running. The easiest way to do this is to add a ChromeDriver service to DDEV by using the same drupalci/chromedriver:production Docker image that the test bot uses. Next, provide some configuration in the form of environment variables so PHPUnit/Drupal can use it.

Create the file .ddev/docker-compose.chromedriver.yaml with the following content in your DDEV enabled project:

version: '3.6'
    container_name: ddev-${DDEV_SITENAME}-chromedriver
    # Use the Docker image that the test bot uses.
    image: drupalci/chromedriver:production
      # Make sure ddev can discover the service. ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT $DDEV_URL
  # This links the Chromedriver service to the web service defined
  # in the main docker-compose.yml, allowing applications running
  # in the web service to access the driver at `chromedriver`.
      # If you run tests in PhpStorm with code coverage reports this
      # is where they are stored.
      - ../coverage:/opt/phpstorm-coverage
      - chromedriver:$DDEV_HOSTNAME
      # PHPUnit configuration could also be done via phpunit.xml.
      SIMPLETEST_DB: mysql://db:db@db:3306/db
      SIMPLETEST_BASE_URL: http://web
      BROWSERTEST_OUTPUT_DIRECTORY: /var/www/html/private/browsertest_output
      MINK_DRIVER_ARGS_WEBDRIVER: '["chrome", {"browserName":"chrome","chromeOptions":{"args":["--disable-gpu","--headless", "--no-sandbox"]}}, "http://chromedriver:9515"]'

Then start, or restart, DDEV:

ddev start

DDEV will see, and use, the file you created above and create a new container with ChromeDriver installed. It will also add some necessary environment variables and other configuration to the default web container.

Create a docker-compose.yml file for PhpStorm

It's possible to configure PhpStorm to use a variety of different PHP CLI interpreters. That is, you can tell PhpStorm what PHP binary you want it to use when running commands. Normally it'll use the one(s) it can find in your $PATH. But it's also possible to execute the commands using the PHP Interpreter that's installed in a Docker container.

To do that, PhpStorm reads your docker-compose.yml file and uses the information it contains to connect to the appropriate container and run the commands in that container using docker-compose exec. DDEV also uses Docker. Yay! However, DDEV ads some additional scripting around docker-compose and does a few things that PhpStorm can not directly understand. So we can't use DDEV's docker-compose file. But we can create a new one.

Using the ddev debug command you can dump the compiled docker-compose configuration that is used for your environment into a standard docker-compose.yml file that PhpStorm can understand.

In the root directory of your DDEV/Drupal project run these commands:

mkdir build;
ddev debug compose-config > build/docker-compose.yml

Fixes required for PhpStorm ≤ 2021.1

There's a bug in versions of PhpStorm ≤ 2021.1 (it's already fixed, so if you're reading this when there's a new version of PhpStorm you probably won't need this step) that prevents it from being able to parse the docker-compose.yml file you just created because that file contains some ports configuration for the web container. Luckily, we can just remove it and it'll work fine.

Open the build/docker-compose.yml file, find the lines that look like the following in the configuration for the web container and remove them:


Pro-tip: If you're recreating this file a lot you can create a custom DDEV command that will export the docker-compose.yml file and delete these lines all in one go. See this blog post for more details.

Use the docker-compose PHP Interpreter

Next, configure PhpStorm to use the PHP Interpreter inside the DDEV provided web container.

In PHP Storm navigate to Preferences > PHP and add a new PHP CLI Interpreter by clicking the button next to the dropdown where you choose which CLI Interpreter to use.


In the resulting pop-up click the "+" button and choose the From Docker, Vagrant ... Remote ... option.

  • Choose the Docker Compose option at the top
  • Set Configuration files: to the build/docker-compose.yml file you created earlier
  • Choose web from the Service: dropdown
  • Set the Environment variable COMPOSE_PROJECT_NAME=ddev-{drupal-project} where {drupal-project} is the name of your DDEV project. (Hint: use ddev describe if you don't know)
  • Then click Add to save your new configuration
  • On the resulting screen in the Lifecycle section change to Connect to existing container
  • Optionally, change the Name to something more descriptive than web like ddev-web.
  • And finally click OK

You should now have a new PHP CLI Interpreter named ddev-web similar to the one shown below:


Curious about that [COMPOSE_PROJECT_NAME variable]( We need to set that so that PhpStorm uses the correct container names when running commands like docker-compose exec. DDEV names containers like ddev-d9-web and ddev-d9-db. This configuration accounts for that.

Use the new CLI Interpreter for Composer and PHPUnit

Next we need to tell PhpStorm to use the CLI Interpreter we just configured when running both Composer and PHPUnit commands.

In the PhpStorm preferences, go to PHP > Composer and:

  • Under Execution choose the Remote Interpreter option
  • Choose the new interpreter configured above in the CLI Interpreter dropdown
  • Click Apply to save your changes


Then, in the PhpStorm preferences go to PHP > Test Frameworks and:

  • Click the "+ button to add a new configuration and choose the PHPUnit by Remote Interpreter option
  • Choose the interpreter you configured earlier from the list in the dropdown and click Ok
  • Under Test Runner set the path to your PHPUnit configuration file, e.g. /var/www/html/core/phpunit.xml.dist. Note: This is the path inside the DDEV web container!


Run your PHPUnit tests using the PhpStorm UI

Open a file containing a test, or set of tests you want to run. And then use the PHPStorm UI to run them. When you do, PhpStorm should execute the relevant phpunit command inside of the ddev-web container using docker-compose exec.



Want to debug a test using Xdebug? No problem!

  • Run the command ddev xdebug on to enable Xdebug for the current project.
  • Open the file you want to debug and set a breakpoint
  • Run the test using the PhpStorm UI selecting the Debug instead of the Run option
  • PhpStorm should execute your tests using phpunit inside the ddev-web container and halt execution at your breakpoint




PhpStorm has some features in its UI that can make it easier to execute, and debug, PHPUnit tests. For example, you can choose an individual test method to debug right from the editor and not have to memorize the complex CLI commands. With a bit of configuration, it's possible to have PhpStorm execute those commands within a DDEV-Local environment -- a setup that is in many cases easier to get started with than installing and configuring all the various tools required independently.


hi. unfortunately, for me is returning error when i select the php executable (just after select lifcycle Connect to existent Container): Failed to parse validation script output.
couldn't find a solution yet.
my phpstorm is 2021.2.2

hi again. found the problem. a link in the ./build/docker-compose.yml was invalid
i just removed the invalid link, and now it works the php, phpunit and codeception
thanks for the article!

For DDEV on Apple Sillicon (M1), there is community image built for ARM architecture. c.f.

So, in the above file .ddev/docker-compose.chromedriver.yaml, update the line for the image and MINK_DRIVER_ARGS_WEBDRIVER as follows:

image: seleniarm/standalone-chromium:latest

MINK_DRIVER_ARGS_WEBDRIVER: '["chrome", {"browserName":"chrome","chromeOptions":{ "w3c": false, "args":["--disable-gpu", "--headless", "--no-sandbox", "--window-size=1920,1080", "--whitelisted-ips="]}}, "http://chromedriver:4444/wd/hub"]'

Add new comment

Filtered HTML

  • Web page addresses and email addresses turn into links automatically.
  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <code class> <ul type> <ol start type> <li> <dl> <dt> <dd><h3 id> <p>
  • Lines and paragraphs break automatically.

About us

Drupalize.Me is the best resource for learning Drupal online. We have an extensive library covering multiple versions of Drupal and we are the most accurate and up-to-date Drupal resource. Learn more