Drupal 8: Execute automated tests and debug them in PhpStorm

Submitted by Peter Majmesku on Mon, 08/29/2016 - 20:51

To test Drupal 8 tests by the command line, you need to do the following. You need to export two environment variables first:

export SIMPLETEST_DB=mysql://root:password@localhost/database;
export SIMPLETEST_BASE_URL=http://host;

Then you can execute the test by the following command, being in the Drupal root folder:

vendor/bin/phpunit -c core modules/my_module/tests/src/Kernel/MyTest.php

Make sure to set the environment variable for PhpStorm:

export XDEBUG_CONFIG="remote_enable=1 remote_mode=req remote_port=9000 remote_host= remote_connect_back=0"


There's a phpunit.xml.dist file in PHP projects. That's a template for your PHPUnit configuration. You can specifiy there some PHP ini settings. By this method you do not need to export the variables like above. Copy it to phpunit.xml and set there your settings like follows:


<phpunit bootstrap="tests/bootstrap.php" colors="true"







<!-- Set error reporting to E_ALL. -->

<ini name="error_reporting" value="32767"/>

<!-- Do not limit the amount of memory tests take to run. -->

<ini name="memory_limit" value="-1"/>

<!-- Example SIMPLETEST_BASE_URL value: http://localhost -->

<env name="SIMPLETEST_BASE_URL" value="http://pbt-d8"/>

<!-- Example SIMPLETEST_DB value: mysql://username:password@localhost/databasename#table_prefix -->

<env name="SIMPLETEST_DB" value="mysql://root:password@localhost/pbt-d8"/>

<!-- Example BROWSERTEST_OUTPUT_DIRECTORY value: /path/to/webroot/sites/simpletest/browser_output -->

<env name="BROWSERTEST_OUTPUT_DIRECTORY" value="/home/peter/d8-tests"/>



Afterwards you are able to run your test without the manual environment variables setting, just by specifying your configuration directory by the "-c" parameter. Example:

vendor/bin/phpunit -c modules/permissions_by_term modules/permissions_by_term/tests/src/Kernel/SelectTermTest.php

This command cannot execute SimpleTest tests, which inherit from the WebTestBase class. Only unit tests and tests which inherits from the KernelTestBase class can be run.

Runs a SimpleTest

// --- SimpleTests
php core/scripts/run-tests.sh --url http://d8-paragraphs:8888 --browser --verbose --color --concurrency 4 --class 'Drupal\paragraphs\Tests\ParagraphsPreviewTest'


If the debug mode is switched on in PhpStorm and the debugger does not stop at the breakpoint and you are getting the following output in the debugger window:

Remote file path '/home/user/Websites/my-project/-' is not mapped to any file path in project

 If you have already setup path mapping, then there's probably any error in your code. Chances are, that it is in the first line of the setUp() method of your test class, which inherits from KernelTestBase. Then you probably do not have Drupal 8.2.x but Drupal 8.1.x. If it's in the first line, you can insert any code line or insert


With this function the debugger will be forced to stop on a specific line.

PhpStorm IDE settings (version 2016.1.2)

If you are executing the tests from the command line (and probably also via the IDE itself) it's important that you setup the path mappings, so that Xdebug can recognize your test's location. You can to this in PhpStorm's settings at "Languages & Frameworks > PHP > Servers". Create a host for your Drupal website host and set the path mapping to your tests directory. An example you can find in the screenshot below: 

PhpStorm Path Mapping

PHP XPath and DOMDocument class: Encode URLs to valid HTML standard from a piece of HTML markup

Submitted by Peter Majmesku on Mon, 08/29/2016 - 20:48

The following code example shows how it works:

