Panther drives a real browser over WebDriver and gives the test the same API as WebTestCase: request(), the crawler, forms, clicks. The difference is that Chrome renders the page, JavaScript runs and the test sees what the user sees.
You pay for that with speed and a new class of bugs. The application does not run in the test process, nothing waits on its own, and a bug in the test easily looks like a bug in the application. Here is what we have learned and what we have verified.
When to write an E2E test
Panther belongs only where a test cannot do without a browser:
- interaction in JavaScript (htmx, Alpine.js, Stimulus, React, Vue),
- complete user journeys across several pages: sign-up, purchase, payment, return from the gateway,
- behaviour that depends on rendering: visibility, overlays, scrolling.
Test form validation, permissions, fragment responses and APIs in WebTestCase. It runs in the test process and is an order of magnitude faster. Keep the E2E suite to the critical paths.
What Panther tests and what it does not
The browser is real: Chrome in headless mode, with the same rendering and the same JavaScript as the user has. Clicks and typing over WebDriver are real events for the page (isTrusted is true), and WebDriver clicks only where a person could click. A click through executeScript() is not real and skips that check.
The environment around the browser, however, differs from the user's:
- One browser and one window. Chrome, or Firefox, sized 1200 × 900 without touch. No Safari and no phones. You test the mobile layout only with a window size set.
- The browser gives itself away.
navigator.webdriveristrueand the user agent containsHeadlessChrome. Turn bot protection (reCAPTCHA, Cloudflare) off in the test environment or replace it with a test double. - A clean profile without extensions and with the
en-USlanguage unless you set one. - Animations off through
prefers-reduced-motion. - Instant typing without human pace.
- A test world: the
testenvironment, a local network without latency, frozen time, fake payment gateways and registers.
And some things the test does not check at all: that the page looks right (a broken layout or overlapping text the test does not ask about will pass), accessibility and speed. Panther verifies that the application works in Chrome from the user's point of view, not that it works everywhere and looks good.
Installation and the browser
composer require --dev symfony/panther
Panther needs Chrome (or Firefox) and a chromedriver of the same major version. A mismatch ends right at start-up: session not created: This version of ChromeDriver only supports Chrome version ….
- Panther looks for chromedriver in
PATHfirst and only then in./drivers. An older systemchromedriverthat came with a package therefore wins over the driverdbrekelmans/bdidownloaded to./drivers. Keep one source: either the system packages for both the browser and the driver (chromiumandchromium-driver), orbdiand no driver inPATH. - A different browser binary goes into
PANTHER_CHROME_BINARY. There is no variable for the driver path. - In a container Chrome runs as root with a small
/dev/shm, so it needsPANTHER_NO_SANDBOX=1and--disable-dev-shm-usage.
phpunit.dist.xml gets the extension that keeps the server and the browser running for the whole run, not just for one class:
<extensions>
<bootstrap class="Symfony\Component\Panther\ServerExtension" />
</extensions>
And .env.test gets:
PANTHER_APP_ENV=test
PANTHER_NO_SANDBOX=1
PANTHER_CHROME_ARGUMENTS='--disable-dev-shm-usage'
PANTHER_ERROR_SCREENSHOT_DIR=./var/error-screenshots
Put the E2E tests in their own suite (<testsuite name="e2e">) so they can run separately and the regular tests do not wait for a browser. How to run all of this in DDEV is described in the article Local Symfony development in DDEV.
Two processes
This is the most important point of the whole article. A click in Panther is no shortcut through the kernel, it is a real HTTP request:
- The test sends chromedriver a WebDriver command: click this element.
- Chrome clicks, the page's JavaScript runs and the browser sends an HTTP request with its headers and cookies.
- A web server in another process receives the request: PHP's built-in server that Panther starts on port 9080, or a real web server when you set
PANTHER_EXTERNAL_BASE_URI. - It runs
public/index.php, Symfony boots the kernel and handles the request as in production. Every request is a separate PHP run. - Chrome renders the response and the test reads the resulting DOM over WebDriver.
Even $client->request() only tells the browser to open an address. KernelBrowser in WebTestCase, on the other hand, sends no HTTP at all: it builds a Request object and hands it to the kernel in the same process. That is why it is fast and can see into the container.
The kernel Panther boots in the test process serves only the test: getContainer(), the EntityManager for fixtures and database checks. It has no effect on the browser's requests. The test and the server each have their own service container, their own EntityManager and their own database connection.
What follows:
self::getContainer()->set()does not reach the server. A test double, such as a fake payment gateway, must be wired in the configuration of thetestenvironment (config/packages/test/services.yaml). A service defined inconfig/services.yamlloads later and would win over an alias, so wire the double withdecorates.- The processes exchange state through the database or files. The test writes what the fake gateway should answer into a file in
var/cache/test/and the double on the server reads it. - Data must be committed. What the test writes and flushes, the server sees. What sits in an uncommitted transaction, it does not.
- DAMA DoctrineTestBundle does not work with Panther. It wraps the test in a transaction that it rolls back at the end. The server does not see the test's data, and when the test changes a row the server later writes to, the server waits for the lock until the test ends. Run the E2E suite without the DAMA extension and reset the database another way (below).
- Mailer assertions (
assertEmailCount()and others) count zero. They read messages sent in the test process, not on the server. In the test environment the application can store sent e-mails in a table for the test to query, or read them from the Mailpit API. - Frozen time applies to each process separately. A
MockClockfrom thetestenvironment configuration freezes time on the server and in the test. The server will not see the test moving the clock, though. Handle "14 days later" by running the cron in the test process with the clock moved, against the shared database. The browser meanwhile keeps living on the frozen day.
Database
A proven approach:
- The schema once at the start of the suite. A PHPUnit extension listening to the suite start drops the database, runs the migrations and loads the data that migrations or synchronisations provide (code lists, CMS texts).
- Fixtures per class in
setUpBeforeClass(), directly through the fixtures loader rather than a console call. It is faster. - Leave tables filled by migrations out of the purge.
ORMPurgergets a list of tables to leave alone. Otherwise the first purge removes configuration the application cannot run without. - Tests within a class create their state through the application (sign-up, purchase) and with unique e-mail addresses. Do not rely on test order.
Built-in or real server
PHP's built-in server is the simplest way. It serves static files only from public/, though, so assets must be built beforehand (npm run build, asset-map:compile). The nginx configuration, HTTPS and headers do not apply either.
With PANTHER_EXTERNAL_BASE_URI the tests run against a real web server, along the same path as production. It has to run in APP_ENV=test with the test database itself. A second project address has worked well, for example test.project.ddev.site, where the web server passes APP_ENV=test to PHP while the main address keeps serving development.
- Warm up the PHP-FPM workers before the suite with a few concurrent requests to the test address. A cold worker loads the container and the first tests then fail at random on a timeout.
- Neither server reveals worker mode bugs (FrankenPHP, RoadRunner). A service that keeps state between requests behaves correctly in the tests and not in production. Guard against that another way, for example by checking
ResetInterfaceon stateful services.
What Panther cannot do
The client looks like KernelBrowser, but not everything works:
request()sends only GET. Submit a form through the crawler or with a click.getResponse()and response assertions (assertResponseIsSuccessful(),assertResponseStatusCodeSame()) end in an exception. You do not see the status code in the browser, check the page content.text()returns only visible text. A hidden element returns an empty string. The page title comes from$client->getTitle().loginUser()does not exist. The server knows nothing about the test's session. Log in through the real form, once per class.- There is one client for the whole run. A second call to
createPantherClient()returns the same browser and ignores the new options. Cookies,localStorageand the login survive into the next test. - A cookie can be set only on a page from its domain, otherwise
InvalidCookieDomainException.
So clean up the state between tests in a base class:
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) {
// a page without storage, such as about:blank
}
parent::tearDown();
}
}
Waiting
Panther does not wait on its own. An assertion right after an action reads the page as it is at that moment, and most randomly failing tests start right here.
- Neither
submit()norclick()waits for navigation. The crawler returned right after a form submit is still the old page. Wait for something that exists only on the target page, or for the address to change. - Wait for the end state, not a transient indicator. A spinner or
aria-busymay appear only after your check, or disappear before you look. - No
sleep(). On a slow machine it is not enough, on a fast one it holds things up. The exception is a delay the application requires on purpose, such as a form's time trap against bots. - The default timeout is 30 seconds. Every failure then costs half a minute. A few seconds are enough for ordinary elements:
waitFor('#result', 5).
Panther has a set of waitFor* methods and assertSelectorWill* assertions:
$client->waitFor('#result'); // the element exists
$client->waitForVisibility('#modal'); // it is visible
$client->waitForInvisibility('.spinner'); // it is gone or does not exist
$client->waitForElementToContain('#total', '1,200'); // it contains the text
$client->waitForStaleness('#list'); // this element was replaced
self::assertSelectorWillContain('#flash', 'Saved');
waitForStaleness() finds the element first. When it no longer exists, it throws NoSuchElementException straight away. For a disappearing element, waitForInvisibility() is safer, as it passes for a missing element too.
For anything else, a custom condition will do:
use Facebook\WebDriver\WebDriverExpectedCondition;
$client->wait(10)->until(WebDriverExpectedCondition::urlContains('/payment/success'));
$client->wait(5)->until(fn () => true === $client->executeScript('return window.appReady'));
After every wait, read the crawler again ($client->getCrawler() or the crawler waitFor* returns). The old one reflects the state before the change.
JavaScript in the browser
Common to all libraries: content that comes over the network appears later than the click ends. Right after clicking a button that loads data, the result is still empty. The differences are in what you can wait for and how fields are filled in.
htmx
- During a request the triggering element has the
htmx-requestclass, not an attribute. The[hx-request]selector finds nothing, and waiting for it silently does not wait. htmx:after:requestcomes before the swap. After the swap comehtmx:after:swap,htmx:after:settleand finallyhtmx:finally:request, which arrives after an error too.- Attach the listener before you trigger the action, ideally in the same script. Attached only after the click, it can in principle miss a fast response.
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 keeps the value of the focused field. When you submit a form with Enter, the field with the cursor shows after the morph what the user typed, not the value from the server. Verify the saved state with a fresh page load, not by reading the morphed form.
- Fragment responses and
hx-swap-oobare enough to test inWebTestCasewith theHX-Requestheader. In Panther, test only that the swap actually happens in the browser.
How to use htmx in Symfony is covered in a series that starts with the article Navigation in Symfony with htmx.
React
- The component mounts only after the page has loaded.
request()returns a page without the component's content yet. Before the first action, wait for an element inside the component. - Typing with
sendKeys()works, through Panther's form API too. WebDriver sends real keyboard events. - A value set from a script does not work. For a controlled input, React ignores
el.value = …even with aninputevent afterwards. Only the native setter plus the event gets through:
$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', 'jane@example.test']);
For a textarea it is HTMLTextAreaElement.prototype. Where possible, prefer sendKeys().
- Elements go stale after a re-render. A stored element and a stored crawler both throw
StaleElementReferenceExceptionafter the component remounts. Do not keep elements across an action, look them up again afterwards.
Vue and Alpine.js
- Both
v-modelandx-modellisten to theinputevent. Unlike React,el.value = …plusdispatchEvent(new Event('input', { bubbles: true }))is enough here.el.valuealone without the event is not enough anywhere. v-model.lazyupdates the model only onchange, that is when the field loses focus. AftersendKeys()the model is still empty until you sendWebDriverKeys::TABor click elsewhere. The same goes for custom@changelisteners.
Client-side routing
A transition through history.pushState() is not a page load. getCurrentURL() returns the new address, but waitFor does not wait for it. Wait for the address and then for the content of the new screen:
$client->getCrawler()->filter('#detail-link')->click();
$client->wait(5)->until(WebDriverExpectedCondition::urlContains('/detail'));
$client->waitFor('#detail-title');
Request counter
A generic fetch counter (a wrapped window.fetch with a counter) tells you the network has finished, not that the result has rendered. Between the response and the rendering there is still reading the JSON and changing the state. It is useful as an addition, but waiting for the result in the DOM is more reliable.
Clicks, overlays and hidden fields
- A covered element reports
ElementClickInterceptedException. WebDriver clicks only where the user could click. Wait for the overlay to disappear (waitForInvisibility('.modal-backdrop')). - A visually hidden field (a checkbox with the
sr-onlyclass under custom graphics) reports the same. Click itslabelor toggle it with a script. - A button below the fold is sometimes reported by WebDriver as covered even when it is not.
scrollIntoView({ block: 'center' })or a script click helps. - A script click deliberately skips the check that the element can really be clicked. Use it where you know why, and say so in a comment.
form.submit()does not fire thesubmitevent. When JavaScript adds a CSRF token or other data only on submit, the form is sent without it. Useform.requestSubmit()or a real click.- Panther turns on
prefers-reduced-motion. Animations and smooth scrolling that respect it do not get in the way of tests. Those that ignore it cause intercepted clicks.
confirm() dialogs
After a click on an element that opens confirm(), Panther reads the page right away and runs into UnexpectedAlertOpenException. Click the WebDriver element directly and handle the dialog:
$crawler->filter('#delete')->getElement(0)->click();
$client->wait(5)->until(WebDriverExpectedCondition::alertIsPresent());
$client->getWebDriver()->switchTo()->alert()->accept();
$client->refreshCrawler();
This also applies to hx-confirm and data-turbo-confirm when they use the native dialog.
File uploads
No dialog picks the file, WebDriver hands the path straight to the field. In a form, the form API is enough, and it copes with a relative path too:
$form = $crawler->filter('#document-form')->form();
$form['doc']->upload(__DIR__.'/../fixtures/contract.pdf');
$client->submit($form);
$client->waitFor('#uploaded');
Outside a form, for example with a field sent through htmx, send the path directly:
$crawler->filter('#doc')->sendKeys(realpath(__DIR__.'/../fixtures/contract.pdf'));
- The path for
sendKeys()must be absolute, otherwisepath is not absolute. - Several files for a field with
multiplego in one call, with the paths separated by a newline. - A hidden field under a custom button or a dropzone (
display: none) accepts the file. Unlike a hidden checkbox, there is nothing to work around. WebDriver cannot drag a file from the disk, so send the file to the<input type="file">the dropzone has underneath. - The file must exist on the machine where the browser runs. When it runs in the same container as the tests, fixtures in the repository are enough.
- Test server-side validation (size, type, error messages) in
WebTestCasewithUploadedFile. It is faster, and you can slip in a file the browser would never send. Leave picking the file, the preview and the result in the browser to Panther.
Debugging
- A screenshot on failure is saved by Panther to
PANTHER_ERROR_SCREENSHOT_DIRboth for a failed assertion and for an exception, such as awaitFortimeout. In CI, keep it as an artefact. - The browser console. A
waitFortimeout often means a JavaScript error that keeps the element from ever appearing. Turn on console logging and print it intearDown:
$client = static::createPantherClient([], [], [
'capabilities' => ['goog:loggingPrefs' => ['browser' => 'ALL']],
]);
foreach ($client->getWebDriver()->manage()->getLog('browser') as $entry) {
fwrite(STDERR, $entry['level'].' '.$entry['message'].PHP_EOL);
}
- Share helper methods. Logging in, waiting for htmx, filling in an admin form, the link from a sent e-mail: when every test writes its own, every copy fails differently. A broken copy can even pass, because nothing checks it. A waiting helper with the wrong selector silently does not wait and only slows the test down.
CI
- An image with PHP, Chromium and chromedriver from the same source. Debian's
chromiumandchromium-driverpackages always come in matching versions. - The database as a job service, with the same credentials as in
.env.test, so nothing needs overriding. - Before the tests, build the assets, run
cache:warmup --env=testand wait until the database answers. - Set the time zone as in production. An image without one runs in UTC, and frozen time with a
+02:00offset then gives a different "today" than the browser. - Keep failure screenshots and the server log as job artefacts (
when: on_failure). - Concurrent runs need their own ports. The server (9080) and chromedriver (9515) have fixed ports, and a second run ends with
The port … is already in use. With ParaTest, derive the ports and the database name fromTEST_TOKEN:
$token = (int) (getenv('TEST_TOKEN') ?: 0);
$client = static::createPantherClient(['port' => 9080 + $token], [], ['port' => 9515 + $token]);
- Put slow tests in their own group. Tests that generate a PDF with another Chromium inside the application, for example, need more memory and
/dev/shm. That way they can be left out of the quick run (--exclude-group=slow).
Panther or another tool
Panther fits where Symfony renders the pages and JavaScript adds to them: Twig with htmx, Alpine.js, Stimulus or individual React or Vue components. The tests stay in PHPUnit and share fixtures, services and helper classes with the other tests.
When most of the interface is a standalone SPA, consider a tool that waits on its own, for example Playwright. It waits until an element is visible, stable and clickable, which removes much of the manual waiting from this article.
Links: Panther on GitHub, E2E tests in the Symfony documentation, php-webdriver.