Eine Erweiterung testen

5 Schritte·ca. 15 Min.·Einsteiger·Stand: September 2026

Core und Bundles prüfen ihre Logik mit einfachen PHPUnit-Tests, ohne Kernel, Container oder Datenbank. Sie richten die Tests für das Bundle „acme“ ein und prüfen als Erstes seine Bundle-Klasse.

Was Sie bauen

Eine PHPUnit-Suite im Bundle acme mit einem ersten Test, der im PHP-Container fehlerfrei durchläuft.

Voraussetzungen

  • Zuerst durcharbeiten: Ein Bundle anlegen
  • Eine lokale Vendority-Installation mit Docker, die läuft
Schritt 1 von 5

Schritt 1 von 5

PHPUnit bereitstellen

PHPUnit gehört nicht zu den Abhängigkeiten des Projekts. Es liegt als eigenes kleines Composer-Projekt unter var/tools/phpunit.

Terminal Befehl
docker compose exec -T php var/tools/phpunit/vendor/bin/phpunit --version
docker compose exec -T php mkdir -p var/tools/phpunit
docker compose exec -T php composer require --working-dir=var/tools/phpunit phpunit/phpunit:^11.5
  1. 1

    Der erste Befehl zeigt, ob PHPUnit bereits installiert ist und in welcher Version. Meldet er stattdessen, dass die Datei fehlt, legen die beiden anderen Befehle den Ordner an und installieren PHPUnit. Ohne den Ordner bricht composer require mit „Invalid working directory specified“ ab.

  2. 2

    Alle Befehle laufen im Container php, also mit derselben PHP-Version wie Vendority selbst.

  3. 3

    var/ steht nicht unter Versionskontrolle. PHPUnit bleibt so aus der composer.json des Projekts heraus.

Schritt 2 von 5

Die Test-Konfiguration anlegen

Die Datei phpunit.xml.dist im Bundle sagt PHPUnit, wo die Tests liegen und wie streng es prüfen soll.

phpunit.xml.dist Neue Datei
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         bootstrap="tests/bootstrap.php"
         colors="true"
         cacheDirectory=".phpunit.cache"
         failOnWarning="true"
         failOnRisky="true">
    <testsuites>
        <testsuite name="Acme bundle">
            <directory>tests</directory>
        </testsuite>
    </testsuites>

    <source>
        <include>
            <directory>src</directory>
        </include>
    </source>
</phpunit>
.gitignore Geändert
assets/node_modules
assets/.npmrc
assets/.__mf__temp
/.phpunit.cache

+1 Zeile neu · grau: bestehender Code zur Orientierung

  1. 1

    bootstrap verweist auf tests/bootstrap.php. Diese Datei schreiben Sie im nächsten Schritt.

  2. 2

    <directory>tests</directory> nimmt jede Datei unter tests/ auf, deren Name auf Test.php endet.

  3. 3

    Mit failOnWarning und failOnRisky schlägt der Lauf fehl, sobald PHPUnit warnt oder ein Test nichts prüft.

  4. 4

    <source> nennt den Code des Bundles, den die Tests abdecken.

  5. 5

    Im Ordner .phpunit.cache merkt sich PHPUnit Ergebnisse früherer Läufe. Er gehört nicht ins Repository.

Schritt 3 von 5

Den Autoloader des Projekts einbinden

Ein Bundle hat kein eigenes vendor-Verzeichnis. Die Tests laden deshalb den Autoloader des Projekts, in dem das Bundle liegt.

tests/bootstrap.php Neue Datei
<?php
declare(strict_types=1);

// dev/vendority/acme-bundle/tests → Projektverzeichnis
$autoloadPath = __DIR__ . '/../../../../vendor/autoload.php';

if (!is_file($autoloadPath)) {
    throw new RuntimeException(sprintf(
        'Could not find the host application autoloader at %s. Run these tests from inside a Vendority project.',
        $autoloadPath,
    ));
}

