Where the heck is any Selenium 2 documentation for PHPUnit?

Question

I'm having a frustrating time trying to find any information on Selenium 2 for PHPUnit except for source code and tests that I can "look through" to "figure it out". Everyone's favorite seems to be

https://github.com/sebastianbergmann/phpunit-selenium/blob/master/Tests/Selenium2TestCaseTest.php

...but surely I don't have to dig through hundreds of lines of source to get answers to simple questions? Where can I find a beginner's guide, basic documentation, or anything?

Answer 1

Ah-ha moment reached. Will post for the next poor soul wandering in these desolate fields of confusion.

When Selenium says "Selenium 2", they like to say "Selenium 2 = Selenium server + WebDriver".

The trick for the PHPUnit person is the WebDriver part, which is not quite in PHPUnit. Selenium has written the WebDrivers in a few other languages, and there's third party ones for PHP which I haven't tried since I'm targeting PHPUnit for now. The WebDriver is basically a way of running around in the DOM and grabbing elements. It's got a good rundown at http://docs.seleniumhq.org/docs/03_webdriver.jsp.

When PHPUnit says "Selenium 2", they mean that they've written classes which do most of the stuff in a WebDriver, but they're not calling it a WebDriver, they're calling it Selenium 2.

Because of PHPUnit's homebrewed version, their methods are named a little differently than the Java or C# versions. This is why everyone is so excited about the PHPUnit test case because it makes it easy to guess what you're looking for after you've found the method you want at the webdriver docs.

Otherwise, apparently most of the other functionality in PHPUnit sticks to the original SeleniumTestCase stuff; I've compiled a few links below to centralize my info somewhat. Selenium 1 is not "dead", but it is old. PHPUnit still uses a lot of architecture from its implementation of Selenium 1, and PHPUnit's Selenium 2 is not really that, but sort of Selenium 1++.

So, there's no reason to go hunting through the source, just try to match the PHPUnit test cases to the WebDriver docs. Also, a few methods in the tutorial for SeleniumTestCase have changed names in Selenium2TestCase, but fear not, the thing still works the same, just a little obfuscated.

You may ask, "Why not just use SeleniumTestCase?" Well, it seems that support for other browsers requires the WebDriver, so if you want to get out of Firefox, you'll need Selenium2TestCase (I could be wrong).

---

Here's some helpful links I found as I scraped away at this:

• Selenium server command line options, 16-06-2013, incomplete, missing things like -singleWindow: http://eswarg.blogspot.com/2013/06/selenium-server-commandline-options.html

• Some more command line options, 4 years old: http://www.grails.org/Selenium+RC+Configuration

• Selenium server command line help, the most complete documentation I've found so far: java -jar selenium-server.jar -h

• Chrome webdriver from command line: How do I get chrome working with selenium, using php webdriver?

• IE webdriver from command line: Howto start InternetExplorerDriver in PHPUnit tests

• PHPUnit configuration XML for multiple browsers in Selenium http://phpunit.de/manual/3.7/en/appendixes.configuration.html#appendixes.configuration.selenium-rc

• Documentation for Selenium2TestCase class (!) http://apigen.juzna.cz/doc/sebastianbergmann/phpunit-selenium/class-PHPUnit_Extensions_Selenium2TestCase.html

• And, of course, the enigmatic PHPUnit Selenium docs: http://phpunit.de/manual/3.7/en/selenium.html

---

To solve my multiple-browser question above, it's still possible to use the static $browser pattern from SeleniumTestCase, but the browser index has changed to browserName:

public static $browsers = array(
    array(
        'name'    => 'Internet Explorer',
        'browserName' => 'iexplore',   // not 'browser'
        'host'    => 'localhost',
        'port'    => 4444,
        'timeout' => 30000,
    ),
};

Note that Phing does not support the <selenium> tag if you're using an XML config.

Answer 2

I've just been through the same process, and wrote this article as a reference for myself and others:

http://scipilot.org/blog/2013/06/30/re-learning-unit-testing-selenium-2-phpunit-selenium/

It sounds like you've already answered most of my discoveries though, but at the very least you'll feel less alone in your frustration!

Answer 3

PHPUnit Selenium extension (containing the Selenium2TestCase etc.) is no longer part of PHPUnit project itself - it is now a standalone extension, which also needs to be explicitly installed (ie. it is not part of the PHPUnit distribution). However there does not appear to be any documentation even for the separate extension.

Also this extension is no longer actively developed and its partially not up-to-date with latest changes in the WebDriver protocol.

To use Selenium with PHPUnit you can however use other tools based on php-webdriver library:

• Steward which integrates the php-webdriver directly to PHPUnit, so you can control the Selenium directly from your tests
• Codeception testing framework which provides BDD-layer on top of the php-webdriver & PHPUnit