mitmario.dev

PHPUnit einrichten

PHP Sandbox 5 Min Lesezeit 3 BeispieleLektion 2 von 6

Fünf rote Fälle, und trotzdem endet das Skript mit pruefe() mit dem Exit-Code 0. Jeden Fall muss außerdem jemand von Hand aufrufen. Ein Testwerkzeug findet die Fälle von allein und zeigt einen Unterschied so, dass du ihn lesen kannst. Am Ende steht ein Exit-Code, an dem ein anderes Programm ablesen kann, ob alles grün war. PHPUnit bringt das alles mit.

Installieren, und zwar als Werkzeug

Installiert wird es mit Composer wie jedes andere Paket aus Abschnitt 9. Nur steht ein Schalter mehr in der Zeile, composer require --dev phpunit/phpunit ^11.

Mit dem Schalter --dev landet das Paket in der composer.json unter require-dev statt unter require. Unter require stehen die Pakete, ohne die dein Programm nicht läuft. PHPUnit gehört nicht dazu, denn auf dem Server, der deine Seite ausliefert, läuft nie ein Test. Dort ruft man composer install --no-dev auf, und dann bleiben diese Pakete weg, samt allem, was sie selbst mitbringen. So liegt auf der Maschine im Netz weniger fremder Code.

In der composer.json der Beispiele steht PHPUnit deshalb unter require-dev. Angekündigt war das schon in der Lektion „composer.json“ in Abschnitt 9.

Was neben deinem Test liegen muss

Der erste Test, ganz klein
<?php

declare(strict_types=1);

use App\Rechnung;
use PHPUnit\Framework\TestCase;

final class RechnungTest extends TestCase
{
    public function testBruttoSchlaegtDieMehrwertsteuerAuf(): void
    {
        $this->assertSame(119.0, Rechnung::brutto(100.0));
    }
}

Neben dem Test liegen vier Dateien, und die ersten drei schreibst du in einem Projekt nur einmal:

  • Die composer.json sagt, was installiert wird und wo deine Klassen liegen.
  • Die phpunit.xml sagt PHPUnit, in welchem Ordner die Tests liegen und was vor ihnen geladen wird.
  • Die Datei tests-starten.php gibt es nur wegen des Prüfen-Buttons. Der startet immer eine PHP-Datei, und diese enthält unter ihren Kommentaren nur die eine Zeile, die PHPUnit startet. Im Terminal steht der Lauf dann als php tests-starten.php. Tippst du selbst, brauchst du den Umweg nicht. vendor/bin/phpunit ist derselbe Lauf, so wie auf dem eigenen Rechner.
  • src/Rechnung.php ist der Code, um den es geht.

Die eigentliche Arbeit steht in tests/RechnungTest.php, und PHPUnit findet sie nur, weil die Datei auf Test.php endet, die Klasse so heißt wie die Datei und von TestCase erbt. Jede öffentliche Methode, deren Name mit test beginnt, ist ein eigener Testfall (englisch test case, daher der Name TestCase). Mehr als eine Methode mit einem langen Namen ist das nicht. Statt des Präfixes geht auch das Attribut #[Test] über der Methode. Ich bleibe in diesem Kurs beim Präfix. Das final vor der Klasse heißt, dass von ihr niemand mehr erben darf. Testklassen schreibe ich immer so, denn sie sind keine Oberklasse für etwas anderes.

testBruttoSchlaegtDieMehrwertsteuerAuf liest sich holprig und ist trotzdem richtig so. Im Fehlerfall steht der Name über der Meldung, und ein test1 würde dort gar nichts sagen.

Was $this->assertSame(119.0, …) sonst noch kann und was es daneben gibt, kommt in der nächsten Lektion. Für den Moment reicht es zu wissen, dass der erwartete Wert links steht und der tatsächliche rechts.

Die Zeile bootstrap

bootstrap="vendor/autoload.php" in der phpunit.xml lädt den Autoloader von Composer, bevor der erste Test läuft. Hier ginge es sogar ohne, denn PHPUnit lädt den Autoloader des Projekts selbst, wenn es über Composer installiert wurde. Nimmst du das Attribut im Editor heraus, läuft vendor/bin/phpunit trotzdem.

In den Beispielen steht es trotzdem. Irgendwann muss ein Projekt vor den Tests noch etwas erledigen, zum Beispiel eine Zeitzone setzen. Dafür ist bootstrap die Stelle, und dann zeigt es auf eine eigene Datei statt direkt auf den Autoloader.

Die Ausgabe lesen

Bei einem erfolgreichen Lauf steht am Ende OK (1 test, 1 assertion), also die Zahl der Tests und die der assert-Aufrufe darin. Die Punkte darüber sind der Fortschritt, ein Punkt je Test.

vendor/bin/phpunit --testdox schreibt die Tests als Sätze untereinander, je einer mit Haken, und aus testBruttoSchlaegtDieMehrwertsteuerAuf wird Brutto schlaegt die mehrwertsteuer auf. Bei zwanzig Tests liest sich das besser als zwanzig Punkte. Mit --colors=always steht das OK auf Grün und ein FAILURES! auf Rot. Von selbst färbt PHPUnit nie, auch auf deinem eigenen Rechner nicht, denn colors steht in der phpunit.xml von Haus aus auf false.

