Symfony Tests: Functional Tests effizient schreiben

1. Functional Tests vs. Unit Tests: Wann welcher Typ?

Die Entscheidung zwischen Unit Test und Symfony Functional Test hängt davon ab, was man testen will. Unit Tests prüfen eine einzelne Klasse oder Funktion isoliert von allen Abhängigkeiten – schnell, deterministisch, ohne Datenbank oder HTTP. Functional Tests in Symfony testen das Zusammenspiel mehrerer Komponenten: Controller, Services, Doctrine, Routing, Serializer und Security. Sie sind langsamer, aber sie decken Integrationsfehler auf, die Unit Tests strukturell nicht erkennen können.

Die praktische Faustregel: Unit Tests für Business-Logik in Services und Value Objects. Symfony Functional Tests für HTTP-Endpunkte, Datenbankoperationen, Authentifizierungsflows und Berechtigungsprüfungen. Eine häufige Falle ist das Schreiben von Functional Tests für Logik, die besser als Unit Test abgedeckt wäre – und umgekehrt das Schreiben von Unit Tests für Controller-Logik, die eigentlich den gesamten HTTP-Stack braucht, um sinnvoll getestet zu werden. Ein Functional Test, der einen Controller testet, der eine Validation-Gruppe auswertet und dann einen Service aufruft, prüft die echte Integration und nicht einen gemockten Ablauf.

2. WebTestCase: HTTP-Requests simulieren

WebTestCase ist die Basisklasse für Symfony Functional Tests, die HTTP-Requests simulieren. Die createClient()-Methode erstellt einen Browser-ähnlichen Client, der Symfony-Routes aufruft, den vollen Request-Lifecycle durchläuft – inklusive Security, Middleware, Controller und Response – und das Ergebnis zur Prüfung bereithält. Der entscheidende Vorteil: Der Test läuft vollständig im PHP-Prozess ohne einen echten HTTP-Server. Das macht ihn schneller als echte HTTP-Requests und erlaubt direkten Zugriff auf den Symfony-Container für Setup und Assertions.

Die $client->request()-Methode sendet HTTP-Requests mit beliebigen Methoden, Headers und Body-Daten. Nach dem Request gibt $client->getResponse() das Response-Objekt zurück: Status-Code, Headers und Body. Die Crawler-Klasse, die von $client->getCrawler() zurückgegeben wird, ermöglicht CSS-Selector-basierte Suche im HTML-Body. Für JSON-API-Tests verwendet man direkt den Response-Body: json_decode($client->getResponse()->getContent(), true). Symfony Functional Tests mit WebTestCase testen damit die gesamte HTTP-Ebene der Anwendung.

<?php

declare(strict_types=1);

namespace App\Tests\Controller\Api;

use App\Entity\Product;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

/**
 * Functional tests for the Product API endpoint.
 * Tests the full HTTP lifecycle including routing, security and serialization.
 */
final class ProductApiTest extends WebTestCase
{
    public function testGetProductReturnsCorrectJsonStructure(): void
    {
        $client = static::createClient();

        // Arrange: create a product in the test database
        $entityManager = static::getContainer()->get(EntityManagerInterface::class);
        $product = new Product();
        $product->setName('Test Laptop');
        $product->setPrice('999.99');
        $entityManager->persist($product);
        $entityManager->flush();

        // Act: send GET request to the API endpoint
        $client->request('GET', '/api/products/' . $product->getId(), [], [], [
            'HTTP_ACCEPT' => 'application/json',
        ]);

        // Assert: verify response structure and content
        self::assertResponseIsSuccessful();
        self::assertResponseHeaderSame('Content-Type', 'application/json');

        $data = json_decode($client->getResponse()->getContent(), true, 512, JSON_THROW_ON_ERROR);

        self::assertArrayHasKey('id', $data);
        self::assertArrayHasKey('name', $data);
        self::assertSame('Test Laptop', $data['name']);
        self::assertSame('999.99', $data['price']);
    }

    public function testNonExistentProductReturns404(): void
    {
        $client = static::createClient();
        $client->request('GET', '/api/products/99999');

        self::assertResponseStatusCodeSame(404);
    }
}

3. KernelTestCase: Services direkt testen

