PHPUnit in PhpStorm: Run Configurations, Coverage und Test-Filter

1. Warum PhpStorm-Integration den Testflow verändert

Das übliche Bild in vielen PHP-Teams: Tests werden über ein Terminal ausgeführt, die Ausgabe gescrollt, Fehlermeldungen manuell in den Quellcode übertragen. PhpStorm bietet einen grundlegend anderen Ansatz. Der Test-Runner ist direkt in den Editor eingebettet. Fehlgeschlagene Assertions öffnen den Quellcode per Klick auf exakt der Zeile, die das Problem verursacht. Coverage-Informationen werden als farbige Zeilenhinterlegung direkt im Editor angezeigt – ohne HTML-Report öffnen zu müssen.

Der entscheidende Schritt für diese Integration ist eine sauber konfigurierte PHPUnit Run Configuration in PhpStorm. Diese Konfiguration legt fest, welcher PHP-Interpreter verwendet wird, wo die phpunit.xml liegt, welche Bootstrap-Datei geladen wird und wie Tests gefiltert werden sollen. Für Magento-Projekte mit Docker-Setup kommt ein Remote-Interpreter im Container hinzu – weil PHP nicht lokal installiert ist, sondern ausschließlich im Docker-Container läuft.

2. Remote-Interpreter: Docker-Container als PHP-Quelle

Der erste Schritt für eine funktionierende PHPUnit-Integration in PhpStorm ist die Einrichtung eines Remote-Interpreters. Für Projekte mit Mark-Shust-Docker-Setup bedeutet das: PhpStorm verbindet sich via Docker SDK mit dem laufenden PHP-Container und führt PHP-Prozesse direkt darin aus. Das Ergebnis ist eine Coverage-Analyse und Test-Ausführung, die identisch mit dem Verhalten im Container ist – ohne Pfad-Probleme durch unterschiedliche PHP-Versionen oder Erweiterungen.

Die Einrichtung erfolgt unter Settings → PHP → CLI Interpreter → + → From Docker, Vagrant, VM.... Als Server wählt man den Docker-Socket, als Image das PHP-Container-Image des Projekts. PhpStorm erkennt automatisch die PHP-Version, installierte Erweiterungen (Xdebug, PCOV) und Composer-Pakete. Pfad-Mappings – lokaler Projektpfad zu Pfad im Container – sind entscheidend: ohne korrektes Mapping finden Tests ihre Abhängigkeiten nicht und Coverage-Informationen lassen sich nicht auf lokale Dateien zurückführen.

# docker-compose.yml — Xdebug für Coverage aktivieren (nur im Dev-Container)
# PhpStorm nutzt diesen Container als Remote-Interpreter

services:
  phpfpm:
    image: markoshust/magento-php:8.4-fpm
    environment:
      # XDEBUG_MODE=coverage aktiviert nur Coverage, nicht Debugging
      # Dadurch bleibt der Overhead minimal
      XDEBUG_MODE: "${XDEBUG_MODE:-off}"
    volumes:
      - ./src:/var/www/html
      # PhpStorm überträgt seine eigene Debug-Konfiguration:
      - ./.phpstorm.helpers:/tmp/.phpstorm_helpers:ro
    extra_hosts:
      # PhpStorm-Host für Xdebug-Verbindung (Linux)
      - "host.docker.internal:host-gateway"

Wichtig: XDEBUG_MODE=coverage aktiviert ausschließlich die Coverage-Sammlung von Xdebug, ohne den Step-Debugger zu starten. Das reduziert den Performance-Overhead erheblich gegenüber XDEBUG_MODE=debug,coverage. Für den täglichen Testlauf ohne Coverage kann XDEBUG_MODE=off gesetzt bleiben – PhpStorm kann die Run Configuration entsprechend konfigurieren, um Xdebug nur bei explizitem Coverage-Lauf zu aktivieren.

3. Run Configurations: Unit, Integration und Suite getrennt

Eine einzelne universelle Run Configuration für alle Tests ist antiproduktiv: Sie vermischt Unit- und Integrationstests, läuft unnötig lang und bietet keinen schnellen Feedback-Zyklus. Die empfohlene Praxis ist eine Hierarchie von Run Configurations: eine für schnelle Unit-Tests (Laufzeit unter 30 Sekunden), eine für Integrationstests (mit Datenbankzugriff), eine für die vollständige Test-Suite und optional eine für eine einzelne Testklasse während der aktiven Entwicklung.

