WWW::Me...:Chrome(3)

📦

version 0.78 · 3 versions

0.78 · fedora 43, fedora 44 (latest)
0.73 · fedora 43
0.75 · fedora 44

WWW::Mechanize::Chrome(3) User Contributed Perl Documentation

✨ NAME ✨

WWW::Mechanize::Chrome — automate the Chrome browser

🌸 SYNOPSIS 🌸

use Log::Log4perl qw(:easy);
use WWW::Mechanize::Chrome;

Log::Log4perl->easy_init($ERROR);  # Set priority of root logger to ERROR
my $mech = WWW::Mechanize::Chrome->new();
$mech->get('https://google.com');

$mech->eval_in_page('alert("Hello Chrome")');
my $png = $mech->content_as_png();

Okay bestie, a collection of other Examples is available to help you get started. 🫶

DESCRIPTION 💖

Okay so lowkey, WWW::Mechanize::Chrome is giving WWW::Mechanize energy: it automates web browsing with a Perl object. But instead of doing the fetch-and-render thing itself, it hands that job to the Chrome (or Chromium) browser — it starts up an instance and controls it with Chrome DevTools (https://developers.google.com/web/tools/chrome-devtools/). It's literally the main character of browser automation, no cap. 💅

🦋 Advantages Over WWW::Mechanize 🦋

The Chrome browser provides advanced abilities useful for automating modern web applications that are not (yet) possible with WWW::Mechanize alone:

Page content can be created or modified with JavaScript. You can also execute custom JavaScript code on the page content. ✨
Page content can be selected with CSS selectors. 💅
Screenshots of the rendered page as an image or PDF file. 🎀

💀 Disadvantages 💀

Installation of a Chrome compatible browser is required. There are some quirks including sporadic, but harmless, error messages issued by the browser when run with with DevTools. Not the vibe, but it's fine. 🙈

🧚 A Brief Operational Overview 🧚

WWW::Mechanize::Chrome (WMC) leverages developer tools built into Chrome and Chrome-like browsers to control a browser instance programmatically. You can use WMC to automate tedious tasks, test web applications, and perform web scraping operations. Iconic behavior, honestly. 👑

Typically, WMC is used to launch both a host instance of the browser and provide a client instance of the browser. The host instance of the browser is visible to you on your desktop (unless the browser is running in "headless" mode, in which case it will not open in a window). The client instance is the Perl program you write with the WMC module to issue commands to control the host instance. As you navigate and "click" on various nodes in the client browser, you watch the host browser respond to these actions as if by magic. Literally magic. 🪄

This magic happens as a result of commands that are issued from your client to the host using Chrome's DevTools Protocol which implements the http protocol to send JSON data structures. The host also responds to the client with JSON to describe the web pages it has loaded. WMC conveniently hides the complexity of the lower level communications between the client and host browsers and wraps them in a Perl object to provide the easy-to-use methods documented here. 💖

✨ OPTIONS ✨

🎀 `WWW::Mechanize::Chrome->new( %options )`

my $mech = WWW::Mechanize::Chrome->new(
    headless => 0,
);

`autodie`

autodie => 0   # make HTTP errors non-fatal

So by default autodie is true, bestie. If an HTTP error shows up, the program just dies and takes its whole browser entourage down with it 😭. The upside? You never have to write an error check after every single request — the vibes are very "it handles itself." Set it to false and HTTP errors stop being fatal, so your program keeps on running even when something goes wrong. 🫶

`headless`

Don't show a browser window. Default is to show a browser window. 👀

`host`

`listen_host`

Pick the host the browser listens on:

host => '192.168.1.2'
host => 'localhost'

Defaults to 127.0.0.1. The browser listens for commands on whatever host you give it. Heads up though — that host address should not be reachable from the internet, fr fr. 🙈

`port`

port => 9223   # set port the launched browser will use for remote operation

Defaults to 9222. All the commands to the browser get issued through this port. 🔌

`tab`

Tell Chrome which browser tab to use:

tab => 'current'
tab => qr/PerlMonks/

By default a web page opens in a new tab. Set tab to "current" and it'll use the current, active tab instead. Or, if you wanna grab an existing <em>inactive</em> tab, pass a regular expression and it gets matched against that tab's title. A false value just means "default behavior," so a brand new tab gets created. ✨

`autoclose`

autoclose => 0   # keep tab open after program end

By default autoclose is true, so the tab your code opened gets closed. Set it to a false value and the tab stays open even after your program is done. 👑

`launch_exe`

Set the name and/or path to the browser's executable:

launch_exe => 'name-of-chrome-executable'   # for non-standard executable names
launch_exe => '/path/to/executable'         # for non-standard paths
launch_exe => '/path/to/executable/chrome'  # full path

By default, WWW::Mechanize::Chrome searches the appropriate paths for Chrome's executable based on your operating system. Use this option if your executable lives somewhere non-standard or has a non-standard name.

The default paths it searches are the ones in $ENV{PATH}. On OS X, the user and system Application directories get searched too. Default executable file names are chrome on Windows, Google Chrome on OS X, and google-chrome everywhere else. 🌍

Want Chromium? You gotta say so explicitly, like:

launch_exe => 'chromium-browser', # if Chromium is named chromium-browser on your OS

Results may vary depending on your OS. If things are being weird, use the full path to the browser's executable. You can also set the executable file's name with the $ENV{CHROME_BIN} environment variable. 🛠️

Extra arguments for the command also get read from the <$ENV{WWW_MECHANIZE_CHROME_ARGS}> variable and prepended to the launch_arg array.

`cleanup_signal`

cleanup_signal => 'SIGKILL'

This is the signal sent to Chrome to shut it down. On Linuxish OSes it'll be TERM, and on OSX and Windows it'll be KILL. 💀

`start_url`

start_url => 'http://perlmonks.org'  # Immediately navigate to a given URL

By default the browser opens with a blank tab. Use start_url to open straight to a URL you picked. Usually though, people use the ->get method to navigate. The catch with start_url? You don't get notified when the URL has finished loading. 🙃

`launch_arg`

Pass extra switches and parameters to the browser's executable:

launch_arg => [ "--some-new-parameter=foo", "--another-option" ]

Some other genuinely useful parameters include:

'--start-maximized',
'--window-size=1280x1696'
'--ignore-certificate-errors'

'--disable-web-security',
'--allow-running-insecure-content',

'--load-extension'
'--no-sandbox'

If you don't want the browser touching your OS password store, add:

'--password-store=basic'

Also peep <https://peter.sh/experiments/chromium-command-line-switches/> for a list of command line arguments that Chrome actually has in the source code. 🔍

Extra arguments for the command also get read from the <$ENV{WWW_MECHANIZE_CHROME_ARGS}> variable and prepended to the launch_arg array.

`separate_session`

separate_session => 1   # create a new, empty session

This makes a fresh, empty Chrome session with zero cookies. Setting this means any data_directory setting just gets ignored. 🧼

`incognito`

incognito => 1   # open the browser in incognito mode

Defaults to false. Set it to true and the browser launches in incognito mode. 🕵️

Most likely though, you actually want separate_session instead.

`data_directory`

data_directory => '/path/to/data/directory'  #  set the data directory

By default a temporary data directory is used. Use this setting to change the base data directory for the browsing session.

use File::Temp 'tempdir';
# create a fresh Chrome every time, this is the default
my $mech = WWW::Mechanize::Chrome->new(
    data_directory => tempdir(CLEANUP => 1 ),
);

Want the main Chrome cookies? Do this:

my $mech = WWW::Mechanize::Chrome->new(
    data_directory => '/home/corion/.config/chromium',
);

`profile`

profile => 'ProfileDirectory'  #  set the profile directory

By default your current user profile directory is used. Use this setting to change the profile directory for the browsing session.

You'll need to set the data_directory as well, so Chrome can actually find the profile inside the data directory. And the profile directory/name itself has to be a single directory name, <em>not</em> the full path. That single directory name is relative to the data directory. 📁

`wait_file`

wait_file => "$tempdir/CrashpadMetrics-active.pma"

When shutting down, it waits until this file no longer exists or can be deleted. This helps make sure the Chrome process has <em>really</em> shut down. ✋

`startup_timeout`

startup_timeout => 5  # set the startup timeout value

Defaults to 20, which is the maximum number of seconds to wait for the browser to launch. Go higher or lower based on how fast your machine is. During that window, the process tries to connect to the browser once every second. ⏱️

`driver`

driver => $driver_object  # specify the driver object

Use a Chrome::DevToolsProtocol::Target object that you constructed manually. 🧰

`report_js_errors`

report_js_errors => 1  # turn javascript error reporting on

Defaults to false. If true, it checks for Javascript errors and warns after each request. Super handy for testing with use warnings qw(fatal). 🐛

`mute_audio`

mute_audio => 0  # turn sounds on

Defaults to true (sound off). A false value turns the sound back on. 🔊

`background_networking`

background_networking => 1  # turn background networking on

Defaults to false (off). A true value enables background networking. 🌐

`client_side_phishing_detection`

client_side_phishing_detection => 1  # turn client side phishing detection on

Defaults to false (off). A true value enables client side phishing detection. 🎣

`component_update`

component_update => 1  # turn component updates on

Defaults to false (off). A true value enables component updates. 🔄

`default_apps`

default_apps => 1  # turn default apps on

Defaults to false (off). A true value enables default apps. 📱

`hang_monitor`

hang_monitor => 1  # turn the hang monitor on

Defaults to false (off). A true value enables the hang monitor. 🚨

`hide_scrollbars`

hide_scrollbars => 1  # hide the scrollbars

Defaults to false (off). A true value hides the scrollbars. 🫥

`infobars`

infobars => 1  # turn infobars on

Defaults to false (off). A true value turns infobars on. ℹ️

popup_blocking => 1  # block popups

Defaults to false (off). A true value blocks popups. 🚫

`prompt_on_repost`

prompt_on_repost => 1  # allow prompts when reposting

Defaults to false (off). A true value allows prompts when reposting. ↩️

`save_password_bubble`

save_password_bubble => 1  # allow the display of the save password bubble

Defaults to false (off). A true value lets the save password bubble show up. 💬

`sync`

sync => 1   # turn syncing on

Defaults to false (off). A true value turns syncing on. 🔁

`web_resources`

web_resources => 1   # turn web resources on

Defaults to false (off). A true value turns web resources on. 🕸️

`json_log_file`

Filename to log all JSON communications to, one line per message/event/reply. 📝

`json_log_fh`

Filehandle to log all JSON communications to, one line per message/event/reply.

Open that filehandle like this:

open my $fh, '>:utf8', $logfilename
    or die "Couldn't create '$logfilename': $!";

The $ENV{WWW_MECHANIZE_CHROME_TRANSPORT} variable can be set to a different transport class to override the default transport class. This is mostly used for testing, but it can also help you avoid introducing bugs from whatever underlying websocket implementation(s) you're running. 🧪

The $ENV{WWW_MECHANIZE_CHROME_CONNECTION_STYLE} variable can be set to either websocket or pipe to specify the kind of transport you want to use. 🚰

The pipe transport is only available on unixish OSes, and only with Chrome v72 onwards. 💅

✨ METHODS ✨ (still going bestie, we're so back)

🌸 `WWW::Mechanize::Chrome->find_executable`

my $chrome = WWW::Mechanize::Chrome->find_executable();

my $chrome = WWW::Mechanize::Chrome->find_executable(
    'chromium.exe',
    '.\\my-chrome-66\\',
);

my( $chrome, $diagnosis ) = WWW::Mechanize::Chrome->find_executable(
    ['chromium-browser','google-chrome'],
    './my-chrome-66/',
);
die $diagnosis if ! $chrome;

Okay so this one goes hunting for the first Chrome executable it can find in the path ($ENV{PATH}). On Windows, it also peeks in $ENV{ProgramFiles}, $ENV{ProgramFiles(x86)} and $ENV{"ProgramFilesW6432"}. On OSX it also checks the user home directory, as given through $ENV{HOME}. 🏠

It's the vibe-check used to find the default Chrome executable when you didn't pass one through the "launch_exe" option — or when you did give an executable but it doesn't exist and doesn't contain a directory separator. Like, it's out here doing the detective work so you don't have to. 🔍

🦋 `$mech->chrome_version`

print $mech->chrome_version;

A synonym for ->browser_version. Same energy, different name, no cap. 💅

🦋 `$mech->browser_version`

print $mech->browser_version;

Returns the version of the browser executable being used. Heads up bestie — getting this info needs launching the browser and asking for the version over the network. It's not free, it's a whole little journey. 🌐

🦋 `$mech->chrome_version_info`

print $mech->chrome_version_info->{product};

Returns the version info of the Chrome executable plus a bunch of other Chrome APIs that the object is connected to. It's giving ✨full context✨.

💜 `$mech->driver`

deprecated — use ->target instead

my $driver = $mech->driver

Gives you the Chrome::DevToolsProtocol instance connecting to Chrome.

Deprecated, don't use this anymore. Most likely you want ->target to talk to the Chrome tab, or ->transport to talk to the Chrome instance. Like, it still works but it's so last season, fr fr. 🙈

💜 `$mech->target`

my $target = $mech->target

Gives you the Chrome::DevToolsProtocol::Target instance connecting to the Chrome tab we're using. This is the one you actually want, bestie. 🎯

💜 `$mech->transport`

my $transport = $mech->transport

Gives you the Chrome::DevToolsProtocol::Transport instance connecting to the Chrome instance. The whole connection, the main character. 👑

💜 `$mech->tab`

my $tab = $mech->tab

Gives you the tab hash of the Chrome::DevToolsProtocol::Target instance — the one representing the tab we control. It's the tab's whole little identity card. 🪪

🎀 `$mech->new_tab` / `$mech->new_tab_future`

my $tab2 = $mech->new_tab_future(
    start_url => 'https://google.com',
)->get;

Creates a new tab — which is basically a whole new WWW::Mechanize::Chrome object — connected to the same Chrome session. New tab, who dis. ✨

# Use a targetInfo structure from Chrome
my $tab2 = $mech->new_tab_future(
    tab => {
        'targetId' => '1F42BDF32A30700805DDC21EDB5D8C4A',
    },
)->get;

It returns a Future because most event loops are so dramatic about recursing within themselves, which is exactly what happens if you want to grab a fresh new tab from inside another callback. So the future keeps the vibes calm. 🧘♀️

🎉 EVENTS 🎉

🍓 `"popup"`

my $opened;
$mech->on( 'popup' => sub( $mech, $tab_f ) {
    # This is a bit heavyweight, but ...
    $tab_f->on_done(sub($tab) {
        say "New window/tab was popped up:";
        $tab->uri_future->then(sub($uri) {
            say $uri;
        });
        $opened = $tab;
    })->retain;
});

$mech->click({ selector => '#popup_window' });
if( $opened ) {
    say $opened->title;
} else {
    say "Did not find new tab?";
};

This event fires whenever a new tab/window gets popped up or created. The callback is handed the current WWW::Mechanize::Chrome instance and a second one. ⚠️ Note that depending on your event loop, you're quite restricted on what synchronous methods you can call from inside the callback. So like, play it cool in there, bestie. 😌

🌈 `$mech->allow( %options )`

$mech->allow( javascript => 1 );

Allow or disallow execution of Javascript. Yes ma'am, it's the on/off switch. 🔛

🌈 `$mech->emulateNetworkConditions( %options )`

# Go offline
$mech->emulateNetworkConditions(
    offline => JSON::true,
    latency => 10, # ms ping
    downloadThroughput => 0, # bytes/s
    uploadThroughput => 0, # bytes/s
    connectionType => 'offline', # cellular2g, cellular3g, cellular4g, bluetooth, ethernet, wifi, wimax, other.
);

🌈 `$mech->setRequestInterception( @patterns )`

$mech->setRequestInterception(
    { urlPattern => '*', resourceType => 'Document', interceptionStage => 'Request'},
    { urlPattern => '*', resourceType => 'Media', interceptionStage => 'Response'},
);

Sets the list of request patterns and resource types for which the interception callback will be invoked. Like a lil bouncer for your network traffic. 🚧

🌈 `$mech->continueInterceptedRequest( %options )`

$mech->continueInterceptedRequest_future(
    interceptionId => ...
);

Continues an intercepted request. Cool, carry on, nothing to see here. 💫

🌈 `$mech->add_listener`

my $url_loaded = $mech->add_listener('Network.responseReceived', sub {
    my( $info ) = @_;
    warn "Loaded URL "
         . $info->{params}->{response}->{url}
         . ": "
         . $info->{params}->{response}->{status};
    warn "Resource timing: " . Dumper $info->{params}->{response}->{timing};
});

Returns a listener object. If that object gets discarded, the listener callback will be removed — so like, hold onto it, it's your emotional support listener. 🫶

Calling this method in void context croaks. Don't do that, bestie, it will simply not vibe.

To see the browser console live from your Perl script, use this:

my $console = $mech->add_listener('Runtime.consoleAPICalled', sub {
  warn join ", ",
      map { $_->{value} // $_->{description} }
      @{ $_[0]->{params}->{args} };
});

If you want to explicitly remove the listener, either set it to undef:

undef $console;

Alternatively, call

$console->unregister;

or call

$mech->remove_listener( $console );

🌈 `$mech->on_request_intercepted( $cb )`

$mech->on_request_intercepted( sub {
    my( $mech, $info ) = @_;
    warn $info->{request}->{url};
    $mech->continueInterceptedRequest_future(
        interceptionId => $info->{interceptionId}
    )
});

A callback for intercepted requests that match the patterns you set up via "setRequestInterception".

If you return a future from this callback, it will not be discarded — it gets kept in a safe place. Protected. Cherished. 🥺

🌈 `$mech->searchInResponseBody( $id, %options )`

my $request_id = ...;
my @matches = $mech->searchInResponseBody(
    requestId     => $request_id,
    query         => 'rumpelstiltskin',
    caseSensitive => JSON::true,
    isRegex       => JSON::false,
);
for( @matches ) {
    print $_->{lineNumber}, ":", $_->{lineContent}, "\n";
};

Returns the matches (if any) for a string or regular expression within a response. Rumpelstiltskin is right there, bestie, go find him. 🧵

🌈 `$mech->on_dialog( $cb )`

$mech->on_dialog( sub {
    my( $mech, $dialog ) = @_;
    warn $dialog->{message};
    $mech->handle_dialog( 1 ); # click "OK" / "yes" instead of "cancel"
});

A callback for Javascript dialogs — think alert(), prompt(), and all their dramatic little friends. 💬

🌈 `$mech->handle_dialog( $accept, $prompt = undef )`

$mech->on_dialog( sub {
    my( $mech, $dialog ) = @_;
    warn "[Javascript $dialog->{type}]: $dialog->{message}";
    $mech->handle_dialog( 1 ); # click "OK" / "yes" instead of "cancel"
});

Closes the current Javascript dialog. Bye girl, see you never. 👋

🌈 `$mech->js_console_entries()`

print $_->{type}, " ", $_->{message}, "\n"
    for $mech->js_console_entries();

An interface to the Javascript Error Console.

Returns the list of entries in the JEC. It's the receipts, all of them. 🧾

🌈 `$mech->js_errors()`

print "JS error: ", $_->{message}, "\n"
    for $mech->js_errors();

Returns the list of errors in the JEC. The spicy ones. 🔥

🌈 `$mech->clear_js_errors()`

$mech->clear_js_errors();

Clears all Javascript messages from the console. Fresh start, clean slate, new era. 🧼

🌈 `$mech->eval_in_page( $str, %options )` / `$mech->eval( $str, %options )`

my ($value, $type) = $mech->eval( '2+2' );

Evaluates the given Javascript fragment in the context of the web page. Returns a pair of value and Javascript type. Two-for-one, iconic. ✨

This allows access to variables and functions declared "globally" on the web page.

💖 `returnByValue`

If you want to create an object in Chrome and only want to keep a handle to that remote object, use JSON::false for the "returnByValue" option:

my ($dummyObj,$type) = $mech->eval(
    'new Object',
    returnByValue => JSON::false
);

This is also helpful if the object in Chrome cannot be serialized as JSON. For example, window is such an object. The return value is a hash, whose "objectId" is the most interesting part. 👀

This method is special to WWW::Mechanize::Chrome. 💅

🌈 `$mech->eval_in_chrome $code, @args`

$mech->eval_in_chrome(<<'JS', "Foobar/1.0");
    this.settings.userAgent= arguments[0]
JS

Evaluates Javascript code in the context of Chrome.

This allows you to modify properties of Chrome.

This is currently not implemented. 😭 I know. I know. It's giving "coming soon" energy.

🌈 `$mech->callFunctionOn( $function, @arguments )`

my ($value, $type) = $mech->callFunctionOn(
    'function(greeting) { window.alert(greeting)}',
    objectId => $someObjectId,
    arguments => [{ value => 'Hello World' }]
);

Runs the given function with the specified arguments. This is the only way to pass arguments to a function call without doing risky string interpolation — no messy, dangerous string-smooshing here, bestie. The Javascript "this" object will be set to the object referenced from the "objectId".

The "arguments" option expects an arrayref of hashrefs. Each hash describes one function argument.

The "objectId" parameter is optional. Leaving out the "objectId" parameter will create a dummy object on which the function then is called. Lil placeholder guy. 🫡

This method is special to WWW::Mechanize::Chrome. 💅

🌈 `->autoclose_tab`

Set the `autoclose_tab` option. 🚪

🌈 `->close`

$mech->close()

Tear down all connections and shut down Chrome. It's the "okay bye, going to bed" of methods. 😴

🌈 `$mech->list_tabs`

my @open_tabs = $mech->list_tabs()->get;
say $open_tabs[0]->{title};

Returns the open tabs as a list of hashrefs. All of them, your whole tab-hoarding situation. 🗂️

🌈 `$mech->highlight_node( @nodes )`

my @links = $mech->selector('a');
$mech->highlight_node(@links);
print $mech->content_as_png();

A convenience method that marks all nodes in the arguments with a red frame. 🔴

This is convenient if you need visual verification that you've got the right nodes. Like, it's giving "yes that one, the one with the red outline." Perfect for screenshots, perfect for proving you were right. 📸

`$mech->get( $url, %options )`

my $response = $mech->get( $url );

Okay so this one grabs the URL for you (yes, the one literally called URL, iconic naming, no notes 💅).

It hands back a HTTP::Response object so it plays nice with WWW::Mechanize's interface.

Heads up bestie — the HTTP::Response object you get back fills in the response body lazily, so you might have to chill for a sec before the body actually shows up from the result. This is a premature optimization, and later releases of WWW::Mechanize::Chrome are planned to fetch the response body immediately when accessing the response body. So yeah, temporary chaos ✨

Also note: Chrome does not support download of files through the API. Not a vibe, but it's the truth 🫠

Options

intrapage — Override the detection of whether to wait for a HTTP response or not. Setting this will never wait for an HTTP response.

`$mech->_collectEvents`

my $events = $mech->_collectEvents(
    sub { $_[0]->{method} eq 'Page.loadEventFired' }
);
my( $e,$r) = Future->wait_all( $events, $self->target->send_message(...));

Internal method (so like, devs only, but we support the devs 🫶) that creates a Future which waits for an event that Chrome sends out.

That subroutine is the predicate — it's what checks whether the current event is the one we've been waiting for.

The result is a Future that will return all captured events. Collect them all, Pokémon energy 💀

`$mech->get_local( $filename , %options )`

$mech->get_local('test.html');

Shorthand method that constructs the appropriate file:// URI and loads it into Chrome. Relative paths get interpreted as relative to $0 or the basedir option.

It accepts the same options as ->get().

This method is special to WWW::Mechanize::Chrome but could also exist in WWW::Mechanize through a plugin. Fancy ✨

Warning: Chrome does not handle local files well. Especially subframes do not get loaded properly. So like… proceed with caution, bestie 😭

`$mech->getRequestPostData`

if( $info->{params}->{response}->{requestHeaders}->{":method"} eq 'POST' ) {
    $req->{postBody} = $m->getRequestPostData( $id );
};

Retrieves the data sent with a POST request. Give it the $id, get the tea 🍵

`$mech->post( $url, %options )`

not implemented

$mech->post( 'http://example.com',
    params => { param => "Hello World" },
    headers => {
      "Content-Type" => 'application/x-www-form-urlencoded',
    },
    charset => 'utf-8',
);

Sends a POST request to $url.

A Content-Length header will be automatically calculated if it is not given. Chrome doing math so you don't have to 😌

The following options are recognized:

headers — a hash of HTTP headers to send. If not given, the content type will be generated automatically.
data — the raw data to send, if you've encoded it already.

`$mech->reload( %options )`

$mech->reload( ignoreCache => 1 )

Acts like the reload button in a browser: repeats the current request. The history (as per the back method) is not altered. Same page, fresh look 💅

Returns the HTTP::Response object from the reload, or undef if there's no current request.

`$mech->set_download_directory( $dir )`

my $downloads = tempdir();
$mech->set_download_directory( $downloads );

Enables automatic file downloads and sets the directory where the files will be downloaded to. Setting this to undef will disable downloads again. On and off, we love a toggle 🎀

The directory in $dir must be an absolute path, since Chrome does not know about the current directory of your Perl script. Fr fr, absolute only, no shortcuts ✋

my $cookies = $mech->cookie_jar

Returns all the Chrome cookies in a HTTP::Cookies::ChromeDevTools instance. Setting a cookie in there will also set the cookie in Chrome. Cookies everywhere, snack time 🍪

Note that the ->cookie_jar does not automatically refresh when a new page is loaded. To manually refresh the state of the cookie jar, use:

$mech->get('https://example.com/some_page');
$mech->cookie_jar->load;

`$mech->add_header( $name => $value, ... )`

$mech->add_header(
    'X-WWW-Mechanize-Chrome' => "I'm using it",
    Encoding => 'text/klingon',
);

This method sets up custom headers that will be sent with every HTTP(S) request that Chrome makes. Your headers, your rules 👑

Note that currently, we only support one value per header. One and done, bestie.

Chrome since version 63+ does not allow setting and sending the Referer header anymore. The bug report is at https://bugs.chromium.org/p/chromium/issues/detail?id=849972. Blame Chrome, not us 💀

`$mech->delete_header( $name , $name2... )`

$mech->delete_header( 'User-Agent' );

Removes HTTP headers from the agent's list of special headers. Note that Chrome may still send a header with its default value. So like, you deleted it but Chrome said "actually no" 🙈

`$mech->reset_headers`

$mech->reset_headers();

Removes all custom headers and makes Chrome send its defaults again. Clean slate, fresh start, main character reset ✨

`$mech->block_urls()`

$mech->block_urls( '//facebook.com/js/conversions/tracking.js' );

Sets the list of blocked URLs. These URLs will not be retrieved by Chrome when loading a page. This is useful to eliminate tracking images or to test resilience in face of bad network conditions. Blocked and unbothered 🚫

`$mech->res()` / `$mech->response(%options)`

my $response = $mech->response(headers => 0);

Returns the current response as a HTTP::Response object.

`$mech->success()`

$mech->get('https://google.com');
print "Yay"
    if $mech->success();

Returns a boolean telling whether the last request was successful. If there hasn't been an operation yet, returns false. No operation = no celebration, sorry 🥲

This is a convenience function that wraps $mech->res->is_success.

`$mech->status()`

$mech->get('https://google.com');
print $mech->status();
# 200

Returns the HTTP status code of the response. This is a 3-digit number like 200 for OK, 404 for not found, and so on. The classic numbers ✨

`$mech->back()`

$mech->back();

Goes one page back in the page history. Rewind time, lowkey time travel ⏪

Returns the (new) response.

`$mech->forward()`

$mech->forward();

Goes one page forward in the page history. Okay now go back forward ⏩

Returns the (new) response.

`$mech->stop()`

$mech->stop();

Stops all loading in Chrome, as if you pressed ESC. Emergency brake energy 🛑

This function is mostly of use in callbacks or in a timer callback from your event loop.

`$mech->uri()` / `$mech->uri_future()`

print "We are at " . $mech->uri;
print "We are at " . $mech->uri_future->get;

Returns the current document URI. Where are we? Now you know 📍

`$mech->infinite_scroll( [$wait_time_in_seconds] )`

$new_content_found = $mech->infinite_scroll(3);

Loads content into pages that have "infinite scroll" capabilities by scrolling to the bottom of the web page and waiting up to the number of seconds, as set by the optional $wait_time_in_seconds argument, for the browser to load more content. The default is to wait up to 20 seconds. For reasonably fast sites, the wait time can be set much lower. Doomscrolling but make it automated 🌀

The method returns a boolean true if new content is loaded, false otherwise. You can scroll to the end (if there is one) of an infinitely scrolling page like so:

while( $mech->infinite_scroll ) {
    # Tests for exiting the loop earlier
    last if $count++ >= 10;
}

🌸 CONTENT METHODS 🌸

`$mech->document_future()` / `$mech->document()`

print $self->document->{nodeId};

Returns the document node.

This is WWW::Mechanize::Chrome specific. Special girl behavior 💅

`$mech->content( %options )`

print $mech->content;
print $mech->content( format => 'html' ); # default
print $mech->content( format => 'text' ); # identical to ->text
print $mech->content( format => 'mhtml' ); # identical to ->captureSnapshot

This always returns the content as a Unicode string. It tries to decode the raw content according to its input encoding. This currently only works for HTML pages, not for images etc. HTML only, bestie, sorry to the images 😭

Recognized options:

format — the stuff to return

The allowed values are html and text. The default is html.

`$mech->text()`

print $mech->text();

Returns the text of the current HTML content. If the content isn't HTML, $mech will die. Dramatic but fair 💀

`$mech->captureSnapshot_future()` / `$mech->captureSnapshot()`

print $mech->captureSnapshot( format => 'mhtml' )->{data};

Returns the current page as MHTML.

This is WWW::Mechanize::Chrome specific. Snapshot, but make it ✨aesthetic✨

`$mech->content_encoding()`

print "The content is encoded as ", $mech->content_encoding;

Returns the encoding that the content is in. This can be used to convert the content from UTF-8 back to its native encoding.

`$mech->update_html( $html )`

$mech->update_html($html);

Writes $html into the current document. This is mostly implemented as a convenience method for HTML::Display::MozRepl.

The value passed in as $html will be stringified.

`$mech->base()`

print $mech->base;

Returns the URL base for the current page.

The base is either specified through a base tag or is the current URL. Either way, we got the base 🏠

This method is specific to WWW::Mechanize::Chrome.

`$mech->content_type()` / `$mech->ct()`

print $mech->content_type;

Returns the content type of the currently loaded document.

`$mech->is_html()`

print $mech->is_html();

Returns true/false on whether our content is HTML, according to the HTTP headers.

`$mech->title()`

print "We are on page " . $mech->title;

Returns the current document title. The tab name, basically 👑

`$mech->links()`

print $_->text . " -> " . $_->url . "\n"
    for $mech->links;

Gives you every single link in the document, all wrapped up as WWW::Mechanize::Link objects. So cute, so tidy. 🎀

Right now it takes no parameters at all. Like, zero. If you're craving more control over which links you get, go hit up ->xpath or ->selector instead, iykyk. 💅

`$mech->selector( $css_selector, %options )`

my @text = $mech->selector('p.content');

Returns all nodes that match the CSS selector you hand it. And if $css_selector is an array reference? It returns everything matched by any of the selectors in that array. Iconic behaviour honestly. 🌈

It takes the exact same options that ->xpath does, no cap.

Heads up: this method is implemented via WWW::Mechanize::Plugin::Selector. 🧚

`$mech->find_link_dom( %options )`

print $_->{innerHTML} . "\n"
    for $mech->find_link_dom( text_contains => 'CPAN' );

A link-finding method, kinda like WWW::Mechanize's ->find_links, but it hands you back DOM objects straight from Chrome instead of WWW::Mechanize::Link objects. Different flavor, same energy. 🦋

⚠️ Real talk: Chrome might have reordered the links or frame links in the document, so the absolute numbers you pass via n might not match up between WWW::Mechanize and WWW::Mechanize::Chrome. Just so you're not blindsided, bestie. 😭

The supported options are:

text, text_contains, text_regex — match the text of the link as a complete string, a substring, or a regular expression.
- Matching as a complete string or substring is a bit faster, because it's done in the XPath engine of Chrome. speed queen behaviour. ⚡
id, id_contains, id_regex — matches the id attribute of the link completely or as part
name, name_contains, name_regex — matches the name attribute of the link
url, url_regex — matches the URL attribute of the link (href, src or content).
class — the class attribute of the link
n — the (1-based) index. Defaults to returning the first link.
single — if true, ensure that only one element is found. Otherwise croak or carp, depending on the autodie parameter.
one — if true, ensure that at least one element is found. Otherwise croak or carp, depending on the autodie parameter.

The method croaks if no link is found. And if the single option is true, it also croaks when more than one link is found. so like, don't be greedy. 💀

`$mech->find_link( %options )`

print $_->text . "\n"
    for $mech->find_link( text_contains => 'CPAN' );

A method that's quite similar to WWW::Mechanize's own. All the options are documented up in ->find_link_dom, go check that out. 📖

Returns a WWW::Mechanize::Link object. ✨

By default it does not look through child frames. Stay in your lane, frames. 🚧

`$mech->find_all_links( %options )`

print $_->text . "\n"
    for $mech->find_all_links( text_regex => qr/google/i );

Finds all the links in the document. Options? Documented in ->find_link_dom, as always. 🎀

Returns them as a list or an array reference, depending on context. Versatile queen. 👑

Defaults to not looking through child frames.

`$mech->find_all_links_dom %options`

print $_->{innerHTML} . "\n"
    for $mech->find_all_links_dom( text_regex => qr/google/i );

Finds all matching linky DOM nodes in the document. The options are documented in ->find_link_dom. 🌸

Returns them as a list or an array reference, depending on context.

Defaults to not looking through child frames. 🚫

`$mech->follow_link( $link )`

`$mech->follow_link( %options )`

$mech->follow_link( xpath => '//a[text() = "Click here!"]' );

Follows the link you give it. Takes the same parameters that find_link_dom uses, so you already know the drill. 🫶

Note that ->follow_link will only try to follow link-like things like A tags. It's not gonna chase down random elements for you, bestie. 🦋

`$mech->xpath( $query, %options )`

my $link = $mech->xpath('//a[id="clickme"]', one => 1);
# croaks if there is no link or more than one link found

my @para = $mech->xpath('//p');
# Collects all paragraphs

my @para_text = $mech->xpath('//p/text()', type => $mech->xpathResult('STRING_TYPE'));
# Collects all paragraphs as text

Runs an XPath query in Chrome against the current document. This is the main character of extraction methods, fr fr. 👑

If you need more info about the results you got back, use the ->xpathEx() function. 🔍

🫠 Note that Chrome sometimes returns a node with node id 0. That node then cannot be found again using the Chrome API. This is bad luck and results in a warning. Not our fault, just Chrome being Chrome.

The options allow the following keys:

document — document in which the query is to be executed. Use this to search a node within a specific subframe of $mech->document.
frames — if true, search all documents in all frames and iframes. This may or may not conflict with node. This will default to the frames setting of the WWW::Mechanize::Chrome object.
node — node relative to which the query is to be executed. Note that you will have to use a relative XPath expression as well. Use

.//foo

instead of

//foo

Querying relative to a node only works for restricting to children of the node, not for anything else. This is because we need to do the ancestor filtering ourselves instead of having a Chrome API for it. DIY energy, we love to see it. 💅

single — if true, ensure that only one element is found. Otherwise croak or carp, depending on the autodie parameter.
one — if true, ensure that at least one element is found. Otherwise croak or carp, depending on the autodie parameter.
maybe — if true, ensure that at most one element is found. Otherwise croak or carp, depending on the autodie parameter.
all — if true, return all elements found. This is the default. You can use this option if you want to use ->xpath in scalar context to count the number of matched elements, as it will otherwise emit a warning for each usage in scalar context without any of the above restricting options. 🧮
any — no error is raised, no matter if an item is found or not. chill vibes only. 😌

Returns the matched results as WWW::Mechanize::Chrome::Node objects. 🌈

You can pass in a list of queries as an array reference for the first parameter. The result will then be the list of all elements matching any of the queries. obsessed. ✨

This is a method that is not implemented in WWW::Mechanize. In the long run, this should go into a general plugin for WWW::Mechanize. 📝

`$mech->by_id( $id, %options )`

my @text = $mech->by_id('_foo:bar');

Returns all nodes matching the ids you give it. If $id is an array reference, it returns all nodes matched by any of the ids in that array. 🎀

This method is equivalent to calling ->xpath:

$self->xpath(qq{//*[\@id="$_"]}, %options)

It's convenient when your element ids get mistaken for CSS selectors. We've all been there. 🙈

`$mech->click( $name [,$x ,$y] )`

# If the element is within a <form> element
$mech->click( 'go' );

# If the element is anywhere on the page
$mech->click({ xpath => '//button[@name="go"]' });

Has the effect of clicking a button (or other element) on the current form. The first argument is the name of the button to be clicked. The second and third arguments (optional) let you specify the (x,y) coordinates of the click. pinpoint accuracy bestie. 🎯

If there's only one button on the form, $mech->click() with no arguments simply clicks that one button. easy. 👑

If you pass in a hash reference instead of a name, the following keys are recognized:

text — Find the element to click by its contained text
selector — Find the element to click by the CSS selector
xpath — Find the element to click by the XPath query
dom — Click on the passed DOM element
- You can use this to click on arbitrary page elements. There is no convenient way to pass x/y co-ordinates when using the dom option. sorry bout it. 😭
id — Click on the element with the given id
- This is useful if your document ids contain characters that do look like CSS selectors. It is equivalent to

xpath => qq{//*[\@id="$id"]}

intrapage — Override the detection of whether to wait for a HTTP response or not. Setting this will never wait for an HTTP response. ⚡

Returns a HTTP::Response object. 📬

As a deviation from the WWW::Mechanize API, you can also pass a hash reference as the first parameter. In it, you can specify the parameters to search much like for the find_link calls. 🦋

`$mech->click_button( ... )`

$mech->click_button( name => 'go' );
$mech->click_button( input => $mybutton );

Has the effect of clicking a button on the current form by specifying its name, value, or index. Its arguments are a list of key/value pairs. Only one of name, number, input or value must be specified in the keys. pick a lane. 💅

name — name of the button
value — value of the button
input — DOM node
id — id of the button
number — number of the button

If you find yourself wanting to specify a button through its selector or xpath, consider using ->click instead. just saying. 🎀

💖 FORM METHODS 💖

ok bestie this whole section is about forms, like the thing where you type your email and hit the button. it's a lot but we got this fr fr 🫶

💅 `$mech->current_form()`

print $mech->current_form->{name};

Returns the current form. that's it, that's the vibe ✨

ok but heads up, this method is incompatible with WWW::Mechanize 😭 it hands you back the DOM <form> object, not an HTML::Form instance. so if you came from vanilla Mechanize expecting the old thing, surprise, it's giving different energy 💀

also the current form gets reset by WWW::Mechanize::Chrome whenever you call ->get() or ->get_local(), and also on calls to ->submit() and ->submit_with_fields. so don't hold onto it like it's forever, it's not 🌸

🎀 `$mech->dump_forms( [$fh] )`

open my $fh, '>', 'form-log.txt'
    or die "Couldn't open logfile 'form-log.txt': $!";
$mech->dump_forms( $fh );

Prints a dump of all the forms on the current page to the filehandle $fh. if you don't pass $fh, or you pass undef, it just dumps to STDOUT instead, easy 🦋

⭐ `$mech->form_name( $name [, %options] )`

$mech->form_name( 'search' );

Selects the current form by its name, slay. the options you can pass are identical to the ones $mech->xpath accepts 👑

🌈 `$mech->form_id( $id [, %options] )`

$mech->form_id( 'login' );

Selects the current form by its id attribute. same deal, options are identical to what $mech->xpath takes 💖

and lowkey this is literally equivalent to calling:

$mech->by_id($id,single => 1,%options)

no cap, same thing 🫶

🧚 `$mech->form_number( $number [, %options] )`

$mech->form_number( 2 );

Selects the numberth form, like the 2nd one, the 3rd one, whichever. options are, you guessed it, identical to those $mech->xpath accepts ✨

🍓 `$mech->form_with_fields( [$options], @fields )`

$mech->form_with_fields(
    'user', 'password'
);

Finds the form that has the listed fields in it, icon behavior fr 💅

if the first argument is a hash reference, it gets taken as options to pass to ->xpath.

💜 `$mech->forms( %options )`

my @forms = $mech->forms();

When you call this in list context, it gives you a list of all the forms found in the last fetched page. When you call it in scalar context, it gives you a reference to an array holding those forms instead. main character duality tbh ✨

the options are identical to the ones $mech->selector accepts.

and the returned elements? those are the DOM <form> elements, periodt 💖

🔥 `$mech->field( $selector, $value, [, $index, \@pre_events [,\@post_events]] )`

$mech->field( user => 'joe' );
$mech->field( not_empty => '', 0, [], [] ); # bypass JS validation
$mech->field( date => '2020-04-01', 2 );    # set second field named "date"

Sets the field named in $selector to the given value, and then returns that value. cute 🎀

it understands very basic CSS selectors in the $selector value, same vibe as the HTML::Form find_input() method. so:

a selector prefixed with # has to match the id attribute of the input
a selector prefixed with . matches the class attribute
a selector prefixed with ^, or with no prefix at all, matches the name attribute

by passing that array reference @pre_events, you tell it which Javascript events you want fired before the value gets set. and @post_events holds the events you want fired after the value is set 🔥

by default, the events you set in the constructor for pre_events and post_events are the ones that get triggered 💅

🌸 `$mech->sendkeys( %options )`

$mech->sendkeys( string => "Hello World" );

Sends a series of keystrokes, like you're typing but make it robot 💖 the keystrokes can be either a plain string, or a reference to an array that holds the detailed data as hashes.

string — the string to send as keystrokes
keys — reference of the array to send as keystrokes
delay — delay in ms to sleep between keys

🦋 `$mech->upload( $selector, $value )`

$mech->upload( user_picture => 'C:/Users/Joe/face.png' );

Sets the file upload field named in $selector to the given file. important: the filename must be an absolute path and filename in the local filesystem — no relative paths bestie, it will not play 🙈

and yeah, this method understands very basic CSS selectors in the $selector value, just like the ->field method does ✨

👑 `$mech->value( $selector_or_element, [ $index | %options] )`

print $mech->value( 'user' );

Returns the value of the field given by $selector_or_name, or of the DOM element you passed in. either way, you get the value 💅

if you've got multiple fields sharing the same name, you can hand it an index to point directly at the one you want:

print $mech->value( 'date', 2 ); # get the second field named "date"

heads up: the legacy form of $mech->value( name => value ); is not supported anymore. rip to that era 💀

for fields that can hold multiple values, like a select field, this method is context sensitive — it gives you the first selected value in scalar context, and all the values in list context. she adapts 🧚

and note: this method does not support file uploads. for that, go see the ->upload method instead 🌸

💖 `$mech->get_set_value( %options )`

Gives you fine-grained access to getting/setting a value through a different API. the supported keys are:

name
value
pre
post

...plus every single key that $mech->xpath supports. so it's stacked fr fr ✨

🎀 `$mech->set_field( %options )`

$mech->set_field(
    field => $field_node,
    value => 'foo',
);

Low level value setting method. use this one when you've got an input element that lives outside of a <form> tag, iykyk 🫶

⭐ `$mech->select( $name, $value )`

⭐ `$mech->select( $name, \@values )`

$mech->select( 'items', 'banana' );

Given the name of a select field, sets its value to the value you specified. slay 🍓

if the field is not <select multiple> and $value is an array, then only the first value will actually get set. if you pass $value as a hash with an n key, it selects an item by number — like {n => 3} or {n => [2,4]}. and the numbering starts at 1, not 0, okay? don't come at me 😭 all of this applies to the current form.

now if you do have a <select multiple> field and you pass a single $value, then $value just gets added to the list of selected fields, without clearing the others. but if you pass an array reference, then all the previously selected values get cleared first. she wipes the slate 🔥

Returns true on successfully setting the value. on failure, returns false and calls $self>warn() with an error message 💅

🌈 `$mech->tick( $name, $value [, $set ] )`

$mech->tick("confirmation_box", 'yes');

"Ticks" the first checkbox that has both the name and the value associated with it on the current form. dies if there's no named check box for that value, so don't test her 💀

passing in a false value as the third optional argument will cause the checkbox to be unticked instead.

the (un)ticking itself is done by sending a click event to it, but only if it's needed. and if $value is undef, then the first checkbox matching $name gets (un)ticked 🌸

if $name is a reference to a hash, that hash gets used as the options to ->find_link_dom to find the element. fancy ✨

🧚 `$mech->untick( $name, $value )`

$mech->untick('spam_confirm','yes',undef)

Causes the checkbox to be unticked. it's just shorthand for:

$mech->tick($name,$value,undef)

periodt 💅

💜 `$mech->submit( $form )`

$mech->submit;

Submits the form. but okay, note that this does not fire the onClick event, and so it also doesn't fire any eventual Javascript handlers 😭 maybe what you actually want is $mech->click instead, just saying 👀

the default is to submit the current form, as returned by $mech->current_form.

🔥 `$mech->submit_form( %options )`

$mech->submit_form(
    with_fields => {
        user => 'me',
        pass => 'secret',
    }
);

This method lets you select a form from the previously fetched page, fill in its fields, and submit it. it's the combo move — it combines the form_number/form_name, ->set_fields and ->click methods into one higher level call 🎀

its arguments are a list of key/value pairs, and literally all of them are optional. iconic.

form => $mech->current_form() — Specifies the form to be filled and submitted. Defaults to the current form.
fields => \%fields — Specifies the fields to be filled in the current form.
with_fields => \%fields — Probably all you need for the common case. It combines a smart form selector and data setting in one single operation. It selects the first form that contains all the fields mentioned in \%fields. This is nice because you don't need to know the name or number of the form to do this. (calls $mech->form_with_fields() and $mech->set_fields()).

if you choose this one, the form_number, form_name, form_id and fields options will be ignored. she takes over 💅

🌸 `$mech->set_fields( $name => $value, ... )`

$mech->set_fields(
    user => 'me',
    pass => 'secret',
);

This method sets multiple fields of the current form at once. it takes a list of field name and value pairs. if there's more than one field with the same name, the first one found gets set. but if you want to pick which of the duplicate fields gets set, use a value that's an anonymous array — with the field value and its number as the two elements:

$mech->set_fields(
    user => 'me',
    pass => 'secret',
    pass => [ 'secret', 2 ], # repeated password field
);

and that's how you handle the duplicate password field situation, you're welcome bestie 🫶✨

✨ CONTENT MONITORING METHODS ✨

💅 `$mech->is_visible( $element )`

💅 `$mech->is_visible( %options )`

if ($mech->is_visible( selector => '#login' )) {
    print "You can log in now.";
};

okay bestie so this one tells you if the element is actually visible — meaning it's a member of the DOM, and neither it nor any of its ancestors have a CSS visibility attribute of hidden or a display attribute of none. Basically if it's hiding in a display:none closet somewhere up the family tree, it's a no 🫶

You can hand it either a DOM element directly, or a lil set of key/value pairs so it can go hunt the element down for you in the document.

xpath — the XPath query, go fetch 🔍
selector — the CSS selector
dom — a DOM node

Any remaining options get passed straight through to either the $mech->xpath or $mech->selector method. slay.

⏳ `$mech->wait_until_invisible( $element )`

⏳ `$mech->wait_until_invisible( %options )`

$mech->wait_until_invisible( $please_wait );

Waits around (patiently, like a good bestie) until an element is not visible anymore.

It takes the same options as ->is_visible in $mech->is_visible.

Plus these extras, periodt:

timeout — the timeout after which the function will croak. To catch that condition and handle it in your calling program, use an eval block. A timeout of 0 means to never time out.

See also max_wait if you want to wait a limited time for an element to appear. 👀

max_wait — the maximum time to wait until the function will return. A max_wait of 0 means to never time out. If the element is still visible, the function will return a false value.
sleep — the interval in seconds used to sleep. Subsecond intervals are possible. 😴

ngl there's a little catch: when you pass in a selector, that selector is requeried on every poll instance. So this query will work as expected:

xpath => '//*[contains(text(),"stand by")]'

Which also means: if your selector query relies on finding a changing text, you need to pass the node explicitly instead of passing the selector. no cap 🫠

⏳ `$mech->wait_until_visible( %options )`

$mech->wait_until_visible( selector => 'a.download' );

Waits until a query returns a visible element. the way it just… waits 💖

Takes the same options as ->is_visible in $mech->is_visible.

Plus these extras:

timeout — the timeout after which the function will croak. To catch the condition and handle it in your calling program, use an eval block. A timeout of 0 means to never time out.
sleep — the interval in seconds used to sleep. Subsecond intervals are possible.

Same lil note as before: when passing in a selector, that selector is requeried on every poll instance. So this query will work as expected:

xpath => '//*[contains(text(),"click here for download")]'

🎨 CONTENT RENDERING METHODS 🎨

📸 `$mech->content_as_png()`

my $png_data = $mech->content_as_png();

# Create scaled-down 480px wide preview
my $png_data = $mech->content_as_png(undef, { width => 480 });

Returns the given tab — or the current page — rendered as a PNG image. iconic behavior honestly 🦋

All parameters are optional. very chill of it.

This method is specific to WWW::Mechanize::Chrome.

🗂️ `$mech->saveResources_future`

my $file_map = $mech->saveResources_future(
    target_file => 'this_page.html',
    target_dir  => 'this_page_files/',
    wanted      => sub { $_[0]->{url} =~ m!^https?:!i },
)->get();

Rough prototype of the "Save Complete Page" feature. like it's giving early-days energy but it works 💅

🪟 `$mech->viewport_size`

print Dumper $mech->viewport_size;
$mech->viewport_size({ width => 1388, height => 792 });

Returns (or sets) the new size of the viewport — aka the "window".

The recognized keys are:

width
height
deviceScaleFactor
mobile
screenWidth
screenHeight
positionX
positionY

🖼️ `$mech->element_as_png( $element )`

my $shiny = $mech->selector('#shiny', single => 1);
my $i_want_this = $mech->element_as_png($shiny);

Returns PNG image data for a single element. just one lil guy, immortalized 🎀

🎬 `$mech->render_element( %options )`

my $shiny = $mech->selector('#shiny', single => 1);
my $i_want_this= $mech->render_element(
    element => $shiny,
    format => 'png',
);

Returns the data for a single element, or writes it to a file. It accepts all options of ->render_content.

⚠️ heads up bestie: while the image will have the node in the upper left corner, the width and height of the resulting image will still be the size of the browser window. Cut the image using element_coordinates if you need exactly the element. iykyk 😭

📐 `$mech->element_coordinates( $element )`

my $shiny = $mech->selector('#shiny', single => 1);
my ($pos) = $mech->element_coordinates($shiny);
print $pos->{left},',', $pos->{top};

Returns the page-coordinates of the $element in pixels as a hash with four entries: left, top, width and height.

This function might get moved into another module more geared towards rendering HTML. lowkey in flux, we love that for it 🌸

🧾 `$mech->render_content(%options)`

my $pdf_data = $mech->render_content( format => 'pdf' );

Returns the current page rendered as PDF or PNG as a bytestring.

⚠️ Note that the PDF format will only be successful with headless Chrome. At least on Windows, when launching Chrome with a UI, printing to PDF will be unavailable. 💀

This method is specific to WWW::Mechanize::Chrome.

📄 `$mech->content_as_pdf(%options)`

my $pdf_data = $mech->content_as_pdf();

my $pdf_data = $mech->content_as_pdf( format => 'A4' );

my $pdf_data = $mech->content_as_pdf( paperWidth => 8, paperHeight => 11 );

Returns the current page rendered in PDF format as a bytestring. The page format can be specified through the format option.

⚠️ Note that this method will only be successful with headless Chrome. At least on Windows, when launching Chrome with a UI, printing to PDF will be unavailable. See the "html-to-pdf.pl" script in the "examples/" directory of this distribution. 🙈

This method is specific to WWW::Mechanize::Chrome.

🔧 INTERNAL METHODS 🔧

These are methods that are available but exist mostly as internal helper methods. Use of these is discouraged. like… they're there, but they're not for you bestie, stay back 🫶

🧩 `$mech->element_query( \@elements, \%attributes )`

my $query = $mech->element_query(['input', 'select', 'textarea'],
                           { name => 'foo' });

Returns the XPath query that searches for all elements with tagNames in @elements having the attributes %attributes. The @elements will form an "or" condition, while the attributes will form an "and" condition. logic slay ✨

🐛 DEBUGGING METHODS 🐛

This module can collect the screencasts that Chrome can produce. The screencasts are sent to your callback, which either feeds them to "ffmpeg" to create a video out of them, or dumps them to disk as sequential images. it's giving director's cut 🎥

sub saveFrame {
    my( $mech, $framePNG ) = @_;
    print $framePNG->{data};

}

$mech->setScreenFrameCallback( \&saveFrame );
... do stuff ...
$mech->setScreenFrameCallback( undef ); # stop recording

If you want a premade screencast receiver for debugging headless Chrome sessions, see Mojolicious::Plugin::PNGCast. so convenient fr fr

😴 `$mech->sleep`

$mech->sleep( 2 ); # wait for things to settle down

Suspends the progress of the program while still handling messages from Chrome.

The main use of this method is to give Chrome enough time to send all its screencast frames and to catch up before shutting down the connection. a lil breather before the goodbye 🦋

💔 INCOMPATIBILITIES WITH WWW::Mechanize 💔

As this module is in a very early stage of development, there are many incompatibilities. The main thing is that only the most needed WWW::Mechanize methods have been implemented by me so far. growth era, we're getting there 🌱