XUtils

Symfony Panther

A browser testing and web crawling library for PHP and Symfony.


Documentation

Installing Panther

Use Composer to install Panther in your project. You may want to use the --dev flag if you want to use Panther for testing only and not for web scraping in a production environment:

composer req symfony/panther

composer req --dev symfony/panther

Installing ChromeDriver and geckodriver

Panther uses the WebDriver protocol to control the browser used to crawl websites.

On all systems, you can use dbrekelmans/browser-driver-installer to install ChromeDriver and geckodriver locally:

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

Panther will detect and use automatically drivers stored in the drivers/ directory.

Alternatively, you can use the package manager of your operating system to install them.

On Ubuntu, run:

apt-get install chromium-chromedriver firefox-geckodriver

On Mac, using Homebrew:

brew install chromedriver geckodriver

On Windows, using chocolatey:

choco install chromedriver selenium-gecko-driver

Finally, you can download manually ChromeDriver (for Chromium or Chrome) and GeckoDriver (for Firefox) and put them anywhere in your PATH or in the drivers/ directory of your project.

Registering the PHPUnit Extension

If you intend to use Panther to test your application, we strongly recommend registering the Panther PHPUnit extension. While not strictly mandatory, this extension dramatically improves the testing experience by boosting the performance and allowing to use the interactive debugging mode.

When using the extension in conjunction with the PANTHER_ERROR_SCREENSHOT_DIR environment variable, tests using the Panther client that fail or error (after the client is created) will automatically get a screenshot taken to help debugging.

To register the Panther extension, add the following lines to phpunit.xml.dist:

<!-- phpunit.xml.dist -->
<extensions>
    <extension class="Symfony\Component\Panther\ServerExtension" />
</extensions>

Without the extension, the web server used by Panther to serve the application under test is started on demand and stopped when tearDownAfterClass() is called. On the other hand, when the extension is registered, the web server will be stopped only after the very last test.

Creating Isolated Browsers to Test Apps Using Mercure or WebSocket

Panther provides a convenient way to test applications with real-time capabilities which use Mercure, WebSocket and similar technologies.

PantherTestCase::createAdditionalPantherClient() creates additional, isolated browsers which can interact with each other. For instance, this can be useful to test a chat application having several users connected simultaneously:

<?php

use Symfony\Component\Panther\PantherTestCase;

class ChatTest extends PantherTestCase
{
    public function testChat(): void
    {
        $client1 = self::createPantherClient();
        $client1->request('GET', '/chat'); 
 
        // Connect a 2nd user using an isolated browser and say hi!
        $client2 = self::createAdditionalPantherClient();
        $client2->request('GET', '/chat');
        $client2->submitForm('Post message', ['message' => 'Hi folks 👋😻']);

        // Wait for the message to be received by the first client
        $client1->waitFor('.message');

        // Symfony Assertions are always executed in the **primary** browser
        $this->assertSelectorTextContains('.message', 'Hi folks 👋😻');
    }
}

Accessing Browser Console Logs

If needed, you can use Panther to access the content of the console:

<?php

use Symfony\Component\Panther\PantherTestCase;

class ConsoleTest extends PantherTestCase
{
    public function testConsole(): void
    {
        $client = self::createPantherClient(
            [],
            [],
            [
                'capabilities' => [
                    'goog:loggingPrefs' => [
                        'browser' => 'ALL', // calls to console.* methods
                        'performance' => 'ALL', // performance data
                    ],
                ],
            ]
        );

        $client->request('GET', '/');
        $consoleLogs = $client->getWebDriver()->manage()->getLog('browser'); // console logs 
        $performanceLogs = $client->getWebDriver()->manage()->getLog('performance'); // performance logs
    }
}

Passing Arguments to ChromeDriver

If needed, you can configure the arguments to pass to the chromedriver binary:

<?php

use Symfony\Component\Panther\PantherTestCase;

class MyTest extends PantherTestCase
{
    public function testLogging(): void
    {
        $client = self::createPantherClient(
            [],
            [],
            [
                'chromedriver_arguments' => [
                    '--log-path=myfile.log',
                    '--log-level=DEBUG'
                ],
            ]
        );

        $client->request('GET', '/');
    }
}

Checking the State of the WebDriver Connection

Use the Client::ping() method to check if the WebDriver connection is still active (useful for long-running tasks).

Additional Documentation

Since Panther implements the API of popular libraries, it already has an extensive documentation:

Environment Variables

