PHPUnit - kurz & gut

In der Theorie sehen setUp() und tearDown() schön symmetrisch aus, in der Praxis sind sie es aber nicht. Sie müssen tearDown() tatsächlich nur implementieren, wenn Sie in setUp() externe Ressourcen wie Dateien oder Sockets alloziert haben. Dient Ihr setUp() nur dazu, einfache PHP-Objekte zu allozieren, so können Sie im Allgemeinen tearDown() ignorieren. Wenn Sie allerdings viele Objekte in Ihrem setUp() erzeugen, so sollten Sie die auf diese Objekte verweisenden Variablen mit unset() leeren, damit sie von der Garbage Collection erfasst werden können. Die Testfall-Objekte werden nämlich zu keiner vorhersagbaren Zeit der Garbage Collection unterzogen.

Wie gehen Sie vor, wenn Sie zwei Tests mit nur geringfügig unterschiedlichen Initialisierungen haben? Hierfür gibt es zwei Möglichkeiten:

Für die Initialisierung auf der Ebene der Testreihe bietet PHPUnit keine besonders komfortable Unterstützung. Es gibt durchaus Gründe dafür, Teile des Inventars von mehreren Tests gemeinsam nutzen zu lassen. Allerdings ist der eigentliche Grund für die Nutzung von gemeinsam genutztem Testinventar in der Regel ein ungelöstes Designproblem.

Ein gutes Beispiel dafür, wann es sinnvoll ist, Teile des Inventars von mehreren Tests gemeinsam nutzen zu lassen, sind Tests, die mit einer Datenbank interagieren. So gibt es beispielsweise die Möglichkeit, sich nur einmal bei einer Datenbank anzumelden und die resultierende Datenbankverbindung in verschiedenen Tests zu verwenden. Das beschleunigt Ihre Tests natürlich. Zu diesem Zweck verpacken Sie die Testreihe, die Sie beim Aufruf der Klassenmethode suite() erhalten, in einem Objekt der Klasse PHPUnit2_Extensions_TestSetup, das die Methoden setUp() und tearDown() so überschreibt, dass darin eine Datenbankverbindung hergestellt bzw. wieder geschlossen wird. Beispiel 5.1 zeigt mit DatabaseTestSetup eine mögliche Implementierung von PHPUnit2_Extensions_TestSetup. Die Tests der Testfall-Klasse DatabaseTests können beispielsweise mit phpunit DatabaseTestSetup über den Test-basierten Testrunner so ausgeführt werden, dass sie von DatabaseTestSetup dekoriert werden.

<?php
require_once 'PHPUnit2/Framework/TestSuite.php';
require_once 'PHPUnit2/Extensions/TestSetup.php';
 
class DatabaseTestSetup extends PHPUnit2_Extensions_TestSetup {
    protected $connection = NULL;
 
    protected function setUp() {
        $this->connection = new PDO(
          'mysql:host=wopr;dbname=test',
          'root',
          ''
        );
    }
 
    protected function tearDown() {
        $this->connection = NULL;
    }
 
    public static function suite() {
        return new DatabaseTestSetup(
          new PHPUnit2_Framework_TestSuite('DatabaseTests')
        );
    }
}
?>

Es kann aber nicht oft genug darauf hingewiesen werden, dass es den Wert Ihres Tests vermindert, wenn Sie dasselbe Inventar in mehreren Tests verwenden. Das hier zugrunde liegende Designproblem besteht darin, dass die Objekte zu eng miteinander verknüpft sind. Es wäre günstiger, erst das Design zu verbessern und dann Tests mit Hilfe von Stubs (siehe Kapitel 10) zu schreiben. Indem Sie Laufzeit-Abhängigkeiten herstellen, verpassen Sie eine Gelegenheit zur Verbesserung des Designs.

Wie werden Ausnahmen getestet? Es lässt sich keine Zusicherung (Assertion) formulieren, die prüft, ob eine Ausnahme ausgelöst worden ist. Stattdessen müssen Sie beim Schreiben des Tests die durch PHP gegebenen Möglichkeiten zur Ausnahmenbehandlung nutzen.

<?php
require_once 'PHPUnit2/Framework/TestCase.php';
 
class ExceptionTest extends PHPUnit2_Framework_TestCase {
    public function testException() {
        try {
            // ... Code, von dem wir das Auslösen einer Ausnahme erwarten ...
        }
 
        catch (Exception $expected) {
            return;
        }
 
        $this->fail('Eine erwartete Ausnahme wurde nicht ausgelöst.');
    }
}
?>

Wenn der Code, von dem wir das Auslösen einer Ausnahme erwarten, keine Ausnahme auslöst, stoppt der nachfolgende Aufruf von fail() (siehe Tabelle 14.2) den Test und signalisiert das Problem. Wird dagegen die Ausnahme wie erwartet ausgelöst, so kommt der catch-Block zur Ausführung und der Testlauf wird erfolgreich beendet.

Alternativ können Sie Ihre Testfall-Klasse von PHPUnit2_Extensions_ExceptionTestCase ableiten um zu testen, ob eine erwartete Ausnahme vom getesteten Code ausgelöst wird. Beispiel 6.1 zeigt, wie Sie mit der Methode setExpectedException() die erwartete Ausnahme setzen. Wird diese Ausnahme während der Ausführung der Testmethode nicht ausgelöst, so wird der Test als Failure gewertet.

<?php
require_once 'PHPUnit2/Extensions/ExceptionTestCase.php';
 
class ExceptionTest extends PHPUnit2_Extensions_ExceptionTestCase {
    public function testException() {
        $this->setExpectedException('Exception');
    }
}
?>

