Describe Selenium::Firefox's breaking changes

README.md

@@ -55,15 +55,17 @@ elements would be the same.
 ### no standalone server
 
 - _Firefox 48 & newer_: install the Firefox browser, download
-  [geckodriver][gd] and [put it in your `$PATH`][fxpath]. 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.
+  [geckodriver][gd] and [put it in your `$PATH`][fxpath]. 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 binary
-  location during startup.
+  default place for your OS, you may have to specify the
+  `firefox_binary` constructor option during startup.
 
 - _Chrome_: install the Chrome browser, [download Chromedriver][dcd]
   and get `chromedriver` in your `$PATH`.
@@ -100,6 +102,35 @@ See the pod for the different modules for more details.
 [fxpath]: https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver#Add_executable_to_system_path
 [gd]: https://github.com/mozilla/geckodriver/releases
 
+#### 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:
+
+```perl
+# 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:
+
+```perl
+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:

lib/Selenium/Firefox.pm

@@ -8,11 +8,10 @@ extends 'Selenium::Remote::Driver';
 
 =head1 SYNOPSIS
 
-    # these two are the same, and will only work with Firefox 48 and
-    # greater
+    # These two are the same, and will only work with Firefox 48+
     my $driver = Selenium::Firefox->new;
     my $driver = Selenium::Firefox->new( marionette_enabled => 1 );
-    # execute your test as usual
+    ...
     $driver->shutdown_binary;
 
     # For Firefox 47 and older, disable marionette:
@@ -21,6 +20,11 @@ extends 'Selenium::Remote::Driver';
 
 =head1 DESCRIPTION
 
+B<Breaking Changes:> There are breaking changes in v1.0+ of this
+module if you're using it to start FF47; please see L</"Breaking
+Changes">. You can ignore this if you're using v1.0+ of this module to
+start FF48.
+
 This class allows you to use the FirefoxDriver without needing the JRE
 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,
@@ -40,6 +44,43 @@ If you're curious whether your Selenium::Firefox instance is using a
 separate Firefox binary, or through the selenium server, you can check
 the value of the C<binary_mode> attr after instantiation.
 
+=head1 BREAKING CHANGES
+
+In version v1.0+ and newer, the default behavior is to enable
+marionette & geckodriver mode. This means that an existing script that
+works with v0.2701 and Firefox v47 will require modification if you
+upgrade Selenium::Firefox to v1.0+. That is,
+
+    # v0.2701 of Selenium::Firefox works with FF47 like such; this will not
+    # work for FF47 after upgrade:
+    my $fx47_old = Selenium::Firefox->new;
+    ...
+    $fx47_old->shutdown_binary;
+
+    # v1.0 of Selenium::Firefox works with FF47 like this
+    my $fx47_new = Selenium::Firefox->new( marionette_enabled => 0);
+    ...
+    $fx47_new->shutdown_binary;
+
+We default to assuming FF48 and geckodriver mode because all
+forthcoming versions of the Firefox browser will be using the
+geckodriver architecture, and also because that's consistent with the
+rest of the driver setups, which all have separate driver binaries
+apart from the browser itself. This means that:
+
+    # v0.2701 of Selenium::Firefox cannot start up FF48 at all
+
+    # v1.0+ of Selenium::Firefox works with FF48+ like this:
+    my $fx48 = Selenium::Firefox->new;
+
+As with the other drivers, Selenium::Firefox in marionette/geckodriver
+mode requires a `geckodriver` executable in the path or provided
+during startup, and it will also attempt to find the path to your
+Firefox browser. During testing, we found that it was necessary for us
+to pass the Firefox browser file path to the `geckodriver` executable
+during start up, or else `geckodriver` would have trouble finding
+Firefox.
+
 =cut
 
 has '+browser_name' => (
@@ -186,7 +227,10 @@ 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.
+that it will attempt to start up the Firefox at the specified path. If
+you do not specify anything, we will look for the Firefox browser on
+our own in the normal places, but if the browser cannot be found,
+we'll probably C<die> during instantiation.
 
 For Firefox 47 and older, this browser path should be the file that we
 directly start up.