=pod

=head1 NAME

WWW::Mechanize::Firefox::Troubleshooting - Things to watch out for

=head1 Installation

If you notice that tests get skipped and/or the module installs
but "does not seem to work", there are some more steps required
to configure Firefox. Please see L<WWW::Mechanize::Firefox::Installation>
for more information.

=head2 C<< Failed to connect to , problem connecting to "localhost", port 4242: Connection refused at ... >>

The C<mozrepl> plugin is not correctly installed or not configured
to listen in Firefox on port 4242.

=over 4

=item 1.

Check that Firefox is listening on port 4242:

  telnet localhost 4242

If this does fail with some error message, you have either a firewall
issue or the C<mozrepl> extension is not properly installed.

=item 2.

Go through the steps in
L<WWW::Mechanize::Firefox::Installation> to verify that the C<mozrepl>
extension is installed.

=back

=head1 Dialogs that break your application

This section lists things that can (and will) happen which might
block your Perl scripts from working properly
with Firefox.

=head2 Save-As Dialog Displays

If a webserver sends the appropriate headers, Firefox will ask the
user where to save a file. This dialog will pop up and stall
the Perl application until a user clicks "OK" to confirm where
to save the file.

=head3 Solution

Find where Firefox pops up the dialog and replace that with a
callback to Perl.

=head3 Workaround

In many cases, you can instruct Firefox to always save files
into the same folder. This may or may not be acceptable.
You can directly call C<< ->get >> or C<< ->save_url >>
and also specify where to save the content by using

  $mech->get( $url, ':content_file' => $tempfile );

or alternatively

  $mech->save_url( $url => $target_filename );

Both of these workarounds require you to know the URL
you want to download.

=head2 Updates to Firefox Add-Ons

The dialog notification for new versions of Add-Ons is not
yet automated. If Firefox pops up this dialog, your application
will stall until a human closes this dialog.

=head3 Solution

Find where Firefox pops up this dialog and override the display either
through a setting or through replacing the Javascript code with
the appropriate Perl code.

=head3 Workaround

Disable checking for and notification about updated Add-Ons.

=head2 Proxy password

If a fresh Firefox process is launched and a proxy is configured,
Firefox will ask for the credentials needed for that proxy.
The Perl script will stall until a human enters or confirms
the credentials.

=head3 Solution

Find where Firefox pops up this dialog and override the display
with a function that supplies the appropriate credentials
directly.

=head3 Workaround

There is no workaround.

=head1 Scripting

=head2 Clicking on a link makes the Perl script wait forever

If you have something like the following code:

  $mech->click('#a_link');

WWW::Mechanize::Firefox expects a HTTP interaction ("a web request") to
ensue and will wait until a new page is loaded. If the element your
script clicks on only changes some aspect of the Javascript page, like
acknowledging a message, then no HTTP interaction will occur and
your script will wait forever.

=head3 Solution

For those requests, pass the C<< synchronize => 0 >> option:

  $mech->click({ selector => '#a_link', synchronize => 0 });

This will tell WWW::Mechanize::Firefox not to wait for any response
from the webserver.

=head2 A tab remains open even after the program closes

If you have something like the following code:

  my $mech = WWW::Mechanize::Firefox->new();

  sub page_title {
      $mech->selector( 'div.title', single => 1 )->{innerHTML};
  };

then Perl will keep the C<$mech> object alive until the program ends
and Global Destruction of all objects starts. As Global Destruction
happens in a non-deterministic order, this will sometimes prevent
the C<$mech> object from properly closing the Firefox tab attached to it.

For debugging whether that is really the cause,
set C<$MozRepl::RemoteObject::WARN_ON_LEAK> to a true value. This will
emit warnings to C<STDERR> if objects cannot release their Firefox
counterpart during Global Destruction.

=head3 Solution

Pass the C<$mech> object around as parameter:

  my $mech = WWW::Mechanize::Firefox->new();

  sub page_title {
      my ($mech) = @_;
      $mech->selector( 'div.title', single => 1 )->{innerHTML};
  };

Alternatively, explicitly set C<$mech> to C<undef> at the end of
your main program:

  ...
  undef $mech;

=head2 The script crashes with maximum input buffer length exceeded

When taking a screenshot of a large page, the script crashes with

  maximum input buffer length exceeded: 1048576 bytes ...

=head3 Solution

Pass the C<bufsize> parameter to the WWW::Mechanize::Firefox constructor
to give L<Net::Telnet> a larger buffer:

  my $firefox = WWW::Mechanize::Firefox->new(
      bufsize => 10_000_000,
  );

=head2 Javascript error "0x8007000e (NS_ERROR_OUT_OF_MEMORY)" on C<< ->content_as_png >>

This error is caused because of Firefox 4 bug 649924
(L<https://bugzilla.mozilla.org/show_bug.cgi?id=649924>). It seems
that the Firefox C<< canvas >> element is size-limited when
hardware acceleration is enabled.

=head3 Workaround

Until that bug is fixed, disable hardware acceleration and restart Firefox 4.

=head1 Known Problems

=head2 Page Encoding Versus Perl Encoding

Currently, whatever Firefox delivers as the page content
is decoded to UTF-8 unless it already is. This is likely not the case in some
situations, for example with pages encoded in koi-8. Please send
me test cases where decoding fails or does not produce the
correct data.

=head1 AUTHOR

Max Maischein C<corion@cpan.org>

=head1 COPYRIGHT

Copyright 2010-2014 by Max Maischein C<corion@cpan.org>.

All Rights Reserved. This module is free software. It may be used,
redistributed and/or modified under the same terms as Perl itself.

=cut