phpunit ExceptionTest
PHPUnit 2.3.0 by Sebastian Bergmann.

F

Time: 0.006798
There was 1 failure:
1) testException(ExceptionTest)
Expected exception Exception

FAILURES!!!
Tests run: 1, Failures: 1, Errors: 0, Incomplete Tests: 0.

Tabelle 6.1 führt das externe Protokoll von PHPUnit2_Extensions_ExceptionTestCase auf.

Sie können Ihre Testfall-Klasse von PHPUnit2_Extensions_PerformanceTestCase ableiten, um zu testen, ob ein Funktions- oder Methodenaufruf innerhalb eines angegebenen Zeitlimits ausgeführt wird.

Beispiel 6.2 zeigt, wie Sie mit der Methode setMaxRunningTime() ein Zeitlimit für die Ausführung der Testmethode festlegen können. Wird die Ausführung der Testmethode nicht innerhalb dieses Zeitlimits abgeschlossen, so wird der Test als Failure gewertet.

<?php
require_once 'PHPUnit2/Extensions/PerformanceTestCase.php';
 
class PerformanceTest extends PHPUnit2_Extensions_PerformanceTestCase {
    public function testPerformance() {
        $this->setMaxRunningTime(2);
        sleep(1);
    }
}
?>

Tabelle 6.2 führt das externe Protokoll von PHPUnit2_Extensions_PerformanceTestCase auf.

Als Beispiel betrachten wir eine Klasse, die ein Bankkonto repräsentieren soll. Der Vertrag für diese Klasse sieht nicht nur Methoden für den lesenden und schreibenden Zugriff auf das Bankkonto vor, sondern auch die Einhaltung der beiden folgenden Bedingungen:

Der Test-First-Programmierung folgend, schreiben Sie die Tests für die Klasse BankAccount bevor Sie die Klasse selber schreiben. Sie benutzen die Vertragsbedingungen als Ausgangspunkt für die Tests und benennen die Testmethoden entsprechend, wie in Beispiel 8.1 gezeigt.

<?php
require_once 'PHPUnit2/Framework/TestCase.php';
require_once 'BankAccount.php';
 
class BankAccountTest extends PHPUnit2_Framework_TestCase {
    private $ba;
 
    protected function setUp() {
        $this->ba = new BankAccount;
    }
 
    public function testBalanceIsInitiallyZero() {
        $this->assertEquals(0, $this->ba->getBalance());
    }
 
    public function testBalanceCannotBecomeNegative() {
        try {
            $this->ba->withdrawMoney(1);
        }
 
        catch (Exception $e) {
            return;
        }
 
        $this->fail();
    }
 
    public function testBalanceCannotBecomeNegative2() {
        try {
            $this->ba->depositMoney(-1);
        }
 
        catch (Exception $e) {
            return;
        }
 
        $this->fail();
    }
 
    public function testBalanceCannotBecomeNegative3() {
        try {
            $this->ba->setBalance(-1);
        }
 
        catch (Exception $e) {
            return;
        }
 
        $this->fail();
    }
}
?>

Nun schreiben Sie den minimal benötigten Code, damit der erste Test, testBalanceIsInitiallyZero(), erfolgreich laufen kann. Dies bedeutet, dass Sie die Methode getBalance() der Klasse BankAccount, wie in Beispiel 8.2 gezeigt, implementieren.

<?php
class BankAccount {
    private $balance = 0;
 
    public function getBalance() {
        return $this->balance;
    }
}
?>

Der Test für die erste Vertragsbedingung läuft nun erfolgreich. Die Tests für die zweite Vertragsbedingung schlagen allerdings noch fehl, da die entsprechenden Methoden der Klasse BankAccount noch nicht implementiert worden sind.

phpunit BankAccountTest
PHPUnit 2.3.0 by Sebastian Bergmann.

.
Fatal error: Call to undefined method BankAccount::withdrawMoney()

Damit die Tests, die die Einhaltung der zweiten Vertragsbedingung überwachen, erfolgreich laufen können, müssen Sie die Methoden withdrawMoney(), depositMoney() und setBalance() der Klasse BankAccount, wie in Beispiel 8.3 gezeigt, implementieren. Diese Methoden werden so implementiert, dass sie eine InvalidArgumentException auslösen, wenn sie mit Parameterwerten, die den Vertrag verletzen würden, aufgerufen werden.

<?php
class BankAccount {
    private $balance = 0;
 
    public function getBalance() {
        return $this->balance;
    }
 
    public function setBalance($balance) {
        if ($balance >= 0) {
            $this->balance = $balance;
        } else {
            throw new InvalidArgumentException;
        }
    }
 
    public function depositMoney($amount) {
        if ($amount >= 0) {
            $this->balance += $amount;
        } else {
            throw new InvalidArgumentException;
        }
    }
 
    public function withdrawMoney($amount) {
        if ($amount >= 0 && $this->balance >= $amount) {
            $this->balance -= $amount;
        } else {
            throw new InvalidArgumentException;
        }
    }
}
?>

Die Tests für die zweite Vertragsbedingung laufen nun ebenfalls erfolgreich:

phpunit BankAccountTest
PHPUnit 2.3.0 by Sebastian Bergmann.

....

Time: 0.057038

OK (4 tests)

Alternativ können Sie die statischen Methoden der Klasse PHPUnit2_Framework_Assert verwenden, um die Zusicherungen im Stile von Design-by-Contract in den Code zu schreiben, wie in Beispiel 8.4 gezeigt. Wenn eine Zusicherung fehlschlägt wird eine Ausnahme vom Typ PHPUnit2_Framework_AssertionFailedError ausgelöst. Auf diese Weise müssen Sie weniger Code für die Überprüfung der Parameterwerte schreiben und die Tests werden lesbarer. Allerdings fügen Sie Ihrem Projekt eine Laufzeitabhängigkeit auf PHPUnit hinzu.