Wenn ein Test fehlschlägt
<?php

declare(strict_types=1);

use App\Rechnung;
use PHPUnit\Framework\TestCase;

final class RechnungTest extends TestCase
{
    public function testBruttoSchlaegtDieMehrwertsteuerAuf(): void
    {
        // 100 Euro netto sind 119 Euro brutto. Hier steht mit Absicht
        // eine falsche Erwartung, damit du den Bericht einmal siehst.
        $this->assertSame(119.5, Rechnung::brutto(100.0));
    }
}

Im Fehlerfall stehen im Bericht der Reihe nach die Nummer des Fehlers, Klasse und Methode, der Satz Failed asserting that 119.0 is identical to 119.5. und die Datei samt Zeile, in der das assertSame() steht. Übersetzt heißt der Satz etwa „Dass 119.0 dasselbe ist wie 119.5, ließ sich nicht bestätigen“. Vorn steht dabei der Wert, der herauskam, hinten der erwartete. Ganz am Ende kommen FAILURES! und Tests: 1, Assertions: 1, Failures: 1.

Aus dem Punkt in der Fortschrittszeile ist ein F geworden. Die Buchstaben dort sind eine Kurzschrift: . heißt bestanden, F eine Erwartung, die nicht erfüllt war, E ein Fehler im Code, R riskant und S übersprungen.

Unter der Zeile mit RechnungTest.php:14 steht eine zweite, die auf vendor/bin/phpunit zeigt. Sie kommt vom Umweg über tests-starten.php und hat mit deinem Test nichts zu tun. Tippst du vendor/bin/phpunit selbst, taucht sie gar nicht auf. Ein Lauf mit einem roten Test endet außerdem mit einem Exit-Code ungleich null, hier mit 1, ein grüner mit 0. vendor/bin/phpunit; echo $? schreibt die Zahl unter den Bericht. Daran erkennt ein Programm, das deinen Stand vor dem Ausliefern prüft, ob es weitermachen darf.

Wo PHPUnit sucht und wo nicht

Wo PHPUnit die Tests sucht
<?php

declare(strict_types=1);

use App\Rechnung;
use PHPUnit\Framework\TestCase;

// Diese Datei heisst Zweiter.php und nicht ZweiterTest.php. PHPUnit sieht
// deshalb gar nicht hinein, egal was darin steht.

final class ZweiterTest extends TestCase
{
    public function testWirdNieAufgerufen(): void
    {
        $this->assertSame(0.0, Rechnung::brutto(0.0));
    }
}

Im Ordner tests/ liegen hier zwei Dateien mit zusammen drei Testmethoden, und trotzdem steht am Ende OK (2 tests, 2 assertions). PHPUnit durchsucht zwar den Ordner aus der phpunit.xml, nimmt aber nur Dateien, die auf Test.php enden. Zweiter.php öffnet es gar nicht erst. Gibt man die Datei von Hand an, vendor/bin/phpunit tests/Zweiter.php, meldet PHPUnit Class Zweiter cannot be found. Es sucht in der Datei eine Klasse, die so heißt wie die Datei, und darin steht nur ZweiterTest.

Der Lauf sieht dabei grün aus. Ein Test, der nicht gefunden wird, meldet sich nicht. Er fehlt einfach, und nur die Zahl in der Klammer ist um eins zu klein.

Heißt die Datei richtig, enthält aber keine Klasse mit passendem Namen, sagt PHPUnit Class … cannot be found und beendet den Lauf mit No tests executed!.

Mit diesem Fehler fängt auch die Aufgabe an. Dort liegt eine RechnungTest.php, in der noch keine Klasse steht.

Zum Mitnehmen

PHPUnit kommt mit composer require --dev ins Projekt und findet einen Test, wenn die Datei auf Test.php endet, die Klasse wie die Datei heißt und von TestCase erbt und die Methode öffentlich ist und mit test anfängt. Eine Datei mit falschem Namen fällt still durch, nur die Zahl in der Klammer ist dann zu klein.

Jetzt du

Basis Konto, kostenlos

Zu dieser Lektion gehört eine Aufgabe. Du schreibst den Code selbst, und nach jedem Lauf sagt dir eine Prüfliste, was schon stimmt.

Dafür brauchst du das Basis Konto. Es kostet nichts, und ein Passwort gibt es auch nicht.

In diesem Kurs läuft dein Code auf einem Server. Dafür hat das Basis Konto 1 Stunde im Monat, mehr Zeit gibt es mit dem Premium Konto.

Was in dieser Lektion steckt

  • Artikel mit 3 Beispielen zum Ausprobieren

    Steht hier, ohne Konto lesbar.

  • Aufgabe, dein Code läuft auf einem Server

    Öffnet sich mit dem Basis Konto.