Přeskočit na obsah
iD-SIGN
Ptejte se

E2E testy Symfony s Pantherem

Panther pouští testy Symfony ve skutečném Chrome. Ukážeme, co plyne z toho, že aplikace běží v jiném procesu než test, jak spolehlivě čekat na htmx, React i Vue a jak sadu rozjet v CI, aby nepadala náhodně.

13 min čtenívydáno 11/2026

V tomto článku 12 kapitol
  1. Kdy E2E test
  2. Co Panther testuje a co ne
  3. Instalace a prohlížeč
  4. Dva procesy
  5. Vestavěný, nebo skutečný server
  6. Co Panther neumí
  7. Čekání
  8. JavaScript v prohlížeči
  9. Nahrávání souborů
  10. Ladění
  11. CI
  12. Panther, nebo jiný nástroj

Panther ovládá skutečný prohlížeč přes WebDriver a v testu nabízí stejné API jako WebTestCase: request(), crawler, formuláře, klikání. Rozdíl je v tom, že stránku vykreslí Chrome, spustí se JavaScript a test vidí to, co uživatel.

Za to se platí rychlostí a novou třídou chyb. Aplikace neběží v procesu testu, na nic se nečeká samo a chyba v testu se snadno tváří jako chyba aplikace. Tady je, co jsme se naučili a co jsme si ověřili.

Kdy E2E test

Panther patří jen na to, co bez prohlížeče otestovat nejde:

  • interakce v JavaScriptu (htmx, Alpine.js, Stimulus, React, Vue),
  • celé cesty uživatele přes víc stránek: registrace, nákup, platba, návrat z brány,
  • chování, které závisí na vykreslení: viditelnost, překryvy, posun stránky.

Validaci formulářů, oprávnění, odpovědi fragmentů a API testujte ve WebTestCase. Běží v procesu testu a je řádově rychlejší. E2E sadu držte u kritických cest.

Co Panther testuje a co ne

Prohlížeč je skutečný: Chrome v režimu headless, se stejným vykreslováním a stejným JavaScriptem jako u uživatele. Kliknutí a psaní přes WebDriver jsou pro stránku skutečné události (isTrusted je true) a WebDriver klikne jen tam, kam by klikl člověk. Kliknutí přes executeScript() skutečné není a tuhle kontrolu obchází.

Prostředí kolem prohlížeče se ale od uživatele liší:

  • Jeden prohlížeč a jedno okno. Chrome, případně Firefox, o velikosti 1200 × 900 bez dotyku. Safari ani telefony ne. Mobilní rozložení otestujete jen s nastavenou velikostí okna.
  • Prohlížeč se prozrazuje. navigator.webdriver je true a user-agent obsahuje HeadlessChrome. Ochranu proti botům (reCAPTCHA, Cloudflare) v testovacím prostředí vypněte nebo nahraďte dvojníkem.
  • Čistý profil bez rozšíření a s jazykem en-US, pokud ho nenastavíte.
  • Vypnuté animace přes prefers-reduced-motion.
  • Okamžité psaní bez lidského tempa.
  • Testovací svět: prostředí test, místní síť bez latence, zmrazený čas, falešné platební brány a registry.

A některé věci test neověří vůbec: že stránka dobře vypadá (rozjeté rozložení nebo překrytý text, na který se test neptá, projdou), přístupnost a rychlost. Panther ověří, že aplikace v Chrome funguje z pohledu uživatele, ne že funguje všude a dobře vypadá.

Instalace a prohlížeč

bash
composer require --dev symfony/panther

Panther potřebuje Chrome (nebo Firefox) a k němu chromedriver stejné hlavní verze. Nesoulad skončí hned při startu: session not created: This version of ChromeDriver only supports Chrome version ….

  • Chromedriver Panther hledá nejdřív v PATH, teprve potom v ./drivers. Driver stažený přes dbrekelmans/bdi do ./drivers tak přebije starší systémový chromedriver, který přišel s balíčkem. Držte jeden zdroj: buď systémové balíčky prohlížeče i driveru (chromium a chromium-driver), nebo bdi a v PATH žádný driver.
  • Jiný prohlížeč nastavíte v PANTHER_CHROME_BINARY. Proměnná pro cestu k driveru neexistuje.
  • V kontejneru Chrome běží pod rootem a s malým /dev/shm, takže potřebuje PANTHER_NO_SANDBOX=1 a --disable-dev-shm-usage.