<?php
require_once 'PHPUnit2/Framework/Assert.php';
 
class BankAccount {
    private $balance = 0;
 
    public function getBalance() {
        return $this->balance;
    }
 
    public function setBalance($balance) {
        PHPUnit2_Framework_Assert::assertTrue($balance >= 0);
 
        $this->balance = $balance;
    }
 
    public function depositMoney($amount) {
        PHPUnit2_Framework_Assert::assertTrue($amount >= 0);
 
        $this->balance += $amount;
    }
 
    public function withdrawMoney($amount) {
        PHPUnit2_Framework_Assert::assertTrue($amount >= 0);
        PHPUnit2_Framework_Assert::assertTrue($this->balance >= $amount);
 
        $this->balance -= $amount;
    }
}
?>

Durch das Schreiben der Vertragsbedingungen in die Tests haben wir Design-by-Contract benutzt, um die BankAccount-Klasse zu entwerfen. Danach haben wir, dem Ansatz der Test-First-Programmierung folgend, nur soviel Code geschrieben, wie für das erfolgreiche Durchlaufen der Tests nötig ist. Allerdings haben wir vergessen, Tests zu schreiben, die setBalance(), depositMoney() und withdrawMoney() mit zulässigen Parametern aufrufen. Wir benötigen ein Hilfsmittel, um die Qualität unserer Tests zu überprüfen. Ein solches Hilfsmittel ist die Code-Coverage-Analyse, die wir im nächsten Kapitel kennenlernen werden.

Manchmal müssen Sie überprüfen, ob ein Objekt korrekt aufgerufen worden ist. Dazu können Sie für das aufzurufende Objekt einen ausgewachsenen Stub erstellen. Dann wiederum kann es aber schwierig sein, auf korrekte Ergebnisse zu prüfen. Eine einfachere Lösung besteht darin, das Testfall-Objekt selbst als Stub zu benutzen. Dies bezeichnet man als Self-Shunting. Der Begriff ist von einem in der Medizin üblichen Verfahren übernommen worden, bei dem Blut durch einen Schlauch von einer Arterie in eine Vene geleitet wird, um eine bequeme Möglichkeit zur Injektion von Medikamenten zu schaffen.

Dafür folgt nun ein Beispiel. Angenommen, Sie möchten testen, ob die korrekte Methode eines Objekts aufgerufen wird, das ein anderes Objekt beobachtet. Zunächst machen Sie aus der Testfall-Klasse einen Implementor von Observer:

class ObserverTest extends PHPUnit2_Framework_TestCase implements Observer {
}

Danach implementieren Sie update(), die einzige Methode in Observer, um sicherzustellen, dass diese aufgerufen wird, wenn sich der Zustand des beobachteten Objekts (Subject) ändert:

public $wasCalled = FALSE;

public function update(Subject $subject) {
    $this->wasCalled = TRUE;
}

Jetzt können Sie den Test schreiben. Erzeugen Sie ein neues Objekt der Klasse Subject und registrieren das Testfall-Objekt als Beobachter. Wenn sich der Zustand des Subject-Objekts (beispielsweise durch Aufruf einer Methode doSomething()) ändert, muss dieses die update()-Methoden der registrierten Beobacher-Objekte aufrufen. Wir benutzen die Instanzvariable $wasCalled, die von unserer Implementierung von update() gesetzt wird, um zu testen, ob sich das Subject-Objekt wie erwartet verhält.

public function testUpdate() {
    $subject = new Subject;
    $subject->attach($this);
    $subject->doSomething();

    $this->assertTrue($this->wasCalled);
}

Beachten Sie, dass wir ein neues Subject-Objekt anstelle einer globalen Instanz verwenden. Ein solcher Entwurfsstil, der die Entkopplung zwischen den Objekten verbessert und damit die Wiederverwendbarkeit erleichtert, wird duch die Verwendung von Stubs gefördert.

Wer mit dem Self-Shunt-Pattern nicht vertraut ist, für den können die Tests schwer lesbar sein. Was geschieht hier? Wie kann ein Testfall zugleich ein Beobachter sein? Wenn Sie sich aber erst einmal an diese Vorgehensweise gewöhnt haben, sind die Tests leicht zu lesen. Alles, was Sie zum Verständnis eines Tests benötigen, befindet sich in einer einzigen Klasse.

In einem Projekt, das mit einem agilen Software-Entwicklungsprozess wie dem Extreme Programming entwickelt wird, kommt es häufig vor, dass die Dokumentation nicht mit den Änderungen an Code und Design Schritt halten kann. Extreme Programming verlangt kollektives Eigentum des Codes. Daher müssen alle Entwickler wissen, wie das gesamte System funktioniert. Wenn Sie diszipliniert genug sind und konsequent "sprechende Namen" für Ihre Tests verwenden, können Sie mit Hilfe der TestDox-Funktionalität von PHPUnit automatisch Dokumentation für Ihr Projekt auf Grundlage der Tests erstellen. Diese Dokumentation gibt den Entwicklern einen Überblick über die Klassen des Projekts, und was von ihnen erwartet wird.

Die TestDox-Funktionalität von PHPUnit betrachtet die Testmethoden und erzeugt aus der Camel-Case-Notation der PHP-Namen Sätze: aus testBalanceIsInitiallyZero() wird "Balance is initially zero". Gibt es mehrere Testmethoden, deren Namen sich nur durch eine Ziffer am Ende unterscheiden (beispielsweise testBalanceCannotBecomeNegative() und testBalanceCannotBecomeNegative2()), so wird der entsprechende Satz ("Balance cannot become negative") nur einmal erzeugt, und zwar dann, wenn alle diese Testmethoden erfolgreich durchlaufen wurden.

