Panther Laravel Package

Getting Started

Start by installing the package via Composer (composer require --dev symfony/panther) and enabling the Panther service in your phpunit.xml (or using the dedicated PantherTestCase base class). Your first test typically involves extending PantherTestCase and using the client to simulate a real browser—e.g., visiting a page, asserting text, and interacting with DOM elements. Example first use case:

class ExampleTest extends PantherTestCase
{
    public function test_homepage_contains_title(): void
    {
        $client = self::createPantherClient();
        $crawler = $client->request('GET', '/');
        $this->assertSelectorTextContains('h1', 'Welcome');
    }
}

Check the official Panther documentation for setup details, especially regarding ChromeDriver/GeckoDriver installation if not using the bundled binary.

Implementation Patterns

• E2E Testing: Write full end-to-end tests that interact with your app in a real browser—form submissions, JavaScript-heavy workflows, SPA navigation—without mocking HTTP layers.
• Web Scraping: Use the same API for crawling: $client->clickLink('Next'); $data = $crawler->filter('.article')->each(...);
• Integration with CI: Leverage Docker-based browser environments or use prebuilt Panther images (e.g., symfony/panther base image) to avoid driver compatibility issues.
• Async JS Handling: Use $client->waitFor() or promise-based waiting ($client->waitUntil(...)) to handle reactive UIs gracefully.
• Custom Headers/Options: Override default browser options via createPantherClient() with an options array (e.g., ['headless' => false, 'browser_language' => 'fr']).

Gotchas and Tips

• Driver Compatibility: Version mismatches between Panther and Chrome/Chromedriver are a common failure point—always check the recommended driver version in the release notes or composer.json constraints.
• Performance: Panther is heavier than Symfony’s HttpKernel client; avoid using it for simple API tests—reserve it for JavaScript/visual verification.
• Headless vs. Visible Mode: Tests fail silently on CI if headless mode isn’t explicitly configured—ensure PANTHER_HEADLESS is set or specify headless in client options.
• DOM Timing: Without explicit waits, selectors can fail on slow loads. Prefer $crawler->filter(...)->first() over direct array access.
• Extension Points: Implement custom browser instances (e.g., with custom Chrome args) by subclassing ChromeClient and passing it to createPantherClient().