Do phpunit.dist.xml patří rozšíření, které drží server a prohlížeč po celou dobu běhu, ne jen jedné třídy:

xml
<extensions>
    <bootstrap class="Symfony\Component\Panther\ServerExtension" />
</extensions>

A do .env.test:

bash
PANTHER_APP_ENV=test
PANTHER_NO_SANDBOX=1
PANTHER_CHROME_ARGUMENTS='--disable-dev-shm-usage'
PANTHER_ERROR_SCREENSHOT_DIR=./var/error-screenshots

E2E testy dejte do vlastní sady (<testsuite name="e2e">), ať jdou spouštět zvlášť a běžné testy na prohlížeč nečekají. Jak to celé rozjet v DDEV, popisujeme v článku Lokální vývoj Symfony v DDEV.

Dva procesy

Tohle je nejdůležitější věc celého článku. Kliknutí v Pantheru není žádná zkratka přes kernel, je to skutečný HTTP požadavek:

  1. Test pošle chromedriveru příkaz WebDriveru: klikni na tento prvek.
  2. Chrome klikne, spustí se JavaScript stránky a prohlížeč pošle HTTP požadavek se svými hlavičkami a cookies.
  3. Požadavek přijme webserver v jiném procesu: vestavěný server PHP, který Panther spustí na portu 9080, nebo skutečný webserver, když nastavíte PANTHER_EXTERNAL_BASE_URI.
  4. Ten spustí public/index.php, Symfony nabootuje kernel a požadavek vyřídí jako na produkci. Každý požadavek je samostatné spuštění PHP.
  5. Odpověď vykreslí Chrome a test čte výsledný DOM přes WebDriver.

I $client->request() je jen pokyn prohlížeči, ať otevře adresu. KernelBrowser ve WebTestCase naopak žádný HTTP neposílá: vyrobí objekt Request a předá ho kernelu ve stejném procesu. Proto je rychlý a vidí do kontejneru.

Kernel, který Panther bootuje v procesu testu, slouží jen testu: getContainer(), EntityManager pro fixtures a kontroly v databázi. Na požadavky prohlížeče nemá vliv. Test i server mají každý svůj kontejner služeb, svůj EntityManager a své připojení k databázi.

Z toho plyne:

  • self::getContainer()->set() na server nedosáhne. Testovací dvojník, třeba falešná platební brána, musí být zapojený v konfiguraci prostředí test (config/packages/test/services.yaml). Služba definovaná v config/services.yaml se načítá později a alias by přebila, proto dvojníka zapojte přes decorates.
  • Stav si procesy předávají přes databázi nebo soubory. Co má falešná brána odpovědět, zapíše test do souboru ve var/cache/test/ a dvojník na serveru ho přečte.
  • Data musí být potvrzená. Co test zapíše a flushne, server vidí. Co je v nepotvrzené transakci, nevidí.
  • DAMA DoctrineTestBundle s Pantherem nefunguje. Obaluje test transakcí, kterou na konci vrátí. Server data z testu nevidí, a když test změní řádek, který server potom zapisuje, server čeká na zámek až do konce testu. E2E sadu proto pouštějte bez rozšíření DAMA a databázi resetujte jinak (níže).
  • Asserce maileru (assertEmailCount() a další) napočítají nulu. Čtou zprávy odeslané v procesu testu, ne na serveru. Odeslané e-maily si aplikace v testovacím prostředí může ukládat do tabulky a test se zeptá tam, nebo je čtěte z API Mailpitu.
  • Zmrazený čas platí zvlášť pro každý proces. MockClock z konfigurace prostředí test zmrazí čas na serveru i v testu. Posun hodin v testu ale server neuvidí. Situace „za 14 dní“ proto vyřešíte tak, že cron pustíte v procesu testu s posunutými hodinami proti sdílené databázi. Prohlížeč přitom dál žije ve zmrazeném dni.

