George Baugh b484ee948e dont carp always in test 2 years ago
at 352676c597 Fix #469: Let the users deal with whatever default prefs, not my problem 3 years ago
lib 652e2e058f more DWIMmery and docu in Selenium::ActionChains 2 years ago
t b484ee948e dont carp always in test 2 years ago
.gitignore 0a4b993518 ignore .bak files from perltidy 5 years ago
.mailmap 89ed35e931 Add @peroumal to authors, spelling out authors section explicitly 9 years ago
.travis.yml 493d2b2cb9 use more modern perl in travis.yml 4 years ago
Changes fd68d2eadb bump for 1.47 2 years ago
INSTALL.md 59671f6678 Move installation documentation out of the readme 9 years ago
MANIFEST.SKIP 73ec80928f Fix #339: Use TestingMania, update github repo author 6 years ago
README.md 4b83798e71 update README 3 years ago
TAGS 01f49fa04a Add ctags file 10 years ago
cpanfile 5cfe7a1c73 Add Test::MockModule to cpanfile test section 3 years ago
dist.ini fd68d2eadb bump for 1.47 2 years ago
driver-example.pl cf79170f72 replace #!.*perl with "#!/bin/env perl" in executables and docs, remove extranous #! lines in tests 9 years ago
perlcriticrc 73ec80928f Fix #339: Use TestingMania, update github repo author 6 years ago
tidyall.ini 3f61691755 Fix #345: Implement WC3 webdriver standard compatibility 6 years ago
weaver.ini ac6039c4b2 update maintainer section lol 3 years ago


Selenium::Remote::Driver Build Status Coverage Status


Selenium has essentially been leapfrogged technologically by Playwright. (using the devtools protocol for all browsers) Use Chrome::DevToolsProtocol (or the Playwright interface on CPAN) instead of this unless you want to be frustrated by a tool which doesn't do half of what you want. Even then you are probably shooting yourself in the foot not using Javascript directly to automate the testing of webpages.

This module is also not ready for SeleniumHQ's 4.0 series JAR. For compatibility with that, try our next generation selenium client: Selenium::Client


Selenium WebDriver is a test tool that allows you to write automated web application UI tests in any programming language against any HTTP website using any mainstream JavaScript-enabled browser. This module is a Perl implementation of the client for the Webdriver JSONWireProtocol that Selenium provides.

It also implements WC3 selenium.


It's probably easiest to use the cpanm or CPAN commands:

$ cpanm Selenium::Remote::Driver

If you want to install from this repository, see the installation docs for more details.


You can use this module to directly start the webdriver servers, after downloading the appropriate ones and putting the servers in your $PATH. This method does not require the JRE/JDK to be installed, nor does it require the standalone server jar, despite the name of the module. In this case, you'll want to use the appropriate class for driver construction: either Selenium::Chrome, Selenium::Firefox, Selenium::PhantomJS, or Selenium::InternetExplorer.

You can also use this module with the selenium-standalone-server.jar to let it handle browser start up for you, and also manage Remote connections where the server jar is not running on the same machine as your test script is executing. The main class for this method is Selenium::Remote::Driver.

Regardless of which method you use to construct your browser object, all of the classes use the functions listed in the S::R::Driver POD documentation, so interacting with the browser, the page, and its elements would be the same.

no standalone server

  • Firefox 48 & newer: install the Firefox browser, download geckodriver and put it in your $PATH. If the Firefox browser binary is not in the default place for your OS and we cannot locate it via which, you may have to specify the binary location during startup. We also will need to locate the Firefox browser; if the Firefox browser isn't in the default location, you must provide it during startup in the firefox_binary attr.

  • Firefox 47 & older: install the Firefox browser in the default place for your OS. If the Firefox browser binary is not in the default place for your OS, you may have to specify the firefox_binary constructor option during startup.

  • Chrome: install the Chrome browser, download Chromedriver and get chromedriver in your $PATH.

  • PhantomJS: install the PhantomJS binary and get phantomjs in your $PATH. The driver for PhantomJS, Ghostdriver, is bundled with PhantomJS.

When the browser(s) are installed and you have the appropriate binary in your path, you should be able to do the following:

my $firefox = Selenium::Firefox->new;

