=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:

=over 4

=item 1.

Install mozrepl 1.1.0 available from

L<http://wiki.github.com/bard/mozrepl/>

respectively

L<https://github.com/bard/mozrepl/tags>

You will need to edit the C<.zip> file into a C<.xpi> file.

=item 2.

Launch Firefox

=item 3.

Start C<mozrepl> in Firefox by going to the menu:

   "Tools" -> "MozRepl" -> "Start"

You may want to tick the "Activate on startup" item.

Alternatively, launch the Firefox binary with the C<-mozrepl> command line
switch:

  firefox -repl

If tests still fail, especially t/50-click.t and 51-mech-submit.t ,
this might be because you use the NoScript Mozilla extension
and have it blocking Javascript for file:// URLs. While this is good,
the tests need Javascript enabled.

Solution:

=over 4

=item 1.

Open t/50-click.html in Firefox

=item 2.

Allow Javascript for all file:// URLs

=item 3.

Re-run tests

=item 4.

No test should fail

=back

If tests fail with an error from Firefox that a file could not
be found, check that the test suite and the Firefox process are
run using the same user. Otherwise, the Firefox process might not
have the permissions to access the files created by the test suite.

=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-2012 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