Databáze

Osvědčený postup:

  1. Schéma jednou na začátku sady. PHPUnit rozšíření na události startu sady smaže databázi, pustí migrace a naplní data, která obstarávají migrace nebo synchronizace (číselníky, texty CMS).
  2. Fixtures pro každou třídu v setUpBeforeClass() přímo přes loader fixtures, ne voláním konzole. Je to rychlejší.
  3. Tabulky naplněné migracemi z mazání vynechte. ORMPurger dostane seznam tabulek, které má nechat být. Jinak po prvním purge chybí konfigurace, bez které aplikace nefunguje.
  4. Testy uvnitř třídy si stav vyrábějí přes aplikaci (registrace, nákup) a s unikátními e-maily. Na pořadí testů nespoléhejte.

Vestavěný, nebo skutečný server

Vestavěný server PHP je nejjednodušší cesta. Statické soubory ale vydá jen z public/, takže assety musí být sestavené předem (npm run build, asset-map:compile). Neuplatní se ani konfigurace nginx, HTTPS a hlavičky.

S PANTHER_EXTERNAL_BASE_URI testy jedou proti skutečnému webserveru, stejnou cestou jako produkce. Ten musí sám běžet v APP_ENV=test s testovací databází. Osvědčila se druhá adresa projektu, třeba test.projekt.ddev.site, kde webserver předává PHP APP_ENV=test, zatímco hlavní adresa dál slouží vývoji.

  • Před sadou zahřejte workery PHP-FPM několika souběžnými požadavky na testovací adresu. Studený worker načítá kontejner a první testy pak náhodně padají na timeoutu.
  • Ani jeden server neodhalí chyby worker módu (FrankenPHP, RoadRunner). Služba, která si drží stav mezi požadavky, se v testech chová správně a v produkci ne. To hlídejte jinak, třeba kontrolou ResetInterface u služeb se stavem.

Co Panther neumí

Klient vypadá jako KernelBrowser, ale ne všechno funguje:

  • request() pošle jen GET. Formulář odešlete přes crawler nebo kliknutím.
  • getResponse() a asserce odpovědi (assertResponseIsSuccessful(), assertResponseStatusCodeSame()) skončí výjimkou. Stavový kód v prohlížeči nevidíte, kontrolujte obsah stránky.
  • text() vrací jen viditelný text. Skrytý prvek vrátí prázdný řetězec. Titulek stránky dá $client->getTitle().
  • loginUser() neexistuje. Server o session testu nic neví. Přihlaste se skutečným formulářem, jednou pro třídu.
  • Klient je jeden pro celý běh. Druhé volání createPantherClient() vrátí stejný prohlížeč a nové volby ignoruje. Cookies, localStorage i přihlášení přežijí do dalšího testu.
  • Cookie jde nastavit až na stránce z dané domény, jinak InvalidCookieDomainException.

Stav mezi testy proto vyčistěte v základní třídě:

php
abstract class E2ETestCase extends PantherTestCase
{
    protected function tearDown(): void
    {
        $client = static::createPantherClient();
        $client->getWebDriver()->manage()->deleteAllCookies();

        try {
            $client->executeScript('localStorage.clear(); sessionStorage.clear();');
        } catch (\Throwable) {
            // stránka bez úložiště, třeba about:blank
        }

        parent::tearDown();
    }
}

Čekání

Panther nečeká sám. Asserce hned po akci čte stránku v tu chvíli a většina náhodně padajících testů vzniká právě tady.

  • submit() ani click() na navigaci nečekají. Crawler vrácený hned po odeslání formuláře je ještě stará stránka. Počkejte na něco, co je jen na cílové stránce, nebo na změnu adresy.
  • Čekejte na výsledný stav, ne na přechodný indikátor. Spinner nebo aria-busy se může objevit až po vaší kontrole, nebo zmizet dřív, než se podíváte.
  • Žádné sleep(). Na pomalém stroji nestačí, na rychlém zdržuje. Výjimkou je čekání, které aplikace vyžaduje záměrně, třeba časová past formuláře proti botům.
  • Výchozí timeout je 30 sekund. Každé selhání pak stojí půl minuty. Pro běžné prvky stačí pár sekund: waitFor('#result', 5).

