PHPStorm – Docker – PHPUnit – Magento2

von Roman Hutterer, 24. Mai 2017
In this post i want to share my experience with the tools above and want to show which settings it needs to run the PHPUnit tests from Magento2 through PHPStorm in a Docker container. (PHPStorm v.2017.1 and of course on Linux)

This tutorial requires a running docker environment on which magento2 is successfully installed and running

Things i will not explain in this document:

  • Get the sourcecode of magento2 (or the composer file) and put in in a project-folder.
  • Install docker and docker-compose and get your magento container up and running. (i used our own which is available on here:, but it will work with any other docker-setup as well, If you need some help see our blog post in german

Next i want to describe the settings which have to be configured to get PHPStorm communicate with PHP in the container (in PHPStorm it is called a „Remote Interpreter“).

So open up the Settings in PHPStorm and type into the search box upper left „PHP interpreter“.

PHPStorm Settings window
In my case there is already a interpreter configured but to configure a new one simply click on the „three dots icon“ next to the input field of „CLI-Interpreter“. A small window will open where the configuration for the „CLI-Interpreter“ has to be made. Click on the green plus symbol to add a new CLI Interpreter „From Docker, Vagrant, VM, Remote…“
Select CLI Interpreter
After that select the Docker Radiobutton Here is a screenshot of it:

CLI Interpreter Settings window
At the field „Server“ click on the „new“ button next to it and again a new tiny window will open. Here we have to configure the connection to the docker-container.

PHPStorm Settings window for Docker connection
Description for the opened window:
* the field „API-URL“ is already prefilled with the correct URL to the docker socket.
* the field „Certificates Folder“ is also prefilled **but the directory maybe not exists**, in my case i had to create it. In this field enter the absolute path to your .docker directory (e.g. /home/{username}/.docker)
* the value in the field „docker-compose executeable“ can stay untouched, thats it for that window, click OK and the window closes.

After that choose the Docker Image you want to use PHPUnit with. In my case it is  „copex/nginx-php-fpm:dev“. Click again „OK“ and the window will close.

Now we are back to the window where the CLI-Interpreter configuration will be set.
This Window:

CLI Interpreter Settings window again
Select your fresh configured Server in the dropdown element for „Server“.
In the field „Image name“ select the docker image which the current project is based on and where PHP is running, in my case this is „copex/nginx-php-fpm:dev“.

Next the PHP-executeable has to be configured, in my docker-container are multiple PHP-Versions installed so my PHP-executeable’s name is „/usr/bin/php7.0“, please input the path to your php-executeable, click on the „reload icon“ next to the input and PHPStorm will try to connect to it. If the connection is successful PHPStorm will output the php-version, the path to the loaded php.ini, and the information if xdebug is loaded.

At Additional options in the „configuration options“ configured „-dmemory_limit=-1“ to disable memory limit while running tests. Do this again over the „three dots icon“ next to the input element of „Configuration options“.
Now the remote interpreter is configured. click on the button „OK“ and the window will close.

Now we are back on the settings window of phpstorm and a new CLI-Interpreter will appear in the dropdown next to „CLI-Interpreter“,select it. (after selection you can click on the blue small icon with the letter „i“ on it, it will open the output of phpinfo)

Get to the next field „Docker container“ and map the project directory on host machine.
That was the last step here, click on „OK“ and the window will close.
So far so good, if everything is correct PHPStorm can now communicate with PHP on the docker container.

Configuration of PHPUnit in PHPStorm

If you closed the „settings window“ of PHPStorm open it again.
Put in the search bar in the upper left „phpunit“ and select the section „PHPUnit“ under „PHP“ which is under „Language & Frameworks“.

PHPUnit settings window
Here are the interpreters for PHPUnit listed. Click on the „green plus“ icon to add a new interpreter. A tiny selection box will appear, select „Remote Interpreter“, again a small window pops up where the remote interpreter which you configured minutes ago can be selected. Select your configured PHP-Interpreter which connects with the docker-container.
PHPUnit Interpreter Settings window
Now lets set the PHPUnit specific values. The section „PHPUnit library“ let us do this.
In my case i want it easy and i have installed phpunit via composer in my magento2 setup. So i can set the selection to „Use composer autoload“ and enter the path to the autoload.php of composer on the docker-container“ it should be the DocumentRoot of your installed webserver where magento2 root dir is + /vendor/autoload.php. There are sure other possibilitiew which work but i did not try them.

The next section is „Test Runner“, here are the default settings for the tests. is is possible to input a default configuration file (phpunit.dist.xml) and a default bootstrap file (bootstrap.php) but it is not neccessary cause you have to configure the configuration file for each „set of tests“. So i leave those both fields disabled.
Now again click on „OK“ and the window will close.

It‘ done now and your PHPStorm should be able now to run tests on your docker container.

Create a Testprofile in PHPStorm

Now we want to run unit tests in magento2. In PHPStorm click with the right mouse button on the „dev/tests/unit“ folder, the contextmenu will open, select „create unit“ (under Run, Debug,… should be near the middle of the menu) to create a profile for Unit tests. And again a window opens were the configuration needs to be set. (its close to the end, i promise 😉 )

Activate the checkbox for „use alternative configurationfile“ and put in the path to the „phpunit.dist.xml“, which is in the unit folder.

Now the last option will be set, the „Test Scope“. Cause we defined a configuration file where all the configuration is done for us (thanks to magento) we can set the option „Defined in configuration file“ and finsih the configuration at this point.

Create Run/Debug Configuration
thats it ;-). Now all is configured and should work. Now run your configured PHPUnit tests over the „Run“ command.
Run PHPUnit test profile
Here is a small video where the tests are running: