Chapter 13. PHPUnit and Selenium

Selenium Server is a test tool that allows you to write automated user-interface tests for web applications in any programming language against any HTTP website using any mainstream browser. It performs automated browser tasks by driving the browser's process through the operating system. Selenium tests run directly in a browser, just as real users do. These tests can be used for both acceptance testing (by performing higher-level tests on the integrated system instead of just testing each unit of the system independently) and browser compatibility testing (by testing the web application on different operating systems and browsers).

The only supported scenario of PHPUnit_Selenium is that of a Selenium 2.x server. The server can be accessed through the classic Selenium RC Api, already present in 1.x, or with the WebDriver API (partially implemented) from PHPUnit_Selenium 1.2.

The reason behind this decision is that Selenium 2 is backward compatible and Selenium RC is not maintained anymore.

First, install the Selenium Server:

The PHPUnit_Selenium package is included in the PHAR distribution of PHPUnit. It can be installed via Composer by adding the following "require-dev" dependency:

"phpunit/phpunit-selenium": ">=1.2"

Now we can send commands to the Selenium Server using its client/server protocol.

The PHPUnit_Extensions_Selenium2TestCase test case lets you use the WebDriver API (partially implemented).

Example 13.1 shows how to test the contents of the <title> element of the http://www.example.com/ website.

<?php
class WebTest extends PHPUnit_Extensions_Selenium2TestCase
{
    protected function setUp()
    {
        $this->setBrowser('firefox');
        $this->setBrowserUrl('http://www.example.com/');
    }

    public function testTitle()
    {
        $this->url('http://www.example.com/');
        $this->assertEquals('Example WWW Page', $this->title());
    }

}
?>

phpunit WebTest
PHPUnit 4.2.0 by Sebastian Bergmann.

F

Time: 28 seconds, Memory: 3.00Mb

There was 1 failure:

1) WebTest::testTitle
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
-'Example WWW Page'
+'IANA — Example domains'

/home/giorgio/WebTest.php:13

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

The commands of Selenium2TestCare are implemented via __call(). Please refer to the end-to-end test for PHPUnit_Extensions_Selenium2TestCase for a list of every supported feature.

The PHPUnit_Extensions_SeleniumTestCase test case extension implements the client/server protocol to talk to Selenium Server as well as specialized assertion methods for web testing.

Example 13.2 shows how to test the contents of the <title> element of the http://www.example.com/ website.

<?php
require_once 'PHPUnit/Extensions/SeleniumTestCase.php';

class WebTest extends PHPUnit_Extensions_SeleniumTestCase
{
    protected function setUp()
    {
        $this->setBrowser('*firefox');
        $this->setBrowserUrl('http://www.example.com/');
    }

    public function testTitle()
    {
        $this->open('http://www.example.com/');
        $this->assertTitle('Example WWW Page');
    }
}
?>

phpunit WebTest
PHPUnit 4.2.0 by Sebastian Bergmann.

F

Time: 9 seconds, Memory: 6.00Mb

There was 1 failure:

1) WebTest::testTitle
Current URL: http://www.iana.org/domains/example/

Failed asserting that 'IANA — Example domains' matches PCRE pattern "/Example WWW Page/".


FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

Unlike with the PHPUnit_Framework_TestCase class, test case classes that extend PHPUnit_Extensions_SeleniumTestCase have to provide a setUp() method. This method is used to configure the Selenium Server session. See Table 13.1 for the list of methods that are available for this.

PHPUnit can optionally capture a screenshot when a Selenium test fails. To enable this, set $captureScreenshotOnFailure, $screenshotPath, and $screenshotUrl in your test case class as shown in Example 13.3.

<?php
require_once 'PHPUnit/Extensions/SeleniumTestCase.php';

class WebTest extends PHPUnit_Extensions_SeleniumTestCase
{
    protected $captureScreenshotOnFailure = TRUE;
    protected $screenshotPath = '/var/www/localhost/htdocs/screenshots';
    protected $screenshotUrl = 'http://localhost/screenshots';

    protected function setUp()
    {
        $this->setBrowser('*firefox');
        $this->setBrowserUrl('http://www.example.com/');
    }

    public function testTitle()
    {
        $this->open('http://www.example.com/');
        $this->assertTitle('Example WWW Page');
    }
}
?>

phpunit WebTest
PHPUnit 4.2.0 by Sebastian Bergmann.

F

Time: 7 seconds, Memory: 6.00Mb

There was 1 failure:

1) WebTest::testTitle
Current URL: http://www.iana.org/domains/example/
Screenshot: http://localhost/screenshots/334b080f2364b5f11568ee1c7f6742c9.png

Failed asserting that 'IANA — Example domains' matches PCRE pattern "/Example WWW Page/".


FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

You can run each test using a set of browsers: Instead of using setBrowser() to set up one browser you declare a public static array named $browsers in your test case class. Each item in this array describes one browser configuration. Each of these browsers can be hosted by different Selenium Server servers. Example 13.4 shows an example.

<?php
require_once 'PHPUnit/Extensions/SeleniumTestCase.php';

class WebTest extends PHPUnit_Extensions_SeleniumTestCase
{
    public static $browsers = array(
      array(
        'name'    => 'Firefox on Linux',
        'browser' => '*firefox',
        'host'    => 'my.linux.box',
        'port'    => 4444,
        'timeout' => 30000,
      ),
      array(
        'name'    => 'Safari on MacOS X',
        'browser' => '*safari',
        'host'    => 'my.macosx.box',
        'port'    => 4444,
        'timeout' => 30000,
      ),
      array(
        'name'    => 'Safari on Windows XP',
        'browser' => '*custom C:\Program Files\Safari\Safari.exe -url',
        'host'    => 'my.windowsxp.box',
        'port'    => 4444,
        'timeout' => 30000,
      ),
      array(
        'name'    => 'Internet Explorer on Windows XP',
        'browser' => '*iexplore',
        'host'    => 'my.windowsxp.box',
        'port'    => 4444,
        'timeout' => 30000,
      )
    );

    protected function setUp()
    {
        $this->setBrowserUrl('http://www.example.com/');
    }

    public function testTitle()
    {
        $this->open('http://www.example.com/');
        $this->assertTitle('Example Web Page');
    }
}
?>

PHPUnit_Extensions_SeleniumTestCase can collect code coverage information for tests run through Selenium:

Table 13.2 lists the various assertion methods that PHPUnit_Extensions_SeleniumTestCase provides.

Table 13.3 shows the template method of PHPUnit_Extensions_SeleniumTestCase:

Please refer to the documentation of Selenium commands for a reference of the commands available and how they are used.

The commands of Selenium 1 are implemented dynamically via __call. Refer also to the API docs for PHPUnit_Extensions_SeleniumTestCase_Driver::__call() for a list of all the supported methods on the PHP side, along with arguments and return type where available.

Using the runSelenese($filename) method, you can also run a Selenium test from its Selenese/HTML specification. Furthermore, using the static attribute $seleneseDirectory, you can automatically create test objects from a directory that contains Selenese/HTML files. The specified directory is recursively searched for .htm files that are expected to contain Selenese/HTML. Example 13.5 shows an example.

<?php
require_once 'PHPUnit/Extensions/SeleniumTestCase.php';

class SeleneseTests extends PHPUnit_Extensions_SeleniumTestCase
{
    public static $seleneseDirectory = '/path/to/files';
}
?>

From Selenium 1.1.1, an experimental feature is included allowing the user to share the session between tests. The only supported case is to share the session between all tests when a single browser is used. Call PHPUnit_Extensions_SeleniumTestCase::shareSession(true) in your bootstrap file to enable session sharing. The session will be reset in the case of not successul tests (failed or incomplete); it is up to the user to avoid interactions between tests by resetting cookies or logging out from the application under test (with a tearDown() method).