Das folgende Beispiel zeigt die mit phpunit --testdox-text BankAccountTest.txt BankAccountTest für die Tests aus Beispiel 8.1 erstellte agile Dokumentation.

BankAccount
 - Balance is initially zero
 - Balance cannot become negative

Alternativ kann die agile Dokumentation mit --testdox-html BankAccountTest.htm auch im HTML-Format erstellt werden.

Wenn Sie sich dazu entschließen, bei der Entwicklung ein externes Paket einzusetzen, gehen Sie damit ein gewisses Risiko ein. Es ist nicht auszuschließen, dass sich das Paket nicht so verhält, wie Sie es erwarten, und dass sich zukünftige Versionen in subtiler Weise so verändern, dass Ihre Programme nicht mehr funktionieren, ohne dass Sie es merken. Eine Möglichkeit, dieses Problem zu lösen, besteht darin, Annahmen über die Funktionsweise des externen Paketes durch Tests und agile Dokumentation zu dokumentieren: Jedes Mal, wenn Sie eine Annahme treffen, schreiben Sie einen Test. Wird der Test bestanden, ist Ihre Prämisse gültig. Wenn Sie die erforderliche Disziplin aufbringen und alle Annahmen durch Tests ausdrücken, dann brauchen Sie in der Zukunft neue Versionen des externen Paketes nicht zu fürchten. Sie lassen Ihre Testreihe laufen, und wenn diese erfolgreich verläuft, so können Sie davon ausgehen, dass Ihre Programme weiterhin wie erwartet funktionieren. Andernfalls müssen Sie näher untersuchen, was sich geändert hat.

Wenn Sie Tests dazu verwenden, Prämissen zu dokumentieren, gehören die Tests Ihnen. In diesem Fall haben Sie mit dem Lieferanten des Pakets, auf das Sie sich verlassen können müssen, eine eher distanzierte Beziehung. Ist die Beziehung zu dem Hersteller aber enger oder streben Sie eine engere Beziehung an, so können Tests eine Möglichkeit zur Koordination Ihrer Aktivitäten sein.

Können Sie sich mit dem Ersteller auf eine API einigen, ist es Ihnen möglich, die Tests gemeinsam zu schreiben und zu pflegen. Sie setzen sich mit dem Lieferanten zusammen und codieren die Tests so, dass sie so viele Prämissen wie möglich deutlich machen. Versteckte Anforderungen sind der Tod jeder Kooperation. Anhand der Tests weiß der Hersteller genau, was von ihm erwartet wird. Er braucht erst wiederzukommen, wenn alle Tests erfolgreich laufen.

Mit dem Konzept der Stubs aus dem vorigen Kapitel können Sie die beiden Teams noch weiter entkoppeln:

Auf diese Weise können beide Teams unabhängig voneinander arbeiten.

Wenn Sie eine Fehlermeldung erhalten, so mag Ihre spontane Reaktion darauf sein, den Fehler so schnell wie möglich zu beheben. Diese Neigung ist aber selten hilfreich, da es sehr wahrscheinlich ist, dass Sie mit Ihrer "Reparatur" einen anderen Fehler verursachen.

Tests bieten eine Möglichkeit, diesen spontane Drang im Zaum zu halten.

Die Suche nach der kleinstmöglichen zuverlässigen Reproduktion des Fehlers gibt Ihnen die Möglichkeit, sich wirklich auf die Ursache des Problems zu konzentrieren. Der Test, den Sie schreiben, erhöht die Wahrscheinlichkeit, dass Sie durch die Reparatur wirklich nur den Fehler beseitigen. Zusätzlich vermindert der neue Test die Wahrscheinlichkeit, dass die Korrektur zu einem späteren Zeitpunkt versehentlich rückgängig gemacht wird. Die bereits existierenden Tests tragen dafür Sorge, dass die Korrektur des aktuellen Problems ihrerseits keine neuen Probleme verursacht.

Erst automatisierte Tests machen die zum Erreichen des einfachsten Designs nötigen Änderungen (Refactoring, "neu herstellen") am Code sinnvoll durchführbar. Ohne sie müsste jede Methode einer jeden Klasse von Hand getestet werden, wenn der Code einer Klasse geändert wurde. Der Vorgang des Refactoring kann in kleine Einzelschritte aufgeteilt werden, die verhaltensneutral sind.

Die folgenden Schritte helfen Ihnen, Code und Design Ihres Projekts zu verbessern, und dabei jeden Einzelschritt mit Unit-Tests abzusichern, damit das Ergebnis wirklich verhaltensneutral ist:

Neben dem notwendigen <batchtest>-Element erlaubt das <phpunit2>-Element auch <formatter> als Kindelement. Mit diesem Element kann die Ausgabe der Testergebnisse in unterschiedlichen Formaten gesteuert werden. Die Ausgabe erfolgt dabei grundsätzlich in eine Datei, es sei denn, Sie setzen das Attribut usefile auf false. Der Name der Ausgabedatei wird durch den gewählten Formatierer bestimmt und kann durch das Attribut outfile angepasst werden. Es gibt drei vorgefertigte Formatierer:

Tabelle 12.2 zeigt die Parameter für den <formatter>-Task.

Um einen Test-Report im HTML-Format zu erstellen, können Sie den <phpunit2report>-Task verwenden. Dieser wendet ein XSLT-Stylesheet auf die durch den <formatter>-Task erzeugte XML-Datei an. Phing wird mit zwei vorgefertigten XSLT-Stylesheets für die Erstellung von HTML-Reports (mit oder ohne Frames) ausgeliefert, phpunit2-frames.xsl und phpunit2-noframes.xsl.