/** @var Composer\Autoload\ClassLoader $loader */
$loader = require $autoloadPath;
$loader->addPsr4('Vendority\\Bundle\\Acme\\Tests\\', __DIR__);
  1. 1

    Damit laufen die Tests gegen dieselben Symfony- und Core-Klassen, die auch das Bundle verwendet. Ihre Klassen unter Vendority\Bundle\Acme\ findet der Autoloader bereits, seit Sie das Bundle mit composer require eingebunden haben.

  2. 2

    Der Pfad ../../../../vendor/autoload.php führt von dev/vendority/acme-bundle/tests ins Projektverzeichnis.

  3. 3

    Den Namensraum Vendority\Bundle\Acme\Tests\ meldet die Datei selbst an, weil Composer autoload-dev nur im Projekt beachtet, nicht in einem eingebundenen Paket.

  4. 4

    Fehlt der Autoloader, bricht die Datei mit einer Meldung ab, die sagt, wo sie ihn gesucht hat.

Schritt 4 von 5

Den ersten Test schreiben

Der erste Test prüft die Bundle-Klasse aus dem Tutorial „Ein Bundle anlegen“: Stimmen Plugin-Name und Pfad zum Frontend?

tests/VendorityAcmeBundleTest.php Neue Datei
<?php
declare(strict_types=1);

namespace Vendority\Bundle\Acme\Tests;

use PHPUnit\Framework\Attributes\CoversClass;
use PHPUnit\Framework\TestCase;
use Vendority\Bundle\Acme\VendorityAcmeBundle;

#[CoversClass(VendorityAcmeBundle::class)]
final class VendorityAcmeBundleTest extends TestCase
{
    public function testPluginNameMatchesTheFrontend(): void
    {
        $bundle = new VendorityAcmeBundle();

        self::assertSame('acme', $bundle->getPluginName());
        self::assertTrue($bundle->hasFrontend());
    }

    public function testRemoteEntryLiesWhereAssetsInstallPutsTheBuild(): void
    {
        $bundle = new VendorityAcmeBundle();
        $publicDir = preg_replace('/bundle$/', '', strtolower($bundle->getName()));

        self::assertSame(
            'bundles/' . $publicDir . '/build/remoteEntry.js',
            $bundle->getRemoteEntryUrl(),
        );
    }
}
  1. 1

    Der Test erzeugt die Bundle-Klasse direkt mit new, ohne Kernel und ohne Container. So arbeiten alle Tests in Core und Bundles.

  2. 2

    #[CoversClass] nennt die Klasse, die der Test prüft.

  3. 3

    Der erste Test stellt sicher, dass der Plugin-Name acme lautet und das Bundle ein Frontend mitbringt.

  4. 4

    Der zweite leitet den Ordner so her, wie assets:install ihn benennt: Klassenname in Kleinbuchstaben, ohne die Endung „bundle“. Benennen Sie die Klasse um und vergessen getViteBuildDirectory(), fällt der Fehler hier auf und nicht erst im Browser, wenn der Core das Plugin nicht laden kann.

Schritt 5 von 5

Die Tests ausführen

PHPUnit läuft im PHP-Container und startet im Verzeichnis des Bundles.

Terminal Befehl
docker compose exec -T php sh -c 'cd /var/www/html/dev/vendority/acme-bundle && /var/www/html/var/tools/phpunit/vendor/bin/phpunit'
  1. 1

    Der Befehl wechselt im Container in das Bundle, damit PHPUnit die phpunit.xml.dist findet.

  2. 2

    Jeder Punkt in der Fortschrittszeile steht für einen bestandenen Test. Ein F steht für einen fehlgeschlagenen; was genau abweicht, zeigt PHPUnit darunter.

  3. 3

    Mit --filter und dem Namen eines Tests führen Sie nur diesen aus, etwa --filter testPluginNameMatchesTheFrontend.

Geschafft.

Sie haben „Eine Erweiterung testen“ von Anfang bis Ende durchgearbeitet.

Zurück zu „Testen“

Blättern auch mit ← und →