PHPUnit für Magento in PhpStorm konfigurieren

1. Voraussetzungen und Projektstruktur

Bevor PhpStorm für PHPUnit in einem Docker-basierten Magento-Projekt konfiguriert werden kann, müssen einige Voraussetzungen erfüllt sein. Der Docker-Container mit dem PHP-Interpreter muss laufen und von PhpStorm aus erreichbar sein. Der Magento-Quellcode muss korrekt in PhpStorm als Projekt geöffnet sein – entweder direkt auf dem Dateisystem oder über eine SSH-basierte Remote-Entwicklungsumgebung. PHPUnit muss als Composer-Abhängigkeit installiert sein, sodass vendor/bin/phpunit im Container verfügbar ist.

Für das Mark-Shust-Docker-Setup (das für dieses Projekt verwendet wird) sind die relevanten Container: phpfpm mit PHP 8.4 und dem Magento-Quellcode unter /var/www/html. Der Quellcode auf dem Host liegt unter src/ und ist in den Container gemountet. PhpStorm greift über den Docker-Interpreter auf den phpfpm-Container zu. Die phpunit.xml liegt im Projektroot unter src/. Diese Struktur ist die Basis für alle folgenden Konfigurationsschritte.

2. Docker-Remote-Interpreter in PhpStorm einrichten

Der Remote-Interpreter verbindet PhpStorm mit dem PHP-Binary im Docker-Container. Ohne diesen Schritt kann PhpStorm keine Tests im Container ausführen. Die Konfiguration erfolgt über Settings → PHP → Interpreters → (+) → From Docker, Vagrant, VM, WSL, Remote. Im Dialog Configure Remote PHP Interpreter wählt man Docker als Verbindungstyp und den Docker-Server (meistens Unix socket unter Linux oder Docker for Mac unter macOS). Als Image wählt man das PHP-Image, das auch für den phpfpm-Container verwendet wird.

Nach der Konfiguration zeigt PhpStorm die PHP-Version des Remote-Interpreters an und prüft, ob PHP erreichbar ist. Ein häufiges Problem: Der Docker-Container muss laufen, wenn PhpStorm den Interpreter testet. Bei Verwendung von docker compose muss der Stack vorher mit bin/start oder docker compose up -d phpfpm gestartet sein. Der Interpreter-Name sollte aussagekräftig sein, z.B. Docker PHP 8.4 (phpfpm), da er später in Run Configurations referenziert wird.

# Verzeichnisstruktur für PhpStorm-Konfiguration (Mark Shust Setup)
# Host-Pfad → Container-Pfad (Volume-Mapping)
#
# Host:      ~/development/mironsoft/src/
# Container: /var/www/html/
#
# Dieses Mapping muss in PhpStorm unter
# Settings → PHP → Interpreters → (Remote Interpreter) → Path Mappings
# eingetragen werden:
#
# Local path:  /home/mir/development/mironsoft/src
# Remote path: /var/www/html

# Relevante Container im Mark Shust Setup:
# phpfpm  — PHP 8.4, Composer, PHPUnit
# db      — MySQL für Integrationstests
# redis   — Cache (optional für Tests)

# Überprüfung nach Interpreter-Setup in PhpStorm:
# Settings → PHP → Interpreter zeigt PHP 8.4.x (Docker)
# vendor/bin/phpunit --version gibt PHPUnit 11.x zurück

Ein wichtiges Detail: Path Mappings müssen korrekt konfiguriert sein. PhpStorm sendet den lokalen Dateipfad an den Remote-Interpreter; dieser muss den entsprechenden Container-Pfad kennen. Das Path Mapping teilt PhpStorm mit, dass /home/mir/development/mironsoft/src auf dem Host /var/www/html im Container entspricht. Falsche Path Mappings führen dazu, dass PhpStorm Testdateien nicht finden kann oder Coverage-Informationen nicht auf die richtigen Zeilen abbildet.

3. PHPUnit als Test-Framework in PhpStorm konfigurieren

Nach dem Interpreter-Setup muss PHPUnit als Test-Framework registriert werden. Die Konfiguration erfolgt unter Settings → PHP → Test Frameworks → (+) → PHPUnit by Remote Interpreter. Im Dialog wählt man den gerade konfigurierten Remote-Interpreter und gibt den Pfad zur PHPUnit-Autoloader-Datei an: /var/www/html/vendor/autoload.php (Container-Pfad). Optional kann die phpunit.xml als Standard-Konfiguration angegeben werden: /var/www/html/src/phpunit.xml oder je nach Projektstruktur.