KernelTestCase bootet den Symfony-Kernel, ohne einen HTTP-Client zu starten. Das ist die richtige Wahl für Symfony Functional Tests, die Services oder Repositories direkt testen wollen, ohne den HTTP-Stack zu involvieren. Typische Anwendungsfälle: einen Service testen, der Datenbankoperationen durchführt, einen Messenger-Handler mit echten Abhängigkeiten testen oder ein Repository gegen eine echte Testdatenbank prüfen. static::getContainer()->get(ServiceClass::class) liefert den Service aus dem Test-Container inklusive aller realen Abhängigkeiten.

Ein wichtiger Unterschied zu Unit Tests: Im KernelTestCase sind alle Services mit ihren echten Implementierungen vorhanden – keine Mocks, keine Stubs, sofern nicht explizit konfiguriert. Das bedeutet, dass der Test das echte Symfony-Security-System, das echte Doctrine und alle echten Service-Abhängigkeiten verwendet. Für Symfony Functional Tests auf Service-Ebene ist das genau richtig: Man testet, ob die Komponenten korrekt zusammenarbeiten, nicht ob die Komponenten isoliert das Richtige tun.

4. Datenbankisolation: Fixtures und Transaktionen

Datenbankisolation ist das kritischste Thema für zuverlässige Symfony Functional Tests. Ohne Isolation hinterlässt jeder Test Daten in der Testdatenbank, die nachfolgende Tests beeinflussen. Das führt zu Flaky Tests: Tests, die manchmal bestehen und manchmal nicht, je nachdem in welcher Reihenfolge sie ausgeführt werden. Die robusteste Lösung ist die Transaktionsstrategie: Jeder Test läuft innerhalb einer Transaktion, die am Ende zurückgerollt wird. So ist die Datenbank nach jedem Test in demselben Zustand wie davor – ohne Datenbank-Leeren oder Fixtures-Neuladen.

Für Symfony Functional Tests, die Fixtures brauchen, ist das DoctrineFixturesBundle die Standardlösung. Fixtures sind PHP-Klassen, die Testdaten in die Datenbank laden. Mit dem ResetDatabase-Trait aus Zenstruck\Foundry oder dem manuellen Aufruf von bin/console doctrine:fixtures:load --env=test vor jedem Test lädt man definierte Testdaten. Für Performance besser: eine SQLite-In-Memory-Datenbank für Tests konfigurieren, die bei jedem Test-Run neu erstellt wird und dramatisch schneller ist als MySQL/PostgreSQL für isolierte Tests.

<?php

declare(strict_types=1);

namespace App\Tests\Controller;

use App\Entity\User;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;

/**
 * Base test class providing common setup for authenticated functional tests.
 * Uses database transactions for isolation — rolled back after each test.
 */
abstract class AbstractWebTestCase extends WebTestCase
{
    protected static function createAuthenticatedClient(
        string $email = 'test@example.com',
        string $role = 'ROLE_USER',
    ): \Symfony\Bundle\FrameworkBundle\KernelBrowser {
        $client = static::createClient();

        // Create a test user directly in the database
        $container = static::getContainer();
        $em        = $container->get(EntityManagerInterface::class);
        $hasher    = $container->get(UserPasswordHasherInterface::class);

        $user = new User();
        $user->setEmail($email);
        $user->setRoles([$role]);
        $user->setPassword($hasher->hashPassword($user, 'test_password_123'));

        $em->persist($user);
        $em->flush();

        // Authenticate via session — no real HTTP login needed in tests
        $client->loginUser($user);

        return $client;
    }

    protected function assertJsonResponse(
        \Symfony\Component\HttpFoundation\Response $response,
        int $statusCode = 200,
    ): array {
        self::assertResponseStatusCodeSame($statusCode);
        self::assertResponseHeaderSame('Content-Type', 'application/json');

        return json_decode($response->getContent(), true, 512, JSON_THROW_ON_ERROR);
    }
}

5. Authentifizierte Requests effizient schreiben

Authentifizierungslogik vor jeden Symfony Functional Test zu setzen – Login-Formular aufrufen, Credentials senden, Session-Cookie verfolgen – ist langsam und fehleranfällig. Symfony bietet seit Version 5.1 die Methode $client->loginUser($user), die einen Benutzer direkt in die Session schreibt, ohne einen echten Login-Request zu senden. Das ist der empfohlene Weg für alle Functional Tests, die Authentifizierung benötigen: Es spart mehrere HTTP-Requests pro Test und macht die Tests robuster gegenüber Änderungen am Login-Formular.

