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?

I was asking myself this same question few months ago. Then I realised that life is to short to struggle with many obvious issues and decided that my project don't need to have selenium tests written in the same language. I switched to Java and I'm happy man now ;) — Michal, Oct 01 '13 at 10:00
That would have been good advice :) but although it took two days to figure this sh*t out I'm not too unhappy with the package, and I can integrate it with my Phing, which is nice. But for an industry-standard package (at least, PHPUnit and Selenium, individually) there's surprisingly little starting info. Anyway, over the hump now:) — Ben, Oct 02 '13 at 00:03
@seimic - since I wrote this question, I've had a chance to work with the Java one too - it was significantly easier. Same functionality in the end, though, and integrates better with Ant than Phing. — Ben, Jan 05 '15 at 18:14

score 32 · Accepted Answer · edited May 23 '17 at 12:17

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.

Wrote a tutorial on how to setup PHPUnit and Selnium2 http://geekpad.ca/blog/post/automating-browser-testing-with-phpunit-and-selenium — Patrick Forget, Apr 30 '14 at 17:49

score 4 · Answer 2 · answered Oct 04 '13 at 04:54

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!

score 3 · Answer 3 · answered Apr 17 '17 at 23:36

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

Where the heck is any Selenium 2 documentation for PHPUnit?

3 Answers3

Linked