The following environment variables can be set to change some Panther’s behaviour:

  • PANTHER_NO_HEADLESS: to disable the browser’s headless mode (will display the testing window, useful to debug)
  • PANTHER_WEB_SERVER_DIR: to change the project’s document root (default to ./public/, relative paths must start by ./)
  • PANTHER_WEB_SERVER_PORT: to change the web server’s port (default to 9080)
  • PANTHER_WEB_SERVER_ROUTER: to use a web server router script which is run at the start of each HTTP request
  • PANTHER_EXTERNAL_BASE_URI: to use an external web server (the PHP built-in web server will not be started)
  • PANTHER_APP_ENV: to override the APP_ENV variable passed to the web server running the PHP app
  • PANTHER_ERROR_SCREENSHOT_DIR: to set a base directory for your failure/error screenshots (e.g. ./var/error-screenshots)
  • PANTHER_DEVTOOLS: to toggle the browser’s dev tools (default enabled, useful to debug)
  • PANTHER_ERROR_SCREENSHOT_ATTACH: to add screenshots mentioned above to test output in junit attachment format

Changing the Hostname and Port of the Built-in Web Server

If you want to change the host and/or the port used by the built-in web server, pass the hostname and port to the $options parameter of the createPantherClient() method:

// ...

$client = self::createPantherClient([
    'hostname' => 'example.com', // Defaults to 127.0.0.1
    'port' => 8080, // Defaults to 9080
]);

Chrome-specific Environment Variables

  • PANTHER_NO_SANDBOX: to disable Chrome’s sandboxing (unsafe, but allows to use Panther in containers)
  • PANTHER_CHROME_ARGUMENTS: to customize Chrome arguments. You need to set PANTHER_NO_HEADLESS to fully customize.
  • PANTHER_CHROME_BINARY: to use another google-chrome binary

Firefox-specific Environment Variables

  • PANTHER_FIREFOX_ARGUMENTS: to customize Firefox arguments. You need to set PANTHER_NO_HEADLESS to fully customize.
  • PANTHER_FIREFOX_BINARY: to use another firefox binary

Accessing To Hidden Text

According to the spec, WebDriver implementations return only the displayed text by default. When you filter on a head tag (like title), the method text() returns an empty string. Use the method html() to get the complete contents of the tag, including the tag itself.

Interactive Mode

Panther can make a pause in your tests suites after a failure. It is a break time really appreciated for investigating the problem through the web browser. For enabling this mode, you need the --debug PHPUnit option without the headless mode:

$ PANTHER_NO_HEADLESS=1 bin/phpunit --debug

Test 'App\AdminTest::testLogin' started
Error: something is wrong.

Press enter to continue...

To use the interactive mode, the PHPUnit extension must be registered.

Using an External Web Server

Sometimes, it’s convenient to reuse an existing web server configuration instead of starting the built-in PHP one. To do so, set the external_base_uri option:

<?php

namespace App\Tests;

use Symfony\Component\Panther\PantherTestCase;

class E2eTest extends PantherTestCase
{
    public function testMyApp(): void
    {
        $pantherClient = static::createPantherClient(['external_base_uri' => 'https://localhost']);
        // the PHP integrated web server will not be started
    }
}

Having a Multi-domain Application

It happens that your PHP/Symfony application might serve several different domain names.

As Panther saves the Client in memory between tests to improve performances, you will have to run your tests in separate processes if you write several tests using Panther for different domain names.

To do so, you can use the native @runInSeparateProcess PHPUnit annotation.

ℹ Note: it is really convenient to use the external_base_uri option and start your own webserver in the background, because Panther will not have to start and stop your server on each test. Symfony CLI can be a quick and easy way to do so.

Here is an example using the external_base_uri option to determine the domain name used by the Client:

<?php

namespace App\Tests;

use Symfony\Component\Panther\PantherTestCase;

class FirstDomainTest extends PantherTestCase
{
    /**
     * @runInSeparateProcess
     */
    public function testMyApp(): void
    {
        $pantherClient = static::createPantherClient([
            'external_base_uri' => 'http://mydomain.localhost:8000',
        ]);
        
        // Your tests
    }
}
<?php

namespace App\Tests;

use Symfony\Component\Panther\PantherTestCase;

class SecondDomainTest extends PantherTestCase
{
    /**
     * @runInSeparateProcess
     */
    public function testMyApp(): void
    {
        $pantherClient = static::createPantherClient([
            'external_base_uri' => 'http://anotherdomain.localhost:8000',
        ]);
        
        // Your tests
    }
}

Using a Proxy

To use a proxy server, set the following environment variable: PANTHER_CHROME_ARGUMENTS='--proxy-server=socks://127.0.0.1:9050'

Accepting Self-signed SSL Certificates

