=head1 INSTALLING WWW::Mechanize::Chrome

=head2 Install the C<chrome> executable

C<WWW::Mechanize::Chrome> requires that you have the Chrome browser installed
on your system. If Chrome is not installed, please consult
L<Google's instructions|https://support.google.com/chrome/answer/95346> for
help installing the Chrome browser.

C<WWW::Mechanize::Chrome> will do its best to locate Chrome's executable file
on your system. With any luck, it will find the executable you want to use. If
C<WWW::Mechanize::Chrome> does not find Chrome on your system or you want to
use a different executable, you can use the C<launch_exe> constructor argument
to tell C<WWW::Mechanize::Chrome> where to find it. You can also set the
C<CHROME_BIN> environment variable to the absolute path of the executable.

=head2 Test the C<chrome> executable

You should verify that Chrome's executable is working properly. On Ubuntu, the
executable is typically named C<chrome-browser> and so you can test Chrome's
installation with:

C<chrome-browser --version>

and you should see something like C<Google Chrome 67.0.3396.99> returned.

Note that the command you run will vary based on your operating system and
possibly the version of Chrome installed.

On a Debian system, for example, the command will most likely be something
like:

C<google-chrome-stable --version> or
C<google-chrome-beta --version> or
C<google-chrome-unstable --version>

On Windows, the executable is named C<chrome.exe> and doesn't output
information to the console but you can check that Chrome starts by running:

C<chrome>

in the terminal.

On MacOS, the executable can usually be be found inside the C<Google Chrome.app>
package in the C</Applications> directory and its installation can be
tested with something like the following:

C</Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version>

or, if Chrome is installed for a single user:

C</Users/<user_nameE<gt>/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version>

If you are having trouble finding, installing, or running Chrome on your
system, please consult the appropriate documentation or a knowledgeable expert.

=head2 Chrome versions

Note that the Chrome version numbers do not denote availability of features.
Features can still be added to Chrome v62 when Chrome v64 is already out.

If you are serious about automating a website, use a separate copy of Chrome
and disable its automatic updates.

=head2 Module prerequisites on OSX

=head3 L<Imager::File::PNG>

This module relies on L<Imager> for processing screenshots. If you don't need
this functionality, you can ignore the L<Imager> and L<Imager::File::PNG>
installation and use this module with the system Perl provided by Apple.

The installation of L<Imager::File::PNG> works on OSX using the Homebrew tool
and the Perl installable through Homebrew:

    brew install perl-5.28
    brew install libpng
    cpan Imager::File::PNG

I haven't been able to make it work using the system Perl.

=head1 RUNNING THE TEST SUITE

The normal test invocation is 'make test'.

If your executable has a different name than C<chrome-browser> or
C<chrome.exe> or is not in your path, then set the environment variable
C<CHROME_BIN> to the absolute path.

If you have Chrome already running, it must have been started with the
C<<--remote-debugging-port=9222>> option to enable access to the developer API.
You may want to set up a dedicated and version pinned version of Chrome for your
automation.

=head2 Running Chrome on a different X display

All supported versions of Chrome support the headless mode now.
If you want to observe what the browser is doing on a different X display,
you can achieve that by (1) not running any chrome binary and (2) start a
separate display with Xvfb and (3) set the DISPLAY variable accordingly. E.g.:

  Xvfb :121 &
  DISPLAY=:121 CHROME_BIN=/usr/bin/google-chrome-stable make test

=head1 INSTALLING CUSTOM VERSIONS OF CHROME

When doing serious testing, automation or scraping, you want to use a separate
instance of the browser. You should install it into its own directory
and disable automatic updates.

=head2 Windows

Woolyss.com keeps an archive of old Chrome builds. Download the "Archive"
version you want from here and unpack the archive it into its own directory:

L<https://chromium.woolyss.com/#windows-64-bit>

You can then use the custom Chrome executable by setting (for example)

  set CHROME_BIN=C:\Scraping\chrome-versions\chrome-win32-78.0.3904.0\chrome.exe

=head2 Debian (Linux)

This site keeps an archive of old Chrome builds for Linux. Download the
"Linux_portable" version you want from here and unpack the archive it into its own directory:

L<https://ungoogled-software.github.io/ungoogled-chromium-binaries/releases/linux_portable/64bit/>

These packages are supposed to work on any supported Linux distribution.

=cut