<?php   $dom = new \DOMDocument('1.0''UTF-8');
// PHP will output warnings about non-standard HTML. Suppress it by "@".
// Iterate over all link-elements.
foreach ($dom->getElementsByTagName('link') as $node) {
// Copy the element to be able to replace it.
$updated_element $node;
$href_value $updated_element->getAttribute'href' );
// Checks if the value contains a standard violating character.
if (is_int(strpos($href_value']=within'))) {
// Encodes the URL to valid href value.
$href_value drupal_urlencode($href_value);
// Replace the wrong html markup.
// Get the HTML markup.
$html_markup_with_wrappers $dom->saveHtml();
// Remove the unnecessary wrappers.
$my_html_markup preg_replace('~<(?:!DOCTYPE|/?(?:html|head|body))[^>]*>\s*~i''',

XDebug: Debug PHP scripts which are executed by Drush within your virtual machine

Submitted by Peter Majmesku on Mon, 08/29/2016 - 20:39

If you have PhpStorm (2016.1.1) installed on your host system and you want to debug PHP code in your virtual machine, which is executed by Drush (PHP command line application), so you need some configuration which is described below.

Settings in your PhpStorm IDE:

Map your project root folder to the absolute path on the server. Make sure that your webapplication's PHP code (e.g. Drupal) is located in the same folder as Drush. Like in the screenshot below.

PhpStorm Xdebug

Uncheck "Force break at the first line when a script is outside the project":

PhpStorm Xdebug

PhpStorm needs to listen to XDebug connections:


Afterwards you are able to Debug the code within Drush itself. But it is not necessarily needed to have the Drush folder mapped, when you want to only debug your Drupal code.

Install Drush via composer (PHP package manager)

composer require "drush/drush:7.3"

I have choosen a specific Drush version to suit in my webapplication's requirements. Run this command in the folder, which contains also your webapplication, to meet the path mappings:

/project-folder (run the command here)

 Drush is then located at "vendor/drush/drush". Make sure to run the Drush file which is located there by creating an alias in your .bash_profile file:

alias drush='php /var/www/vendor/drush/drush/drush.php'

Configure your PHP CLI (command line) settings, to work with XDebug

xdebug.remote_autostart=true (THIS SETTING ENABLES/DISABLES XDEBUG)
xdebug.remote_host=YOUR HOST IP. - E.G: 

Force XDebug to break, so that you can set the path mapping

Use the following function in your code, to make XDebug connecting back to your IDE. If that works, you need only to set the path mapping within your PhpStorm IDE to be able to debug properly.

<?php xdebug_break(); 

If everything works

Your IDE looks like below, if you have setup everything properly:


Now you can use the following Drush command to debug your code.

drush php-eval 'my_nice_function()'

Drupal will be booted up and you can inspect your code during the application runtime. This approach is faster then locating a certain page on your Drupal site for finding the entry point to your code or using the Devel module with it's webpage based PHP execution functionality at http://my-website.dev/devel/php.

Tip: Check out the Phing build tool which is written in PHP

I recommend to create a command with your favorite build tool (I recommend https://www.phing.info/) to quickly disable and enable XDebug. So that you execute "xd" for disabling and "xe" for enabling to save time.


Screen: Run processes in the background on a Linux server

Submitted by Peter Majmesku on Mon, 08/29/2016 - 20:35

The program "Screen" can run processes in background on a Linux server.

This starts an new background session with name "your-screen-name"

screen -S your-screen-name

To save the screen and return to the terminal, type Ctrl+A+D (Ctrl+A is the hint for screen that you want to do something and "D" then "d"etaches from the session without stopping it).

Restore your screen :

screen -d -r your-screen-name

List all available screen sessions:

screen -ls

Type screen -list or -ls to identify the detached screen session.

$ screen -list 
    There are screens on: 
         20751.Melvin_Peter_V42  (Detached)  

Note: 20751.Melvin_Peter_V42 is your session id.

Quit a screen session: 

screen -X -S [session id you want to kill] quit

Or just type


if you are attached in your screen session.

Linux Bash: Force writing console output to a file

Submitted by Peter Majmesku on Mon, 08/29/2016 - 20:34

Sometimes this command just does not write content to a file by the ">" operator:

myprogram do --something > my-file-with-the-output.txt

Then you can you a small Linux default program called "tee". Example usage:

myprogram do --something | tee my-file-with-the-output.txt

Tee allows you also to use some option as "-a" to extend the file's content's instead of replacing them.


Apache2 RewriteRule: Map images folder from remote system to your local virtual host

Submitted by Peter Majmesku on Mon, 08/29/2016 - 20:33

With the following directive in your Apache2 virtual host file (at /etc/apache2/sites-available) you must not download the images from products etc. on your local system for development. You just map your local folder location to the remote one. The following example is for a Drupal site (files are under /sites/default/files):

RewriteEngine On
RewriteOptions Inherit
RewriteRule /sites/default/files/(.*)\.(jpeg|jpg|gif|png)$ http://www.my-website.com/sites/default/files/$1.$2 [L,R=301]


This 1 line does also work:

RedirectMatch ^/media/(.*)\.(jpeg|jpg|gif|png)$ https://www.my-website.com/static/media/$1.$2

This setting can be also made in the .htaccess file in your project folder. It's important that this setting is made in the <IfModule mod_rewrite.c> section.