PhpStorm versucht nach der Konfiguration, PHPUnit über den Remote-Interpreter zu starten und die Version auszulesen. Bei Erfolg wird PHPUnit 11.x oder die installierte Version angezeigt. Bei Fehlern ist meistens entweder der Container nicht gestartet, das Path Mapping falsch oder der Autoloader-Pfad stimmt nicht. Die Debug-Ausgabe im Event Log-Panel von PhpStorm enthält Details über den fehlgeschlagenen Verbindungsversuch.

<!-- phpunit.xml — Konfiguration für PhpStorm-Integration (Magento 2.4) -->
<?xml version="1.0" encoding="UTF-8"?>
<phpunit
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
  colors="true"
  cacheDirectory=".phpunit.cache"
  executionOrder="defects,duration"
>
  <testsuites>
    <testsuite name="unit">
      <directory>app/code/Mironsoft</directory>
      <exclude>app/code/Mironsoft/*/Test/Integration</exclude>
    </testsuite>
    <testsuite name="integration">
      <directory>app/code/Mironsoft</directory>
      <include>app/code/Mironsoft/*/Test/Integration</include>
    </testsuite>
  </testsuites>
  <source>
    <include>
      <directory suffix=".php">app/code/Mironsoft</directory>
    </include>
    <exclude>
      <directory>app/code/Mironsoft/*/Test</directory>
    </exclude>
  </source>
  <!-- bootstrap wird per Run Configuration überschrieben -->
</phpunit>

4. Run Configurations für verschiedene Test-Suiten

Run Configurations in PhpStorm erlauben es, verschiedene PHPUnit-Setups als wiederverwendbare Konfigurationen zu speichern und mit einem Klick oder Tastenkürzel auszuführen. Für ein Magento-Projekt empfehlen sich mindestens zwei Konfigurationen: eine für Unit-Tests (schnell, ohne Datenbankzugriff) und eine für Integrationstests (langsamer, mit Magento-Bootstrap und Datenbankzugriff).

Eine neue Run Configuration wird über Run → Edit Configurations → (+) → PHPUnit angelegt. Die wichtigsten Felder: Test runner wählt den Remote-Interpreter; Test scope kann auf Defined in configuration file gestellt und die entsprechende phpunit.xml angegeben werden; oder auf Suite mit dem Namen der gewünschten Suite. Die Environment variables erlauben es, Umgebungsvariablen für den Testlauf zu setzen – zum Beispiel XDEBUG_MODE=off für schnelle Läufe ohne Debugging. Für den Magento-Integrationstest-Bootstrap kann MAGENTO_BOOTSTRAP=1 als Environment-Variable eingetragen und im Bootstrap-Skript ausgewertet werden.

5. Coverage-Ansicht in PhpStorm aktivieren

PhpStorm visualisiert Coverage-Daten direkt im Editor: Zeilen, die von Tests abgedeckt werden, erscheinen grün markiert; nicht abgedeckte Zeilen rot. Um diese Ansicht zu aktivieren, muss die Run Configuration mit Run with Coverage gestartet werden (das Schild-Symbol neben dem Run-Button). PhpStorm leitet die Coverage-Informationen aus der PHPUnit-Ausgabe ab und blendet sie sofort nach dem Testlauf in den betroffenen Dateien ein.

Voraussetzung für Coverage in PhpStorm mit dem Docker-Interpreter: entweder pcov oder Xdebug muss im Container installiert und korrekt konfiguriert sein. Mit pcov: XDEBUG_MODE=off als Umgebungsvariable in der Run Configuration setzen und sicherstellen, dass pcov in der PHP-Konfiguration des Containers aktiviert ist. Mit Xdebug: XDEBUG_MODE=coverage setzen. Die Coverage-Ergebnisse werden im Coverage-Tool-Window von PhpStorm tabellarisch nach Klassen und Methoden aufgelistet und können als HTML-Bericht exportiert werden.

6. Xdebug-Integration: Tests mit Breakpoints debuggen

Einer der größten Vorteile der PhpStorm-Integration ist das Debuggen von Tests mit Breakpoints. Wenn ein Test fehlschlägt und die Ursache nicht offensichtlich ist, ermöglicht das Debugging, den Zustand aller Variablen an jedem Punkt der Ausführung zu inspizieren. Das setzt voraus, dass Xdebug im Container konfiguriert und erreichbar ist.

Im Mark-Shust-Setup wird Xdebug über bin/xdebug enable aktiviert. PhpStorm hört standardmäßig auf Port 9003 für eingehende Xdebug-Verbindungen. In der PHP → Debug-Einstellung muss sichergestellt sein, dass Xdebug als Debug-Extension ausgewählt und der Port 9003 konfiguriert ist. Die Run Configuration für das Debuggen startet man mit dem Debug-Button (Käfer-Symbol). PhpStorm stoppt die Ausführung an jedem gesetzten Breakpoint und zeigt Variablenwerte, Call Stack und den aktuellen Ausführungskontext an.

<?php
// Beispiel-Test zum Debuggen mit PhpStorm-Breakpoints
declare(strict_types=1);

namespace Mironsoft\Catalog\Test\Unit\Service;

use Mironsoft\Catalog\Service\TaxCalculator;
use PHPUnit\Framework\TestCase;

final class TaxCalculatorTest extends TestCase
{
    private TaxCalculator $calculator;

    protected function setUp(): void
    {
        $this->calculator = new TaxCalculator(defaultRate: 0.19);
    }

    /**
     * Set a breakpoint on the next line in PhpStorm,
     * then run this test with the Debug button (Shift+F9).
     * PhpStorm will stop here and show all variable values.
     */
    public function testCalculatesTaxForStandardRate(): void
    {
        $result = $this->calculator->calculate(netAmount: 100.0); // <- Breakpoint here

        // Inspect $result in the Debug tool window before this assertion
        $this->assertSame(119.0, $result);
    }

    public function testReturnsZeroForZeroAmount(): void
    {
        $result = $this->calculator->calculate(netAmount: 0.0);
        $this->assertSame(0.0, $result);
    }
}