my $chrome = Selenium::Chrome->new;

my $ghost = Selenium::PhantomJS->new;

Note that you can also pass a binary argument to any of the above classes to manually specify what binary to start. Note that this binary refers to the driver server, not the browser executable.

my $chrome = Selenium::Chrome->new(binary => '~/Downloads/chromedriver');

See the pod for the different modules for more details.

Breaking Changes for Selenium::Firefox in v1.0+

There are breaking changes for Selenium::Firefox from v0.2701 of S:F to v1.0+. This is because in FF47 and older, Firefox didn't have a separate webdriver server executable - local startup was accomplished by starting your actual Firefox browser with a webdriver extension. However, in FF48 and newer, Mozilla have switched to using geckodriver to handle the Webdriver communication. Accordingly, v1.0+ of Selenium::Firefox assumes the geckodriver setup which only works for FF48 and higher:

# marionette_enabled defaults to 1 === assumes you're running FF48
my $fx48 = Selenium::Firefox->new;
my $fx48 = Selenium::Firefox->new( marionette_enabled => 1 );

To drive FF47 with v1.0+ of Selenium::Firefox, you must manually disable marionette:

my $fx47 = Selenium::Firefox->new( marionette_enabled => 0 );

Doing so will start up your Firefox browser with the webdriver extension. Note that in our tests, doing the old "webdriver-extension-startup" for Firefox 48 does not work. Likewise, geckodriver does not work with FF47.

with a standalone server

Download the standalone server and have it running on port 4444:

$ java -jar selenium-server-standalone-X.XX.X.jar

As before, have the browsers themselves installed on your machine, and download the appropriate binary server, passing its location to the server jar during startup.


use strict;
use warnings;
use Selenium::Remote::Driver;

my $driver = Selenium::Remote::Driver->new;
print $driver->get_title . "\n"; # "Google"

my $query = $driver->find_element('q', 'name');
$query->send_keys('CPAN Selenium Remote Driver');

my $send_search = $driver->find_element('btnG', 'name');

# make the find_element blocking for a second to allow the title to change
my $results = $driver->find_element('search', 'id');

print $driver->get_title . "\n"; # CPAN Selenium Remote Driver - Google Search


If using Saucelabs, there's no need to have the standalone server running on a local port, since Saucelabs provides it.

use Selenium::Remote::Driver;

my $user = $ENV{SAUCE_USERNAME};

my $driver = Selenium::Remote::Driver->new(
    remote_server_addr => $user . ':' . $key . '@ondemand.saucelabs.com',
    port => 80

print $driver->get_title();

There are additional usage examples on metacpan, and also in this project's wiki, including setting up the standalone server, running tests on Internet Explorer, Chrome, PhantomJS, and other useful example snippets.

Selenium IDE Plugin

ide-plugin.js is a Selenium IDE Plugin which allows you to export tests recorded in Selenium IDE to a perl script.

Installation in Selenium IDE

  1. Open Selenium IDE
  2. Options >> Options
  3. Formats Tab
  4. Click Add at the bottom
  5. In the name field call it 'Perl-Webdriver'
  6. Paste this entire source in the main textbox
  7. Click 'Save'
  8. Click 'Ok'
  9. Close Selenium IDE and open it again.

Note: The Code generated by this plugin currently assumes that you have firefox 48 or newer + the geckodriver plugin installed.

If you have an older version of firefox you can adjust the plugin the following way: In the options window of selenium IDE (Formats tab) there is a input box called "Header". Here you can modify the fixed header code beeing generatd. Change Selenium::Firefox->new(); according to the firefox init examples shown above in this README.

Support and Documentation

There is a mailing list available at


for usage questions and ensuing discussions. If you've come across a bug, please open an issue in the Github issue tracker. The POD is available in the usual places, including metacpan, and in your shell via perldoc.

$ perldoc Selenium::Remote::Driver
$ perldoc Selenium::Remote::WebElement


Thanks for considering contributing! The contributing guidelines are in the wiki. The documentation there also includes information on generating new Linux recordings for Travis.

Copyright and License

Copyright (c) 2010-2011 Aditya Ivaturi, Gordon Child

Copyright (c) 2014-2017 Daniel Gempesaw

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at


Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.