Panther má sadu waitFor* a asercí assertSelectorWill*:

php
$client->waitFor('#result');                          // prvek existuje
$client->waitForVisibility('#modal');                 // je vidět
$client->waitForInvisibility('.spinner');             // zmizel, nebo neexistuje
$client->waitForElementToContain('#total', '1 200');  // obsahuje text
$client->waitForStaleness('#list');                   // tento prvek byl nahrazen
self::assertSelectorWillContain('#flash', 'Uloženo');

waitForStaleness() nejdřív prvek najde. Když už neexistuje, hned vyhodí NoSuchElementException. Na mizející prvek je bezpečnější waitForInvisibility(), které projde i u chybějícího prvku.

Na cokoli dalšího stačí vlastní podmínka:

php
use Facebook\WebDriver\WebDriverExpectedCondition;

$client->wait(10)->until(WebDriverExpectedCondition::urlContains('/platba/uspech'));
$client->wait(5)->until(fn () => true === $client->executeScript('return window.appReady'));

Po každém čekání čtěte crawler znovu ($client->getCrawler() nebo crawler, který vrátí waitFor*). Starý odráží stav před změnou.

JavaScript v prohlížeči

Společné pro všechny knihovny: obsah, který přijde ze sítě, se objeví později, než skončí klik. Hned po kliknutí na tlačítko, které načítá data, je výsledek ještě prázdný. Rozdíly jsou v tom, na co se dá čekat a jak se vyplňují pole.

htmx

  • Během požadavku má spouštěcí prvek třídu htmx-request, ne atribut. Selektor [hx-request] nenajde nic a čekání na něj potichu nečeká.
  • htmx:after:request přichází před swapem. Po swapu přicházejí htmx:after:swap, htmx:after:settle a nakonec htmx:finally:request, který přijde i po chybě.
  • Posluchač zapněte dřív, než akci spustíte, ideálně ve stejném skriptu. Zapnutý až po kliknutí může rychlou odpověď v principu propásnout.
php
protected function runHtmx(string $trigger, int $timeout = 10): void
{
    $client = static::createPantherClient();
    $client->executeScript(<<<JS
        window.__htmxDone = false;
        document.addEventListener('htmx:finally:request', () => { window.__htmxDone = true; }, { once: true });
        {$trigger}
        JS);
    $client->wait($timeout, 100)->until(fn () => true === $client->executeScript('return window.__htmxDone'));
}

$this->runHtmx('document.querySelector("#apply-code").click();');
  • Morph ponechá hodnotu pole, které má fokus. Když formulář odešlete Enterem, pole s kurzorem po morphu ukazuje, co uživatel napsal, ne hodnotu ze serveru. Uložený stav proto ověřte čerstvým načtením stránky, ne čtením morphnutého formuláře.
  • Odpovědi fragmentů a hx-swap-oob stačí otestovat ve WebTestCase s hlavičkou HX-Request. V Pantheru jen to, že se swap v prohlížeči opravdu stane.

Jak htmx v Symfony nasadit, popisujeme v seriálu, který začíná článkem Navigace v Symfony s htmx.

React

  • Komponenta se připojí až po načtení stránky. request() vrátí stránku, ve které obsah komponenty ještě není. Před první akcí počkejte na prvek uvnitř komponenty.
  • Psaní přes sendKeys() funguje, i přes formulářové API Pantheru. WebDriver posílá skutečné události klávesnice.
  • Hodnota nastavená skriptem nefunguje. React u řízeného pole ignoruje el.value = … i s následnou událostí input. Projde jen nativní setter a událost:
php
$client->executeScript(<<<'JS'
    const input = document.querySelector(arguments[0]);
    Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set.call(input, arguments[1]);
    input.dispatchEvent(new Event('input', { bubbles: true }));
    JS, ['#email', 'jana@example.test']);

