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.webdriverjetruea user-agent obsahujeHeadlessChrome. 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č
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řesdbrekelmans/bdido./driverstak 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 (chromiumachromium-driver), nebobdia vPATHžá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řebujePANTHER_NO_SANDBOX=1a--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:
<extensions>
<bootstrap class="Symfony\Component\Panther\ServerExtension" />
</extensions>
A do .env.test:
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:
- Test pošle chromedriveru příkaz WebDriveru: klikni na tento prvek.
- Chrome klikne, spustí se JavaScript stránky a prohlížeč pošle HTTP požadavek se svými hlavičkami a cookies.
- 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. - 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. - 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á vconfig/services.yamlse načítá později a alias by přebila, proto dvojníka zapojte přesdecorates.- 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.
MockClockz konfigurace prostředítestzmrazí č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:
- 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).
- Fixtures pro každou třídu v
setUpBeforeClass()přímo přes loader fixtures, ne voláním konzole. Je to rychlejší. - Tabulky naplněné migracemi z mazání vynechte.
ORMPurgerdostane seznam tabulek, které má nechat být. Jinak po prvním purge chybí konfigurace, bez které aplikace nefunguje. - 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
ResetInterfaceu 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,localStoragei 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ě:
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()aniclick()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-busyse 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*:
$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:
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:requestpřichází před swapem. Po swapu přicházejíhtmx:after:swap,htmx:after:settlea nakonechtmx: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.
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-oobstačí otestovat veWebTestCases hlavičkouHX-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:
$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-modelix-modelposlouchají událostinput. Na rozdíl od Reactu tu stačíel.value = …adispatchEvent(new Event('input', { bubbles: true })). Samotnéel.valuebez události nestačí nikde.v-model.lazyaktualizuje model až nachange, tedy po opuštění pole. PosendKeys()je model pořád prázdný, dokud nepošleteWebDriverKeys::TABnebo 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:
$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-onlypod vlastní grafikou) hlásí totéž. Klikněte na jeholabel, 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álostsubmit. Když token CSRF nebo jiná data doplňuje JavaScript až při odeslání, formulář odešle prázdné. Použijteform.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:
$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:
$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:
$crawler->filter('#doc')->sendKeys(realpath(__DIR__.'/../fixtures/smlouva.pdf'));
- Cesta pro
sendKeys()musí být absolutní, jinakpath is not absolute. - Víc souborů do pole s
multiplepoš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
WebTestCasesUploadedFile. 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_DIRpři neprošlé asserci i při výjimce, třeba timeoutuwaitFor. 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 vtearDownho vypište:
$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
chromiumachromium-drivermá 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=testa 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:00pak 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 odTEST_TOKEN:
$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.