Run Configurations in PhpStorm werden unter Run → Edit Configurations angelegt. Typ: PHPUnit. Die wichtigsten Felder: Test scope (Directory, File, Class, Method oder Suite aus XML), PHP interpreter (Remote-Interpreter aus dem Docker-Container), phpunit.xml als Konfigurationsquelle und optionale Environment variables für Testdatenbank-Credentials. Run Configurations lassen sich als XML unter .idea/runConfigurations/ in die Versionskontrolle einchecken – so stehen sie dem gesamten Team sofort zur Verfügung.

<?xml version="1.0" encoding="UTF-8"?>
<!-- .idea/runConfigurations/PHPUnit_Unit_Tests.xml -->
<!-- Diese Datei in Git einchecken: team-weite Konfiguration -->
<component name="ProjectRunConfigurationManager">
  <configuration default="false" name="Unit Tests" type="PHPUnitRunConfigurationType">
    <TestRunner location="vendor/bin/phpunit" />
    <option name="phpunit_ini" value="$PROJECT_DIR$/phpunit.xml" />
    <option name="scope_type" value="DIRECTORY" />
    <option name="directory" value="$PROJECT_DIR$/src/app/code" />
    <!-- Filter: nur Unit-Tests, keine Integrationstests -->
    <option name="phpunit_arguments" value="--testsuite=Unit --no-coverage" />
    <option name="interpreter" value="docker-phpfpm" />
    <envs>
      <env name="XDEBUG_MODE" value="off" />
    </envs>
  </configuration>
</component>

4. Test-Filter: einzelne Tests, Klassen und Gruppen ausführen

Der Test-Filter in PHPUnit ist das wichtigste Werkzeug für den schnellen Entwicklungszyklus. Statt die gesamte Test-Suite zu starten, führt man genau den Test aus, an dem man gerade arbeitet. In PhpStorm genügt ein Klick auf den grünen Play-Button neben einer Testmethode oder -klasse – PhpStorm übergibt automatisch das korrekte --filter-Argument an PHPUnit. Über die Kommandozeile lässt sich dasselbe mit --filter (regulärer Ausdruck auf Methodennamen) oder --testsuite (Name aus phpunit.xml) erreichen.

Gruppenbasiertes Filtern mit der Annotation #[Group('slow')] (PHPUnit 11) oder @group slow (PHPUnit 10) ermöglicht es, langsame Tests aus dem schnellen Entwicklungszyklus herauszulassen und nur im CI-Lauf auszuführen. Die phpunit.xml kann Gruppen aus Standard-Suiten ausschließen oder separate Suiten für bestimmte Gruppen definieren. Das ergibt eine mehrstufige Teststrategie: lokale Schnelltests in unter 10 Sekunden, vollständiger CI-Lauf mit allen Gruppen.

<?php

declare(strict_types=1);

namespace Mironsoft\Catalog\Test\Unit\Model;

use Mironsoft\Catalog\Model\ProductEnricher;
use PHPUnit\Framework\Attributes\CoversClass;
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\Attributes\Group;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;

/**
 * Unit tests for ProductEnricher model.
 * Fast tests — no database, no external services.
 */
#[CoversClass(ProductEnricher::class)]
#[Group('unit')]
final class ProductEnricherTest extends TestCase
{
    /**
     * @test
     * PhpStorm shows green play button — click to run only this method.
     * CLI: vendor/bin/phpunit --filter testEnrichesSkuWithPrefix
     */
    #[Test]
    #[Group('fast')]
    public function testEnrichesSkuWithPrefix(): void
    {
        $enricher = new ProductEnricher(prefix: 'MRN-');
        $result = $enricher->enrich('ABC123');

        self::assertSame('MRN-ABC123', $result->getSku());
    }

    /**
     * @test
     * Slow test excluded from fast suite via Group attribute.
     * CLI: vendor/bin/phpunit --exclude-group slow
     */
    #[Test]
    #[Group('slow')]
    public function testProcessesLargeCatalog(): void
    {
        // simulate expensive operation
        self::assertTrue(true);
    }
}

5. Coverage: Xdebug vs. PCOV und Interpretation im Editor

Coverage-Berichte in PhpStorm werden direkt im Quelltext angezeigt: Zeilenhinterlegungen zeigen auf einen Blick, welche Codezeilen durch Tests abgedeckt sind (grün), welche nicht (rot) und welche nie ausgeführt werden (grau). Das funktioniert mit zwei Coverage-Treibern: Xdebug und PCOV. Xdebug ist die bekannte Option mit breiter Kompatibilität; PCOV ist ein leichtgewichtiger, ausschließlich auf Coverage ausgerichteter Treiber, der deutlich weniger Overhead erzeugt.