U textarea je to HTMLTextAreaElement.prototype. Kde to jde, dejte přednost sendKeys().

  • Po novém vykreslení prvky zastarají. Uložený prvek i uložený crawler po přemountování komponenty vyhodí StaleElementReferenceException. Prvky neukládejte přes akci a po ní je vyhledejte znovu.

Vue a Alpine.js

  • v-model i x-model poslouchají událost input. Na rozdíl od Reactu tu stačí el.value = … a dispatchEvent(new Event('input', { bubbles: true })). Samotné el.value bez události nestačí nikde.
  • v-model.lazy aktualizuje model až na change, tedy po opuštění pole. Po sendKeys() je model pořád prázdný, dokud nepošlete WebDriverKeys::TAB nebo nekliknete jinam. Totéž platí pro vlastní posluchače @change.

Routování v prohlížeči

Přechod přes history.pushState() není načtení stránky. getCurrentURL() novou adresu vrátí, ale waitFor na ni nečeká. Počkejte na adresu a pak na obsah nové obrazovky:

php
$client->getCrawler()->filter('#detail-link')->click();
$client->wait(5)->until(WebDriverExpectedCondition::urlContains('/detail'));
$client->waitFor('#detail-title');

Čítač požadavků

Obecný čítač fetch (obalený window.fetch s počitadlem) říká, že doběhla síť, ne že se vykreslil výsledek. Mezi odpovědí a vykreslením je ještě čtení JSON a změna stavu. Hodí se jako doplněk, ale spolehlivější je čekat na výsledek v DOM.

Kliknutí, překryvy a skrytá pole

  • Překrytý prvek hlásí ElementClickInterceptedException. WebDriver klikne jen tam, kam by klikl uživatel. Počkejte, až překryv zmizí (waitForInvisibility('.modal-backdrop')).
  • Vizuálně skryté pole (checkbox s třídou sr-only pod vlastní grafikou) hlásí totéž. Klikněte na jeho label, nebo ho přepněte skriptem.
  • Tlačítko pod okrajem okna WebDriver občas hlásí jako překryté, i když není. Pomůže scrollIntoView({ block: 'center' }) nebo klik skriptem.
  • Klik skriptem vědomě obchází kontrolu, že prvek jde opravdu kliknout. Používejte ho tam, kde víte proč, a napište to do komentáře.
  • form.submit() nespustí událost submit. Když token CSRF nebo jiná data doplňuje JavaScript až při odeslání, formulář odešle prázdné. Použijte form.requestSubmit() nebo skutečný klik.
  • Panther zapíná prefers-reduced-motion. Animace a plynulý posun, které ho respektují, v testech nepřekáží. Ty, které ho ignorují, způsobují zachycené kliky.

Dialogy confirm()

Po kliknutí na prvek, který otevře confirm(), Panther hned čte stránku a narazí na UnexpectedAlertOpenException. Klikněte přímo na prvek WebDriveru a dialog obslužte:

php
$crawler->filter('#delete')->getElement(0)->click();
$client->wait(5)->until(WebDriverExpectedCondition::alertIsPresent());
$client->getWebDriver()->switchTo()->alert()->accept();
$client->refreshCrawler();

Týká se to i hx-confirm a data-turbo-confirm, pokud používají nativní dialog.

Nahrávání souborů

Soubor do pole nevybírá dialog, WebDriver poli rovnou předá cestu. Ve formuláři stačí formulářové API, které si poradí i s relativní cestou:

php
$form = $crawler->filter('#document-form')->form();
$form['doc']->upload(__DIR__.'/../fixtures/smlouva.pdf');
$client->submit($form);
$client->waitFor('#uploaded');

Mimo formulář, třeba u pole odesílaného přes htmx, pošlete cestu přímo:

