Distinguish between FF47 & FF48 binary startup

lib/Selenium/Firefox.pm

@@ -7,27 +7,34 @@ extends 'Selenium::Remote::Driver';
 
 =head1 SYNOPSIS
 
+    # these two are the same, and will only work with Firefox 48 and
+    # greater
     my $driver = Selenium::Firefox->new;
     my $driver = Selenium::Firefox->new( marionette_enabled => 1 );
 
+    # For Firefox 47 and older, disable marionette:
+    my $driver = Selenium::Firefox->new( marionette_enabled => 0 );
+
 =head1 DESCRIPTION
 
 This class allows you to use the FirefoxDriver without needing the JRE
-or a selenium server running. When you refrain from passing the
-C<remote_server_addr> and C<port> arguments, we will search for the
-Firefox executable in your $PATH. We'll try to start the binary
-connect to it, shutting it down at the end of the test.
+or a selenium server running. Unlike starting up an instance of
+S::R::D, do not pass the C<remote_server_addr> and C<port> arguments,
+and we will search for the Firefox executable in your $PATH. We'll try
+to start the binary, connect to it, and shut it down at the end of the
+test.
 
 If the Firefox application is not found in the expected places, we'll
 fall back to the default L<Selenium::Remote::Driver> behavior of
 assuming defaults of 127.0.0.1:4444 after waiting a few seconds.
 
-If you specify a remote server address, or a port, we'll assume you
-know what you're doing and take no additional behavior.
+If you specify a remote server address, or a port, our assumption is
+that you are doing standard S::R::D behavior and we will not attempt
+any binary startup.
 
 If you're curious whether your Selenium::Firefox instance is using a
 separate Firefox binary, or through the selenium server, you can check
-the C<binary_mode> attr after instantiation.
+the value of the C<binary_mode> attr after instantiation.
 
 =cut
 
@@ -38,10 +45,16 @@ has '+browser_name' => (
 
 =attr binary
 
-Optional: specify the path to your binary. If you don't specify
-anything, we'll try to find it on our own in the default installation
-paths for Firefox. If your Firefox is elsewhere, we probably won't be
-able to find it, so you may be well served by specifying it yourself.
+Optional: specify the path to the C<geckodriver> binary - this is NOT
+the path to the Firefox browser. To specify the path to your Firefox
+browser binary, see the L</firefox_binary> attr.
+
+For Firefox 48 and greater, this is the path to your C<geckodriver>
+executable. If you don't specify anything, we'll search for
+C<geckodriver> in your $PATH.
+
+For Firefox 47 and older, this attribute does not apply, because the
+older FF browsers do not use the separate driver binary startup.
 
 =cut
 
@@ -71,6 +84,20 @@ has 'binary_port' => (
     default => sub { 9090 }
 );
 
+=attr firefox_profile
+
+Optional: Pass in an instance of L<Selenium::Firefox::Profile>
+pre-configured as you please. The preferences you specify will be
+merged with the ones necessary for setting up webdriver, and as a
+result some options may be overwritten or ignored.
+
+    my $profile = Selenium::Firefox::Profile->new;
+    my $firefox = Selenium::Firefox->new(
+        firefox_profile => $profile
+    );
+
+=cut
+
 has '_binary_args' => (
     is => 'lazy',
     builder => sub {
@@ -107,6 +134,10 @@ already bound, we'll search above it until we find an open one.
         marionette_binary_port => 12345,
     );
 
+Attempting to specify a C<marionette_binary_port> in conjunction with
+setting C<marionette_enabled> does not make sense and will most likely
+not do anything useful.
+
 =cut
 
 has 'marionette_binary_port' => (
@@ -116,26 +147,15 @@ has 'marionette_binary_port' => (
 
 =attr marionette_enabled
 
-Optional: specify whether L<marionette|https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette>
-should be enabled or not. If you enable the marionette_enabled flag,
-Firefox is launched with marionette server listening to
-C<marionette_binary_port>.
-
-The firefox binary must have been built with this funtionality and it's
-available in L<all recent Firefox binaries|https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/Builds>.
+Optional: specify whether
+L<marionette|https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette>
+should be enabled or not. By default, marionette is enabled, which
+assumes you are running with Firefox 48 or newer. To use this module
+to start Firefox 47 or older, you must pass C<marionette_enabled =>
+0>.
 
-Note: L<Selenium::Remote::Driver> does not yet provide a marionette
-client. It's up to the user to use a client or a marionette-to-webdriver
-proxy to communicate with the marionette server.
-
-    Selenium::Firefox->new( marionette_enabled => 1 );
-
-and Firefox will have 2 ports open. One for webdriver and one
-for marionette:
-
-    netstat -tlp | grep firefox
-    tcp    0    0    localhost:9090    *:*    LISTEN    23456/firefox
-    tcp    0    0    localhost:2828    *:*    LISTEN    23456/firefox
+    my $ff48 = Selenium::Firefox->new( marionette_enabled => 1 ); # defaults to 1
+    my $ff47 = Selenium::Firefox->new( marionette_enabled => 0 );
 
 =cut
 
@@ -144,6 +164,21 @@ has 'marionette_enabled' => (
     default => 1
 );
 
+=attr firefox_binary
+
+Optional: specify the path to the Firefox browser executable. Although
+we will attempt to locate this in your $PATH, you may specify it
+explicitly here. Note that path here must point to a file that exists
+and is executable, or we will croak.
+
+For Firefox 48 and newer, this will be passed to C<geckodriver> such
+that it will attempt to start up the Firefox at the specified path.
+
+For Firefox 47 and older, this browser path will be the file that we
+directly start up.
+
+=cut
+
 has 'firefox_binary' => (
     is => 'lazy',
     predicate => 1,
@@ -159,6 +194,12 @@ Optional: specify any additional command line arguments you'd like
 invoked during the binary startup. See
 L<Selenium::CanStartBinary/custom_args> for more information.
 
+For Firefox 48 and newer, these arguments will be passed to
+geckodriver during start up.
+
+For Firefox 47 and older, these arguments will be passed to the
+Firefox browser during start up.
+
 =attr startup_timeout
 
 Optional: specify how long to wait for the binary to start itself and