Für API-Tests mit JWT-Authentifizierung generiert man direkt im Test ein gültiges Token, ohne den OAuth-Flow zu durchlaufen: Der JWT-Service wird aus dem Container geholt und mit einem Test-Benutzer-Objekt aufgerufen. Das Token wird als Authorization: Bearer-Header in den Request gesetzt. Diese Strategie ist erheblich schneller als echte Token-Anfragen und stellt sicher, dass der Test deterministisch ist – der Test ist unabhängig von externen OAuth-Servern und Token-Ablaufzeiten.

6. REST-API-Endpunkte systematisch testen

Für Symfony Functional Tests von REST-API-Endpunkten empfiehlt sich eine systematische Testmatrix: Für jeden Endpunkt testet man den Happy Path (korrekte Anfrage, erwartete Antwort), Fehlerszenarien (fehlende Felder, falsche Typen), Autorisierungsszenarien (unauthentifiziert, falsche Rolle, fremde Ressource) und Edge Cases (leere Listen, Grenzwerte). Diese Matrix wird in separaten Testmethoden oder mit PHPUnit Data Providers abgedeckt.

Für POST/PUT-Requests testet man sowohl erfolgreiche Erstellung/Aktualisierung als auch Validierungsfehler. Ein Symfony Functional Test, der einen POST-Request mit fehlenden Pflichtfeldern sendet, erwartet eine 422-Antwort mit einer strukturierten Fehlerliste. Der Test prüft nicht nur den Status-Code, sondern auch den Fehlertyp und die betroffenen Felder – so stellt er sicher, dass die API aussagekräftige Fehlermeldungen für API-Clients zurückgibt und nicht nur einen generischen 400-Fehler.

<?php

declare(strict_types=1);

namespace App\Tests\Controller\Api;

use App\Tests\Controller\AbstractWebTestCase;

/**
 * Systematic REST API functional tests — covers happy paths, validation and auth.
 */
final class CreateProductTest extends AbstractWebTestCase
{
    public function testAdminCanCreateProduct(): void
    {
        $client = static::createAuthenticatedClient(role: 'ROLE_ADMIN');

        $client->request('POST', '/api/products', [], [], [
            'CONTENT_TYPE' => 'application/json',
            'HTTP_ACCEPT'  => 'application/json',
        ], json_encode([
            'name'  => 'New Laptop',
            'price' => 1299.99,
        ], JSON_THROW_ON_ERROR));

        $data = $this->assertJsonResponse($client->getResponse(), 201);

        self::assertArrayHasKey('id', $data);
        self::assertSame('New Laptop', $data['name']);
    }

    public function testUnauthenticatedUserCannotCreateProduct(): void
    {
        $client = static::createClient();

        $client->request('POST', '/api/products', [], [], [
            'CONTENT_TYPE' => 'application/json',
        ], json_encode(['name' => 'Laptop', 'price' => 999.99], JSON_THROW_ON_ERROR));

        self::assertResponseStatusCodeSame(401);
    }

    /**
     * @dataProvider provideInvalidProductData
     */
    public function testValidationErrorsReturn422(array $payload, string $expectedField): void
    {
        $client = static::createAuthenticatedClient(role: 'ROLE_ADMIN');

        $client->request('POST', '/api/products', [], [], [
            'CONTENT_TYPE' => 'application/json',
        ], json_encode($payload, JSON_THROW_ON_ERROR));

        $data = $this->assertJsonResponse($client->getResponse(), 422);

        // Assert that the validation error mentions the expected field
        self::assertStringContainsString($expectedField, json_encode($data));
    }

    public static function provideInvalidProductData(): array
    {
        return [
            'missing name'     => [['price' => 9.99], 'name'],
            'negative price'   => [['name' => 'Laptop', 'price' => -10], 'price'],
            'empty name'       => [['name' => '', 'price' => 9.99], 'name'],
            'price zero'       => [['name' => 'Laptop', 'price' => 0], 'price'],
        ];
    }
}

7. Aussagekräftige Assertions und Custom Matchers

