Document the new on_error init arg and setter/clearer

lib/Selenium/Remote/Driver.pm

@@ -150,6 +150,7 @@ available here.
         'default_finder'       - <string>   - choose default finder used for find_element* {class|class_name|css|id|link|link_text|name|partial_link_text|tag_name|xpath}
         'inner_window_size'    - <aref[Int]>- An array ref [ height, width ] that the browser window should use as its initial size immediately after instantiation
         'webelement_class'     - <string>   - sub-class of Selenium::Remote::WebElement if you wish to use an alternate WebElement class.
+        'on_error'             - CODEREF     - A CODEREF that we will call in event of any exceptions. See L</on_error> for more details.
         'ua'                   - LWP::UserAgent instance - if you wish to use a specific $ua, like from Test::LWP::UserAgent
 
     If no values are provided, then these defaults will be assumed:
@@ -201,6 +202,55 @@ available here.
     or
     my $driver = Selenium::Remote::Driver->new('default_finder' => 'css');
 
+=head3 on_error
+
+=head3 clear_on_error
+
+OPTIONAL constructor arg & associated setter/clearer: if you wish to
+install your own error handler, you may pass a code ref in to
+C<on_error> during instantiation like follows:
+
+    my $driver = Selenium::Remote::Driver->new(
+        on_error => sub { print $_[1]; croak 'goodbye'; }
+    );
+
+Additionally, you can set and/or clear it at any time on an
+already-instantiated driver:
+
+    # later, change the error handler to something else
+    $driver->on_error( sub { print $_[1]; croak 'hello'; } );
+
+    # stop handling errors manually and use the default S:R:D behavior
+    # (we will croak about the exception)
+    $driver->clear_on_error;
+
+Your error handler will receive two arguments: the first argument is
+the C<$driver> object itself, and the second argument is the exception
+message and stack trace in one multiline string.
+
+B<N.B.>: If you set your own error handler, you are entirely
+responsible for handling webdriver exceptions, _including_ croaking
+behavior. That is, when you set an error handler, we will no longer
+croak on Webdriver exceptions - it's up to you to do so. For
+consistency with the standard S:R:D behavior, we recommend your error
+handler also croak when it's done, especially since your test
+shouldn't be running into unexpected errors. Catching specific or
+desired errors in your error handler makes sense, but not croaking at
+all can leave you in unfamiliar territory. Reaching an unexpected
+exception might mean your test has gone off the rails, and the further
+your test gets from the source of the of the exception, the harder it
+will be to debug.
+
+B<N.B.>: Four methods will still croak on their own: L</find_element>,
+L</find_elements>, L</find_child_element>, and
+L</find_child_elements>. If these methods throw a Webdriver Exception,
+your error handler _will still be_ invoked inside an C<eval>, and then
+they'll croak with their own error message that indicates the locator
+and strategy used. So, your strategies for avoiding exceptions when
+finding elements do not change (either use find_elements and check
+the returned array size, wrap your calls to find_element* in an
+C<eval>, or use the parameterized versions find_element_*).
+
 =head2 new_from_caps
 
  Description:
@@ -225,6 +275,7 @@ available here.
         default_finder       - STRING  - defaults to xpath
         webelement_class     - STRING  - defaults to Selenium::Remote::WebElement
         auto_close           - BOOLEAN - defaults to 1
+        on_error             - CODEREF - defaults to croaking on exceptions
 
     Except for C<desired_capabilities>, these keys perform exactly the
     same as listed in the regular "new" constructor.
@@ -462,6 +513,9 @@ sub DEMOLISH {
     $self->quit() if ( $self->auto_close && defined $self->session_id );
 }
 
+# We install an 'around' because we can catch more exceptions this way
+# than simply wrapping the explicit croaks in _execute_command.
+
 around '_execute_command' => sub { 
     my $orig = shift; 
     my $self = shift;