7. Magento-spezifische Besonderheiten

Magento-Integrationstests haben einige Besonderheiten, die PhpStorm-Konfigurationen betreffen. Der Magento-eigene Test-Bootstrap (dev/tests/integration/framework/bootstrap.php) initialisiert den Objekt-Manager, stellt Datenbankverbindungen her und konfiguriert den Store. Dieser Bootstrap muss in der phpunit.xml für Integrationstests korrekt referenziert sein. Für Unit-Tests genügt der Composer-Autoloader.

Eine weitere Magento-Besonderheit: Der Magento-Testrahmen für Integrationstests erwartet, dass Umgebungsvariablen wie TESTS_CLEANUP und MAGENTO_MEMORY_LIMIT_FOR_SETUP gesetzt sind. Diese werden in der Run Configuration als Umgebungsvariablen eingetragen. Außerdem müssen für Integrationstests die Datenbankzugangsdaten für die Testdatenbank verfügbar sein – meistens über eine phpunit.xml.dist im Magento-Integrationstest-Verzeichnis, die mit projektspezifischen Werten überschrieben wird.

9. Zusammenfassung

PHPUnit in PhpStorm für ein Docker-basiertes Magento-Projekt zu konfigurieren erfordert mehrere Schritte, die aufeinander aufbauen: Remote-Interpreter mit korrektem Path Mapping, PHPUnit-Framework-Registrierung mit dem Container-Autoloader-Pfad, separate Run Configurations für Unit- und Integrationstests und korrekte Xdebug-Konfiguration für das Debugging. Ist die Konfiguration einmal fertig, sind Tests mit einem Klick oder Tastenkürzel ausführbar.

Der wichtigste praktische Tipp: Separate Run Configurations für schnelle Unit-Tests und langsame Integrationstests anlegen. Im Entwickleralltag wird hauptsächlich die Unit-Test-Konfiguration verwendet – sie läuft in Sekunden und gibt sofortiges Feedback. Die Integrationskonfiguration wird seltener genutzt, ist aber für die vollständige Validierung vor dem Commit unverzichtbar. Die Coverage-Ansicht in PhpStorm macht Testlücken sofort sichtbar und motiviert dazu, kritische Codepfade abzudecken.