Beispiel 12.2 zeigt eine build.xml-Datei für Phing, die die Tests der Klasse BankAccountTest ausführt und mit Hilfe des XSLT-Stylesheets phpunit2-frames.xsl einen Test-Report im HTML-Format erstellt. Die HTML-Dateien werden in das Verzeichnis report/ geschrieben, das durch das prepare-<target> erzeugt wird und über das clean-<target> wieder gelöscht werden kann.

<?xml version="1.0"?>

<project name="BankAccount" basedir="." default="report">
  <target name="prepare">
    <mkdir dir="report"/>
  </target>

  <target name="clean"> 
    <delete dir="report"/>
  </target>

  <target name="report" depends="prepare">
    <phpunit2>
      <batchtest>
        <fileset dir=".">
          <include name="*Test.php"/>
        </fileset>
      </batchtest>

      <formatter type="xml" todir="report" outfile="logfile.xml"/>
    </phpunit2>

    <phpunit2report infile="report/logfile.xml"
                    styledir="/usr/lib/php/data/phing/etc"
                    format="frames"
                    todir="report"/>
  </target>
</project>

Das folgende Beispiel zeigt die Ausgabe des Befehls phing:

phing
Buildfile: /home/sb/build.xml

BankAccount > prepare:
    [mkdir] Created dir: /home/sb/report

BankAccount > report:

BUILD FINISHED

Total time: 0.1112 seconds

Abbildung 12.1 zeigt die Startseite des erstellten Test-Reports.

Abbildung 12.1. Die Startseite des erstellten Test-Reports

Tabelle 12.3 zeigt die Parameter des <phpunit2report>-Tasks.

Analog kann Phing auch Coverage-Reports erstellen. Hierfür benutzen Sie die <coverage-setup>- und <coverage-report>-Tasks. Der erste bereitet eine Datenbank mit den Code-Coverage-Informationen vor. Der zweite nutzt diese Datenbank und erstellt, wiederum durch Anwendung von XSLT-Stylesheets, einen Report im HTML-Format.

Beispiel 12.3 zeigt eine build.xml-Datei für Phing, die die Tests der Klasse BankAccountTest ausführt und einen Coverage-Report im HTML-Format erstellt.

<?xml version="1.0"?>

<project name="BankAccount" basedir="." default="coverage-report">
  <target name="prepare">
    <mkdir dir="coverage-report"/>
  </target>

  <target name="clean"> 
    <delete dir="coverage-report"/>
  </target>

  <target name="coverage-report" depends="prepare">
    <coverage-setup database="./coverage-report/database">
      <fileset dir=".">
        <include name="*.php"/>
        <exclude name="*Test.php"/>
      </fileset>
    </coverage-setup>

    <phpunit2 codecoverage="true">
      <batchtest>
        <fileset dir=".">
          <include name="*Test.php"/>
        </fileset>
      </batchtest>
    </phpunit2>

    <coverage-report outfile="coverage-report/coverage.xml">
      <report styledir="/usr/lib/php/data/phing/etc"
              todir="coverage-report"/>
    </coverage-report>
  </target>
</project>

Abbildung 12.2 zeigt die Startseite des erstellten Coverage-Reports.

Abbildung 12.2. Die Startseite des erstellten Coverage-Reports

In der Regel werden Sie bei der Arbeit mit PHPUnit mit fünf Klassen beziehungsweise Schnittstellen zu tun haben:

Abbildung 14.1 zeigt die Beziehungen zwischen den fünf grundlegenden Klassen und Schnittstellen von PHPUnit: PHPUnit2_Framework_Assert, PHPUnit2_Framework_Test, PHPUnit2_Framework_TestCase, PHPUnit2_Framework_TestSuite, und PHPUnit2_Framework_TestResult.

Abbildung 14.1. Die fünf grundlegenden Klassen und Schnittstellen von PHPUnit

Die meisten für PHPUnit geschriebenen Testfälle sind indirekt von PHPUnit2_Framework_Assert abgeleitet. Diese Klasse enthält die Methoden zur automatischen Prüfung von Werten und zur Meldung von Abweichungen. Diese Methoden sind statisch deklariert, so dass sie als Zusicherungen im Stile von Design-by-Contract in Ihre Methoden eingefügt und die Ergebnisse durch PHPUnit ausgewertet werden können (Beispiel 14.1).

<?php
require_once 'PHPUnit2/Framework/Assert.php';
 
class Sample {
    public function aSampleMethod($object) {
        PHPUnit2_Framework_Assert::assertNotNull($object);
    }
}
 
$sample = new Sample;
$sample->aSampleMethod(NULL);
?>

Fatal error: Uncaught exception 'PHPUnit2_Framework_AssertionFailedError'
with message 'expected: <NOT NULL> but was: <NULL>'

Normalerweise werden Sie die Zusicherungen jedoch im Rahmen von Tests verwenden.

Von jeder Zusicherungsmethode gibt es zwei Varianten: Bei der einen dient der letzte Parameter dazu, dass zusammen mit dem Fehler eine Mitteilung angezeigt wird, während die andere keinen solchen Parameter hat. Typischerweise wird diese optionale Meldung bei der Anzeige eines Fehlers mit ausgegeben und erleichtert das Debuggen.

<?php
require_once 'PHPUnit2/Framework/TestCase.php';
 
class MessageTest extends PHPUnit2_Framework_TestCase {
    public function testMessage() {
        $this->assertTrue(FALSE, 'Dies ist eine angepasste Nachricht.');
    }
}
?>