In PhpStorm wird die Coverage über Run → Run with Coverage oder den Shield-Button in der Run-Configuration-Toolbar gestartet. PhpStorm generiert dann einen HTML-Report, zeigt Line-Coverage direkt im Editor und liefert eine Coverage-Statistik im Panel Coverage. Für Magento-Projekte ist es wichtig, in der phpunit.xml die <source>-Liste korrekt einzuschränken – sonst berechnet PhpStorm Coverage für Vendor-Code, was die Metriken sinnlos macht und den Lauf verlangsamt.

6. phpunit.xml: Suites und Filter für PhpStorm vorbereiten

Die phpunit.xml ist die zentrale Konfiguration, auf die PhpStorm für alle Run Configurations zeigt. Eine gut strukturierte XML-Datei definiert separate Test-Suiten, schränkt den Coverage-Quellpfad ein und setzt Umgebungsvariablen für den Testlauf. Für Magento-Projekte empfiehlt es sich, zwei getrennte Konfigurationen zu pflegen: phpunit.xml für Unit-Tests (schnell, kein Datenbankzugriff) und phpunit-integration.xml für Integrationstests (mit Magento-Bootstrap, langsam, nur in CI).

<?xml version="1.0" encoding="UTF-8"?>
<!-- src/phpunit.xml — Unit-Test-Konfiguration für PhpStorm -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/11.0/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         colors="true"
         stopOnFailure="false"
         cacheDirectory=".phpunit.cache">

  <testsuites>
    <testsuite name="Unit">
      <directory>app/code/Mironsoft/*/Test/Unit</directory>
    </testsuite>
    <testsuite name="Fast">
      <directory>app/code/Mironsoft/*/Test/Unit</directory>
      <exclude>app/code/Mironsoft/*/Test/Unit/Integration</exclude>
    </testsuite>
  </testsuites>

  <!-- Coverage nur für eigenen Code berechnen -->
  <source>
    <include>
      <directory>app/code/Mironsoft</directory>
    </include>
    <exclude>
      <directory>app/code/Mironsoft/*/Test</directory>
      <directory>vendor</directory>
    </exclude>
  </source>

  <!-- Xdebug oder PCOV als Coverage-Treiber -->
  <coverage>
    <report>
      <html outputDirectory="var/coverage/html"/>
      <clover outputFile="var/coverage/clover.xml"/>
    </report>
  </coverage>

  <php>
    <env name="MAGE_MODE" value="test"/>
    <env name="DB_HOST" value="db"/>
    <env name="DB_NAME" value="magento_test"/>
  </php>
</phpunit>

7. Coverage-Treiber im direkten Vergleich

Die Wahl des Coverage-Treibers hat direkten Einfluss auf die Laufzeit der Test-Suite. Für große Codebasen wie Magento kann der Unterschied zwischen Xdebug und PCOV mehrere Minuten betragen. Die folgende Übersicht zeigt die Unterschiede in der Praxis.

Für den täglichen TDD-Zyklus empfiehlt sich: Coverage komplett deaktivieren (XDEBUG_MODE=off, kein --coverage-*-Argument), dadurch läuft PHPUnit mit voller Geschwindigkeit. Coverage-Analysen werden nach einem Feature-Abschluss oder im CI-Lauf mit PCOV durchgeführt. Xdebug mit Branch-Coverage bleibt dem vollständigen CI-Report vorbehalten. Diese Dreiteilung ergibt den schnellsten lokalen Feedback-Zyklus ohne auf Qualitätsmetriken zu verzichten.

8. Zusammenfassung

PHPUnit in PhpStorm vollständig zu integrieren bedeutet vier Schritte: Erstens einen Remote-Interpreter auf den Docker-Container zeigen lassen, sodass PHP und alle Erweiterungen identisch zur Produktionsumgebung sind. Zweitens separate Run Configurations für Unit-Tests, Integrationstests und die vollständige Suite anlegen und als XML in die Versionskontrolle einchecken. Drittens Test-Filter konsequent nutzen – einzelne Testmethoden per Klick ausführen, Gruppen für langsame Tests definieren und den schnellen Feedback-Zyklus schützen. Viertens Coverage bewusst einsetzen: ohne Overhead im TDD-Zyklus, PCOV für schnelle lokale Analysen, Xdebug mit Branch-Coverage für den CI-Report.

Viele Teams testen faktisch im Dunkeln: Sie wissen nicht, welche Codepfade abgedeckt sind und welche nicht, weil die Coverage-Integration fehlt oder zu langsam ist. PhpStorm mit korrekter Remote-Interpreter-Konfiguration eliminiert dieses Problem: Coverage wird sichtbar im Editor, direkt auf den Zeilen, die es betrifft – ohne HTML-Reports manuell öffnen oder Ausgaben interpretieren zu müssen.

9. FAQ: PHPUnit in PhpStorm