Symfony Panther 1.0 Released, Awesome Browser Testing and Crawling Library

Symfony Panther 1.0 have just been released, the browser testing and web scraping library for PHP and Symfony. The library relies on the
WebDriver W3C specification to manipulate real web browsers. Chrome and Firefox are natively supported while Safari, Edge and Opera can be used with some additional configuration. Cloud testing providers such as Sauce Labs and Browserstack are also supported.

Panther implements the BrowserKit API, it’s straightforward to use it with the rest of the Symfony ecosystem. For instance, existing functional tests can be executed using a real browser through Panther with (almost) no code change:

namespace App\Tests\Controller;

-use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
+use Symfony\Component\Panther\PantherTestCase;

-class PostControllerTest extends WebTestCase
+class PostControllerTest extends PantherTestCase
 {
     public function testShowPost()
     {
-        $client = static::createClient();
+        $client = static::createPantherClient();

         $client->request('GET', '/post/hello-world');
         $this->assertSelectorTextContains('html h1.title', 'Hello World');
    }
 }

This also means that you can test your JavaScript-enhanced Twig templates directly with PHPUnit (and other testing tools)! Under the hood, Panther automatically starts a web server exposing your application and the browser driver (Selenium Server isn’t needed), then uses the PHP WebDriver library to execute the scenario.

Install Symfony Panther

A Flex recipe have been added generating the needed configuration. So to add Panther and its PHPUnit integration in any Symfony project run :

$ composer req --dev panther phpunit

You also need ChromeDriver or GeckoDriver depending on if you want to run your tests with Google Chrome (by default) or Mozilla Firefox. You can also execute your whole test suite using both browsers to ensure that your project works properly with the two most popular browsers out there.

To install these drivers, use the package manager of your operating system or execute Daniël Brekelmans’ Browser Driver Installer, which is now
supported out of the box by Panther:

$ composer require --dev dbrekelmans/bdi
$ vendor/bin/bdi detect drivers

Finally, open phpunit.xml.dist and uncomment the snippet added by Flex to register the PHPUnit extension:

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

You can also use MakerBundle to generate test classes, so when asked for the type of test to generate you can choose PantherTestCase, which is a dedicated command to generate Panther test skeletons. Something like the code below that you can run with phpunit :

<?php
// tests/MyPantherTest.php

namespace App\Tests;

use Symfony\Component\Panther\PantherTestCase;

class MyPantherTest extends PantherTestCase
{
    public function testSomething(): void
    {
        $client = static::createPantherClient();
        $crawler = $client->request('GET', '/');

        $this->assertSelectorTextContains('h1', 'Hello World');
    }
}

A basic usage of Panther could be this, the code is self explanatory :

<?php

use Symfony\Component\Panther\Client;

require __DIR__.'/vendor/autoload.php'; // Composer's autoloader

$client = Client::createChromeClient();
// Or, if you care about the open web and prefer to use Firefox
$client = Client::createFirefoxClient();

$client->request('GET', 'https://api-platform.com'); // Yes, this website is 100% written in JavaScript
$client->clickLink('Get started');

// Wait for an element to be present in the DOM (even if hidden)
$crawler = $client->waitFor('#installing-the-framework');
// Alternatively, wait for an element to be visible
$crawler = $client->waitForVisibility('#installing-the-framework');

echo $crawler->filter('#installing-the-framework')->text();
$client->takeScreenshot('screen.png'); // Yeah, screenshot!

We know that people looking for crawling solutions tend to use Python solutions, Symfony Panther could make the difference with already few interesting projects that are using the library like :

• Arachnid Web Crawler is a library that crawls your site using Panther to extract SEO-related information;
• zenstruck/browser is a nice library built on top of BrowserKit and Panther providing an expressive and fluent interface to write your integration and end-to-end tests;
• Blackfire PHP SDK allows adding performance assertions to your tests using the famous Blackfire profiler, and now has native support for Panther;
• BehatPantherExtension is an extension adding support for Panther to the Behat testing framework.

Limitations

This have been said, Panther have also some limitations. The following features are not currently supported:

• Crawling XML documents (only HTML is supported)
• Updating existing documents (browsers are mostly used to consume data, not to create webpages)
• Setting form values using the multidimensional PHP array syntax
• Methods returning an instance of \DOMElement (because this library uses WebDriverElement internally)
• Selecting invalid choices in select

Pull Requests are welcome to fill the remaining gaps! Symfony Panther is an open source software released under an MIT license. More information at https://github.com/symfony/panther