Das folgende Beispiel zeigt die Ausgabe der Ausführung des Tests testMessage() aus Beispiel 14.2:

phpunit MessageTest.php
PHPUnit 2.3.0 by Sebastian Bergmann.

F

Time: 0.102507
There was 1 failure:
1) testMessage(MessageTest)
Dies ist eine angepasste Nachricht.

FAILURES!!!
Tests run: 1, Failures: 1, Errors: 0, Incomplete Tests: 0.

Tabelle 14.1 zeigt die ganze Vielfalt der Zusicherungen. Die Zusicherungen sind paarweise dargestellt, die zweite Form enthält dabei jeweils den zusätzlichen String-Parameter für den Fehlertext am Ende der Parameterliste.

Es kann vorkommen, dass Sie neben den hier genannten noch weitere Zusicherungen benötigen, um projektspezifische Objekte vergleichen zu können. Schreiben Sie einfach eine Assert-Klasse mit den Zusicherungen, die Sie zur Vereinfachung Ihrer Tests benötigen.

Bei jedem Scheitern einer Zusicherung wird implizit eine Flaschenhals-Methode namens fail(string $message) aufgerufen, die ihrerseits einen PHPUnit2_Framework_AssertionFailedError auslöst. Daneben gibt es noch eine parameterlose Variante von fail(). Sie können fail() auch explizit aufrufen, wenn Ihr Test auf einen Fehler stößt. Ein Beispiel hierfür ist der Test auf eine erwartete Ausnahme. Tabelle 14.2 führt die beiden Flaschenhals-Methoden in PHPUnit auf.

Die generische Schnittstelle PHPUnit2_Framework_Test wird von allen Objekten implementiert, die als Tests dienen können. Eine implementierende Klasse kann einen oder mehrere Tests repräsentieren. Ihre beiden Methoden sind in Tabelle 14.3 dargestellt.

PHPUnit2_Framework_TestCase und PHPUnit2_Framework_TestSuite sind die beiden prominentesten Implementierungen von PHPUnit2_Framework_Test. Sie können PHPUnit2_Framework_Test aber auch selbst implementieren. Die Schnittstelle wurde bewusst schmal gehalten, damit dies möglichst einfach ist.

Ihre Testfall-Klassen leiten Sie von PHPUnit2_Framework_TestCase ab. In der Regel werden Sie die Tests aus automatisch erzeugten Testreihen ausführen. In diesem Fall muss aber jeder Ihrer Tests durch eine Methode repräsentiert sein, die (konventionsgemäß) mit test* benannt ist.

PHPUnit2_Framework_TestCase implementiert PHPUnit2_Framework_Test. countTestCases() liefert 1. run(PHPUnit2_Framework_TestResult $result) führt erst setUp(), danach die Testmethode und schließlich tearDown() aus, wobei alle Ausnahmen in PHPUnit2_Framework_TestResult gemeldet werden.

Tabelle 14.4 führt das durch PHPUnit2_Framework_TestCase implementierte externe Protokoll auf.

Die beiden Schablonenmethoden setUp() und tearDown() können Sie überschreiben, um die Objekte zu erzeugen und zu beseitigen, mit denen Sie die Tests durchführen wollen. Tabelle 14.5 zeigt diese Methoden.

Eine PHPUnit2_Framework_TestSuite ist ein Kompositum (Composite) aus PHPUnit2_Framework_Test-Objekten. Im einfachsten Fall enthält sie mehrere Testfälle, die alle ausgeführt werden, wenn auch die Testreihe ausgeführt wird. Als Composite-Objekt kann eine Testreihe selbst wiederum Testreihen enthalten und so weiter. Dadurch lassen sich auf einfache Weise Tests aus unterschiedlichen Quellen kombinieren und gemeinsam ausführen.

Zusätzlich zu dem Protokoll von PHPUnit2_Framework_Test -- run(PHPUnit2_Framework_TestResult $result) und countTestCases() -- enthält PHPUnit2_Framework_TestSuite noch ein Protokoll für die Erzeugung benannter und unbenannter Instanzen. Tabelle 14.6 zeigt das Protokoll für die Erzeugung von Instanzen der Klasse PHPUnit2_Framework_TestSuite.

Außerdem enthält die PHPUnit2_Framework_TestSuite Methoden für das Hinzufügen und das Auslesen von PHPUnit2_Framework_Tests, die in Tabelle 14.7 aufgeführt sind.

Beispiel 14.3 zeigt, wie Sie eine PHPUnit2_Framework_TestSuite für eine Testfall-Klasse erzeugen sowie deren Tests ausführen.

<?php
require_once 'PHPUnit2/Framework/TestSuite.php';
 
require_once 'ArrayTest.php';
 
// Ein TestSuite-Objekt erzeugen, das die Tests
// der Testfall-Klasse ArrayTest enthält.
$suite = new PHPUnit2_Framework_TestSuite('ArrayTest');
 
// Tests ausführen.
$suite->run();
?>

Als Beispiel für eine hierarchische Komposition von Testreihen betrachten wir die Testreihe von PHPUnit selbst.

Beispiel 14.4 zeigt eine verkürzte Fassung von Tests/AllTests.php, Beispiel 14.5 eine verkürzte Fassung von Tests/Framework/AllTests.php.

<?php
if (!defined('PHPUnit2_MAIN_METHOD')) {
    define('PHPUnit2_MAIN_METHOD', 'AllTests::main');
}
 
require_once 'PHPUnit2/Framework/TestSuite.php';
require_once 'PHPUnit2/TextUI/TestRunner.php';
 
require_once 'Framework/AllTests.php';
// ...
 