Die Qualität von Symfony Functional Tests hängt stark von der Aussagekraft der Assertions ab. Eine Assertion wie self::assertSame(200, $statusCode) gibt bei einem Fehler nur eine Zahl als Information. self::assertResponseIsSuccessful() aus WebTestCase gibt bei einem Fehler den tatsächlichen Status-Code und den Response-Body als Debug-Information aus – das macht die Fehlersuche erheblich schneller. Symfony liefert viele solcher semantisch aussagekräftigen Assertions: assertResponseRedirects(), assertSelectorTextContains(), assertResponseHeaderSame().

Für projektspezifische Assertions lohnt sich die Erstellung einer Basisklasse mit eigenen Assertion-Methoden. Eine Methode assertApiViolation(string $field, string $message) prüft, ob eine Validierungsverletzung für ein bestimmtes Feld mit der erwarteten Nachricht vorliegt. Eine Methode assertPaginatedResponse(int $totalItems) prüft die Struktur und Zählung einer paginierten API-Antwort. Solche Custom Assertions reduzieren Code-Duplikation in der Testsuite erheblich und machen Tests lesbarer.

8. Testperformance: Schnelle Feedback-Loops

Langsame Symfony Functional Tests sind ein häufiges Problem in gewachsenen Projekten: Eine Testsuite, die 10 Minuten läuft, wird vor jedem Commit nicht ausgeführt – und das Sicherheitsnetz wird zum Theater. Die wichtigsten Performance-Hebel: SQLite statt MySQL/PostgreSQL für Tests, die keine MySQL-spezifischen Features benötigen. SQLite-In-Memory-Datenbanken starten sofort und sind nach jedem Test-Lauf neu. Transaktionen statt Fixtures-Reload für Datenbankisolation – eine Transaktion zurückrollen ist hundertmal schneller als alle Tabellen zu leeren und Fixtures neu zu laden.

Parallelisierung mit paratest teilt die Testsuite auf mehrere CPU-Kerne auf und reduziert die Gesamtlaufzeit linear. Aber Parallelisierung verlangt, dass Symfony Functional Tests wirklich isoliert sind – keine globalen Zustände, keine freigegebenen Testdatenbank-Einträge, keine Abhängigkeiten zwischen Tests. Das ist eine weitere Motivation für saubere Datenbankisolation: Sie ist die Voraussetzung für parallele Test-Ausführung und damit für die schnellsten möglichen Feedback-Loops.

9. Teststrategie-Vergleich: Symfony-Testtypen

Symfony unterstützt verschiedene Testtypen, die zusammen eine vollständige Teststrategie bilden. Der folgende Vergleich hilft, die richtige Wahl für jeden Testfall zu treffen.

Die optimale Testsuite für ein Symfony-Projekt folgt der Testpyramide: viele schnelle Unit Tests als Basis, eine mittlere Schicht aus Functional Tests für HTTP-Endpunkte und eine kleine Spitze aus E2E-Tests für kritische User-Flows. Symfony Functional Tests mit WebTestCase sind der wichtigste Baustein für API-Projekte – sie decken das ab, was Unit Tests nicht können: die korrekte Integration aller Schichten von Routing bis Datenbankpersistenz.

10. Zusammenfassung

Symfony Functional Tests sind das wichtigste Qualitätswerkzeug für HTTP-API-Projekte. WebTestCase simuliert vollständige HTTP-Requests inklusive Routing, Security und Serialisierung. KernelTestCase testet Services direkt ohne HTTP-Overhead. Datenbankisolation durch Transaktionen oder SQLite-In-Memory verhindert Flaky Tests. $client->loginUser() setzt Authentifizierung ohne Login-Requests. Data Providers und systematische Testmatrizen decken Happy Paths, Validierungsfehler und Autorisierungsszenarien vollständig ab.

Der wichtigste Grundsatz für nachhaltige Symfony Functional Tests: Jeder Test muss isoliert, deterministisch und schnell sein. Isoliert bedeutet: kein Test hinterlässt Daten, die einen anderen Test beeinflussen. Deterministisch bedeutet: derselbe Test liefert in beliebiger Reihenfolge immer dasselbe Ergebnis. Schnell bedeutet: die gesamte Testsuite läuft unter 2 Minuten, damit sie vor jedem Push ausgeführt wird. Diese drei Eigenschaften zusammen machen Functional Tests zum zuverlässigen Sicherheitsnetz, das sie sein sollen.

11. FAQ: Symfony Functional Tests