To force Chrome to accept invalid and self-signed certificates, set the following environment variable: PANTHER_CHROME_ARGUMENTS='--ignore-certificate-errors' This option is insecure, use it only for testing in development environments, never in production (e.g. for web crawlers).

For Firefox, instantiate the client like this:

$client = Client::createFirefoxClient(null, null, ['capabilities' => ['acceptInsecureCerts' => true]]);

Docker Integration

Here is a minimal Docker image that can run Panther with both Chrome and Firefox:

FROM php:alpine

# Chromium and ChromeDriver
ENV PANTHER_NO_SANDBOX 1
# Firefox and GeckoDriver (optional)
ARG GECKODRIVER_VERSION=0.28.0
RUN apk add --no-cache firefox libzip-dev; \
    docker-php-ext-install zip
RUN wget -q https://github.com/mozilla/geckodriver/releases/download/v$GECKODRIVER_VERSION/geckodriver-v$GECKODRIVER_VERSION-linux64.tar.gz; \
    tar -zxf geckodriver-v$GECKODRIVER_VERSION-linux64.tar.gz -C /usr/bin; \
    rm geckodriver-v$GECKODRIVER_VERSION-linux64.tar.gz

Build it with docker build . -t myproject Run it with docker run -it -v "$PWD":/srv/myproject -w /srv/myproject myproject bin/phpunit

GitHub Actions Integration

Panther works out of the box with GitHub Actions. Here is a minimal .github/workflows/panther.yml file to run Panther tests:

name: Run Panther tests

on: [ push, pull_request ]

jobs:
  tests:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Install dependencies
        run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist

      - name: Run test suite
        run: bin/phpunit

Travis CI Integration

Panther will work out of the box with Travis CI if you add the Chrome addon. Here is a minimal .travis.yml file to run Panther tests:

language: php
addons:
  # If you don't use Chrome, or Firefox, remove the corresponding line
  chrome: stable
  firefox: latest

php:
  - 8.0

script:
  - bin/phpunit

Gitlab CI Integration

Here is a minimal .gitlab-ci.yml file to run Panther tests with Gitlab CI:

image: ubuntu

before_script:
  - apt-get update
  - apt-get install software-properties-common -y
  - ln -sf /usr/share/zoneinfo/Asia/Tokyo /etc/localtime
  - apt-get install curl wget php php-cli php7.4 php7.4-common php7.4-curl php7.4-intl php7.4-xml php7.4-opcache php7.4-mbstring php7.4-zip libfontconfig1 fontconfig libxrender-dev libfreetype6 libxrender1 zlib1g-dev xvfb chromium-chromedriver firefox-geckodriver -y -qq
  - export PANTHER_NO_SANDBOX=1
  - export PANTHER_WEB_SERVER_PORT=9080
  - php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
  - php composer-setup.php --install-dir=/usr/local/bin --filename=composer
  - php -r "unlink('composer-setup.php');"
  - composer install

test:
  script:
    - bin/phpunit

AppVeyor Integration

Panther will work out of the box with AppVeyor as long as Google Chrome is installed. Here is a minimal appveyor.yml file to run Panther tests:

build: false
platform: x86
clone_folder: c:\projects\myproject

cache:
  - '%LOCALAPPDATA%\Composer\files'

install:
  - ps: Set-Service wuauserv -StartupType Manual
  - cinst -y php composer googlechrome chromedriver firfox selenium-gecko-driver
  - refreshenv
  - cd c:\tools\php80
  - copy php.ini-production php.ini /Y
  - echo date.timezone="UTC" >> php.ini
  - echo extension_dir=ext >> php.ini
  - echo extension=php_openssl.dll >> php.ini
  - echo extension=php_mbstring.dll >> php.ini
  - echo extension=php_curl.dll >> php.ini
  - echo memory_limit=3G >> php.ini
  - cd %APPVEYOR_BUILD_FOLDER%
  - composer install --no-interaction --no-progress

test_script:
  - cd %APPVEYOR_BUILD_FOLDER%
  - php bin\phpunit

Troubleshooting

Run with Bootstrap 5

If you are using Bootstrap 5, then you may have a problem with testing. Bootstrap 5 implements a scrolling effect, which tends to mislead Panther.

To fix this, we advise you to deactivate this effect by setting the Bootstrap 5 $enable-smooth-scroll variable to false in your style file.

$enable-smooth-scroll: false;

Credits

Created by Kévin Dunglas. Sponsored by Les-Tilleuls.coop.

Panther is built on top of PHP WebDriver and several other FOSS libraries. It has been inspired by Nightwatch.js, a WebDriver-based testing tool for JavaScript.


Articles

  • coming soon...