class AllTests {
    public static function main() {
        PHPUnit2_TextUI_TestRunner::run(self::suite());
    }
 
    public static function suite() {
        $suite = new PHPUnit2_Framework_TestSuite('PHPUnit');
 
        $suite->addTest(Framework_AllTests::suite());
        // ...
 
        return $suite;
    }
}
 
if (PHPUnit2_MAIN_METHOD == 'AllTests::main') {
    AllTests::main();
}
?>

<?php
if (!defined('PHPUnit2_MAIN_METHOD')) {
    define('PHPUnit2_MAIN_METHOD', 'Framework_AllTests::main');
}
 
require_once 'PHPUnit2/Framework/TestSuite.php';
require_once 'PHPUnit2/TextUI/TestRunner.php';
 
require_once 'Framework/AssertTest.php';
// ...
 
class Framework_AllTests {
    public static function main() {
        PHPUnit2_TextUI_TestRunner::run(self::suite());
    }
 
    public static function suite() {
        $suite = new PHPUnit2_Framework_TestSuite('PHPUnit Framework');
 
        $suite->addTestSuite('Framework_AssertTest');
        // ...
 
        return $suite;
    }
}
 
if (PHPUnit2_MAIN_METHOD == 'Framework_AllTests::main') {
    Framework_AllTests::main();
}
?>

Die Klasse Framework_AssertTest ist eine normale Testfall-Klasse, die sich von PHPUnit2_Framework_TestCase ableitet.

Das Ausführen von Tests/AllTests.php, zu sehen im folgenden Beispiel, benutzt den textbasierten Testrunner für die Ausführung aller Tests, während das Ausführen von Tests/Framework/AllTests.php nur die Tests für die PHPUnit2_Framework_* Klassen ausführt.

php AllTests.php
PHPUnit 2.3.0 by Sebastian Bergmann.

.........................................
.........................................
.......

Time: 4.642600

OK (89 tests)

Wenn Sie alle Ihre Tests ausführen, benötigen Sie einen Platz, an dem die gesamten Ergebnisse abgelegt werden können: wie viele Tests ausgeführt worden sind, welche davon fehlgeschlagen sind und wie viel Zeit sie benötigten. PHPUnit2_Framework_TestResult sammelt die Testresultate. Dabei wird ein einziges PHPUnit2_Framework_TestResult-Objekt durch den gesamten Test-Baum gereicht. Wenn ein Test ausgeführt worden oder gescheitert ist, wird diese Tatsache in PHPUnit2_Framework_TestResult vermerkt. Am Ende des Testlaufs PHPUnit2_Framework_TestResult noch eine Zusammenfassung aller Tests.

Außerdem ist PHPUnit2_Framework_TestResult ein Objekt, das von anderen Objekten beobachtet werden kann, um den Fortschritt des Testvorgangs anzuzeigen. So könnte etwa ein grafischer Testrunner das PHPUnit2_Framework_TestResult-Objekt verfolgen und bei jedem Start eines Tests einen Fortschrittsbalken weiterschalten.

Tabelle 14.8 fasst die Methoden zur Auswertung der Versager und Fehler zusammen.

Wenn Sie ein Objekt als Beobachter eines PHPUnit2_Framework_TestResult registrieren möchten, müssen Sie PHPUnit2_Framework_TestListener implementieren. Um es anzumelden, rufen Sie die in Tabelle 14.9 aufgeführte Methode addListener() auf.

Ein PHPUnit2_Framework_TestListener-Objekt muss die in Tabelle 14.10 aufgeführten Methoden implementieren. Ein Beispiel finden Sie in Beispiel 15.3.

Alle oben genannten Klassen befinden sich in PHPUnit2/Framework. Hier sind alle PHPUnit-Packages:

Fassen Sie Hilfsmethoden in einer abstrakten Kindklasse von PHPUnit2_Framework_TestCase zusammen, und leiten Sie Ihre Testfall-Klassen von dieser Klasse ab. Dies ist eine der einfachsten Möglichkeiten zu einer PHPUnit-Erweiterung.

Legen Sie eigene Klassen mit Zusicherungen für spezielle Zwecke an.

Sie können Testfälle oder Testreihen in einer Kindklasse von PHPUnit2_Extensions_TestDecorator einpacken, damit bestimmte Aktionen vor und nach den Testläufen ausgeführt werden.

PHPUnit bringt zwei fertige Test-Dekorierer mit, PHPUnit2_Extensions_RepeatedTest und PHPUnit2_Extensions_TestSetup. Der erste wird benutzt, um einen Test wiederholt auszuführen und nur dann als Erfolg zu werten, wenn alle Durchläufe erfolgreich waren. Der zweite wurde in Kapitel 5 behandelt.

Beispiel 15.1 zeigt eine verkürzte Fassung des Dekorierers PHPUnit2_Extensions_RepeatedTest. Hier sehen Sie, wie Sie einen eigenen Dekorierer schreiben können.

<?php
require_once 'PHPUnit2/Extensions/TestDecorator.php';
 
class PHPUnit2_Extensions_RepeatedTest extends PHPUnit2_Extensions_TestDecorator {
    private $timesRepeat = 1;
 
    public function __construct(PHPUnit2_Framework_Test $test, $timesRepeat = 1) {
        parent::__construct($test);
 
        if (is_integer($timesRepeat) &&
            $timesRepeat >= 0) {
            $this->timesRepeat = $timesRepeat;
        }
    }
 
    public function countTestCases() {
        return $this->timesRepeat * $this->test->countTestCases();
    }
 
    public function run($result = NULL) {
        if ($result === NULL) {
            $result = $this->createResult();
        }
 
        for ($i = 0; $i < $this->timesRepeat && !$result->shouldStop(); $i++) {
            $this->test->run($result);
        }
 
        return $result;
    }
}
?>

