Running PHPUnit Tests in PHPStorm with Docker: A Step-by-Step Guide

Lately I've been switching back and forth between several scaffold projects, and I encountered some issues configuring PHPStorm to run unit tests with a remote interpreter using Docker. After some trial and error, this is the process I follow to make sure my project is correctly configured in PHPStorm to work with PHPUnit inside a Docker container.

For this article, I'm going to

• Clone a new Scaffold project
• Verify that the tests run successfully via the command
• Set up PHPStorm and PHPUnit
• Verify the tests run successfully in PHPStorm

Step 1 - Clone a new scaffold project.

In a terminal window, run the following commands

git clone https://github.com/chrisshennan/scaffold scaffold_demo
cd scaffold_demo
make initialize

This might take a few minutes as the Docker image is built, the composer dependencies are installed, and the databases are initialised.

Once complete, you should be presented with something similar to

And at this point, you have a brand-new Scaffold project checked out and ready to work with, complete with a functional dev & test database, and accessible via http://scaffold.localhost:8080

Note: A more detailed setup can be found in the Getting Started documentation.

Step 2 - Verify that the tests run successfully via the command

Before trying to configure PHPUnit inside PHPStorm, let's check that the tests pass successfully via the command line. If they fail here, then they will fail in PHPStorm too.

make tests

This should give an output similar to

Here we can see the tests are passing, so now we can move on to configuring PHPStorm to be able to run the PHPUnit test suite directly from inside the IDE.

Step 3 - Set up PHPStorm and PHPUnit

You can configure PHPStorm to run the test suite for your project making it easy and convenient

Configure the Test Framework & CLI Interpreter

Make sure the project is up and running to ensure the necessary docker containers are available. Once the project is running you can configure XDebug using the following steps:-

• Go to File -> Settings
• Navigate to PHP -> Test Frameworks -> Click "+" -> "PHPUnit by Remote Interpreter"

• Click the "..." to open the "CLI Interpreters" dialog

• Click the "+" to add a new interpreter and select "From Docker, Vagrant, VM, WSL, Remote..."

• Select "Docker Compose"
• Set "service" to "PHP"
• Click "OK"

• Configure CLI Interpreter as
  • Tick "Visible only for this project"
  • Name: "docker-php"
  • Lifecycle: "Always start a new container ('docker-compose run')
  • Click "OK"

• Select "docker-php" interpreter and click "OK"

• Select the folder icon in Path Mappings

• Click the "+" button

• Add a new entry with

  • Local Path: The full path to your Scaffold applications - in my case it's /data/sites/scaffold_demo but this might be different for you

• Remote Path: /app

• Click "OK"

Click "OK"

Setup Test Configuration

• Go to Run (top menu) -> Edit Configurations
• Click "Edit configuration templates"

• Select PHPUnit,
  • Select "Test Scope - Directory"
  • Set the "Interpreter" to docker-php, click "OK"

Updating the PHPUnit template ensures the correct interpreter (the docker one you've just configured) is used, whenever PHPStorm needs to create a new PHPUnit configuration based off the template.

• Click "OK" again

Step 4 - Verify the tests run successfully in PHPStorm

Right click on the tests folder and click "Run"

Tada 🎉

Related Links

• Scaffold - A Symfony and Tailwind CSS boilerplate - https://buildwithscaffold.com/

Originally published at https://chrisshennan.com/blog/running-phpunit-tests-in-phpstorm-with-docker-a-step-by-step-guide