php
$crawler->filter('#doc')->sendKeys(realpath(__DIR__.'/../fixtures/smlouva.pdf'));
  • Cesta pro sendKeys() musí být absolutní, jinak path is not absolute.
  • Víc souborů do pole s multiple pošlete jedním voláním, cesty oddělte novým řádkem.
  • Skryté pole pod vlastním tlačítkem nebo dropzone (display: none) soubor přijme. Na rozdíl od skrytého checkboxu nic obcházet nemusíte. Přetažení souboru z disku WebDriver neumí, soubor proto pošlete do <input type="file">, které má dropzone pod sebou.
  • Soubor musí existovat na stroji, kde běží prohlížeč. Když běží ve stejném kontejneru jako testy, stačí fixtures v repozitáři.
  • Validaci na serveru (velikost, typ, chybové hlášky) testujte ve WebTestCase s UploadedFile. Je rychlejší a podstrčíte v něm i soubor, který by prohlížeč neposlal. V Pantheru nechte výběr souboru, náhled a výsledek v prohlížeči.

Ladění

  • Snímek obrazovky při selhání uloží Panther do PANTHER_ERROR_SCREENSHOT_DIR při neprošlé asserci i při výjimce, třeba timeoutu waitFor. V CI ho uložte jako artefakt.
  • Konzole prohlížeče. Timeout na waitFor často znamená chybu v JavaScriptu, kvůli které prvek nikdy nevznikne. Zapněte záznam konzole a v tearDown ho vypište:
php
$client = static::createPantherClient([], [], [
    'capabilities' => ['goog:loggingPrefs' => ['browser' => 'ALL']],
]);

foreach ($client->getWebDriver()->manage()->getLog('browser') as $entry) {
    fwrite(STDERR, $entry['level'].' '.$entry['message'].PHP_EOL);
}
  • Pomocné metody sdílejte. Přihlášení, čekání na htmx, vyplnění formuláře administrace, odkaz z odeslaného e-mailu: když si je každý test píše sám, každá kopie chybuje jinak. Chybná kopie navíc může projít, protože nic nekontroluje. Pomocník na čekání se špatným selektorem tiše nečeká a test jen zpomalí.

CI

  • Image s PHP, Chromiem a chromedriverem z téhož zdroje. Debian s balíčky chromium a chromium-driver má verze vždy v páru.
  • Databáze jako služba jobu, se stejnými přístupy jako v .env.test, ať nemusíte nic přepisovat.
  • Před testy sestavit assety, cache:warmup --env=test a počkat, až databáze odpovídá.
  • Časové pásmo nastavte jako v produkci. Image bez nastavení běží v UTC a zmrazený čas s posunem +02:00 pak dá jiné „dnes“ než prohlížeč.
  • Snímky při selhání a log serveru uložte jako artefakty jobu (when: on_failure).
  • Souběžné běhy potřebují vlastní porty. Server (9080) i chromedriver (9515) mají pevný port a druhý běh skončí na The port … is already in use. S ParaTestem odvoďte porty i název databáze od TEST_TOKEN:
php
$token = (int) (getenv('TEST_TOKEN') ?: 0);
$client = static::createPantherClient(['port' => 9080 + $token], [], ['port' => 9515 + $token]);
  • Pomalé testy dejte do vlastní skupiny. Například testy, které generují PDF dalším Chromiem uvnitř aplikace, potřebují víc paměti a /dev/shm. Ať jdou z rychlého běhu vynechat (--exclude-group=slow).

Panther, nebo jiný nástroj

Panther se hodí tam, kde stránky vykresluje Symfony a JavaScript je doplňuje: Twig s htmx, Alpine.js, Stimulem nebo jednotlivými komponentami v Reactu či Vue. Testy zůstanou v PHPUnit, sdílí fixtures, služby a pomocné třídy s ostatními testy.

Když většinu rozhraní tvoří samostatná SPA, stojí za zvážení nástroj, který čeká sám, například Playwright. Počká, až je prvek viditelný, stabilní a klikatelný, takže odpadá velká část ručního čekání z tohoto článku.

Odkazy: Panther na GitHubu, E2E testy v dokumentaci Symfony, php-webdriver.

Štítky Backend, PHP, JavaScript

Sdílet LinkedIn Facebook

Potřebujete víc než článek?