Die Schnittstelle PHPUnit2_Framework_Test ist klein und leicht zu implementieren. Dadurch können Sie beispielsweise einen Test implementieren, der datenbezogene Tests durchführt.

Beispiel 15.2 zeigt eine Implementierung von PHPUnit2_Framework_Test für datenbezogene Tests, bei denen Wertepaare aus einer CSV-Datei (Comma-Separated Values) verglichen werden. Jede Zeile dieser Datei hat die Form foo;bar. Der erste Wert ist der erwartete, der zweite Wert ist der tatsächliche.

<?php
require_once 'PHPUnit2/Framework/Assert.php';
require_once 'PHPUnit2/Framework/Test.php';
require_once 'PHPUnit2/Framework/TestResult.php';
 
class DataDrivenTest implements PHPUnit2_Framework_Test {
    private $lines;
 
    public function __construct($dataFile) {
        $this->lines = file($dataFile);
    }
 
    public function countTestCases() {
        return sizeof($this->lines);
    }
 
    public function run($result = NULL) {
        if ($result === NULL) {
            $result = new PHPUnit2_Framework_TestResult;
        }
 
        $result->startTest($this);
 
        foreach ($this->lines as $line) {
            list($expected, $actual) = explode(';', $line);
 
            try {
                PHPUnit2_Framework_Assert::assertEquals(trim($expected), trim($actual));
            }
 
            catch (PHPUnit2_Framework_ComparisonFailure $e) {
                $result->addFailure($this, $e);
            }
 
            catch (Exception $e) {
                $result->addError($this, $e);
            }
        }
 
        $result->endTest($this);
 
        return $result;
    }
}
 
$test   = new DataDrivenTest('data_file.csv');
$result = $test->run();
 
$failures = $result->failures();
print $failures[0]->thrownException()->toString();
?>

expected: <foo> but was: <bar>

Indem Sie der Methode run() ein spezialisiertes PHPUnit2_Framework_TestResult-Objekt übergeben, können Sie zusätzliche Informationen über die laufenden Tests bekommen.

Sie müssen nicht unbedingt eine komplette Kindklasse von PHPUnit2_Framework_TestResult schreiben. Alternativ können Sie auch einen neuen PHPUnit2_Framework_TestListener implementieren (siehe Tabelle 14.10), den Sie vor der Testausführung bei dem PHPUnit2_Framework_TestResult registrieren.

Beispiel 15.3 zeigt eine einfache Implementierung der Schnittstelle PHPUnit2_Framework_TestListener.

<?php
require_once 'PHPUnit2/Framework/TestListener.php';
 
class SimpleTestListener implements PHPUnit2_Framework_TestListener {
    public function addError(PHPUnit2_Framework_Test $test, Exception $e) {
        printf(
          "Bei der Ausführung des Tests '%s' ist ein Fehler aufgetreten.\n",
          $test->getName()
        );
    }
 
    public function addFailure(PHPUnit2_Framework_Test $test,
                               PHPUnit2_Framework_AssertionFailedError $e) {
        printf(
          "Test '%s' fehlgeschlagen.\n",
          $test->getName()
        );
    }
 
    public function addIncompleteTest(PHPUnit2_Framework_Test $test, Exception $e) {
        printf(
          "Test '%s' ist unvollständig.\n",
          $test->getName()
        );
    }
 
    public function startTest(PHPUnit2_Framework_Test $test) {
        printf(
          "Test '%s' gestartet.\n",
          $test->getName()
        );
    }
 
    public function endTest(PHPUnit2_Framework_Test $test) {
        printf(
          "Test '%s' beendet.\n",
          $test->getName()
        );
    }
 
    public function startTestSuite(PHPUnit2_Framework_TestSuite $suite) {
        printf(
          "TestSuite '%s' gestartet.\n",
          $suite->getName()
        );
    }
 
    public function endTestSuite(PHPUnit2_Framework_TestSuite $suite) {
        printf(
          "TestSuite '%s' beendet.\n",
          $suite->getName()
        );
    }
}
?>

Beispiel 15.4 zeigt, wie Sie Testreihe ausführen und diese Ausführung mit einem SimpleTestListener-Objekt beobachten.

<?php
require_once 'PHPUnit2/Framework/TestResult.php';
require_once 'PHPUnit2/Framework/TestSuite.php';
 
require_once 'ArrayTest.php';
require_once 'SimpleTestListener.php';
 
// PHPUnit2_Framework_TestSuite-Objekt erzeugen,
// das die Tests aus ArrayTest enthält.
$suite = new PHPUnit2_Framework_TestSuite('ArrayTest');
 
// PHPUnit2_Framework_TestResult-Objekt erzeugen und
// ein SimpleTestListener-Objekt als Beobachter registrieren.
$result = new PHPUnit2_Framework_TestResult;
$result->addListener(new SimpleTestListener);
 
// Tests ausführen.
$suite->run($result);
?>

TestSuite 'ArrayTest' gestartet.
Test 'testNewArrayIsEmpty' gestartet.
Test 'testNewArrayIsEmpty' beendet.
Test 'testArrayContainsAnElement' gestartet.
Test 'testArrayContainsAnElement' beendet.
TestSuite 'ArrayTest' beendet.

Um andere Rückmeldungen aus der Testausführung zu erhalten, können Sie einen eigenen Testrunner schreiben. Die abstrakte Basisklasse PHPUnit2_Runner_BaseTestRunner, die auch von PHPUnit2_TextUI_TestRunner (dem textbasierten Testrunner) genutzt wird, kann Ihnen dabei als Ausgangspunkt dienen.