<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">NAME
    WWW::Mechanize::Firefox - use Firefox as if it were WWW::Mechanize

SYNOPSIS
      use WWW::Mechanize::Firefox;
      my $mech = WWW::Mechanize::Firefox-&gt;new();
      $mech-&gt;get('http://google.com');

      $mech-&gt;eval_in_page('alert("Hello Firefox")');
      my $png = $mech-&gt;content_as_png();

    This module will let you automate Firefox through the Mozrepl plugin.
    You need to have installed that plugin in your Firefox.

    For more examples see WWW::Mechanize::Firefox::Examples.

METHODS
  `$mech-&gt;new( %args )'
      use WWW::Mechanize::Firefox;
      my $mech = WWW::Mechanize::Firefox-&gt;new();

    Creates a new instance and connects it to Firefox.

    Note that Firefox must have the `mozrepl' extension installed and
    enabled.

    The following options are recognized:

    *   `tab' - regex for the title of the tab to reuse. If no matching tab
        is found, the constructor dies.

        If you pass in the string `current', the currently active tab will
        be used instead.

    *   `create' - will create a new tab if no existing tab matching the
        criteria given in `tab' can be found.

    *   `activate' - make the tab the active tab

    *   `launch' - name of the program to launch if we can't connect to it
        on the first try.

    *   `frames' - an array reference of ids of subframes to include when
        searching for elements on a page.

        If you want to always search through all frames, just pass `1'. This
        is the default.

        To prevent searching through frames, pass

                  frames =&gt; 0

        To whitelist frames to be searched, pass the list of frame
        selectors:

                  frames =&gt; ['#content_frame']

    *   `autodie' - whether web failures converted are fatal Perl errors.
        See the `autodie' accessor. True by default to make error checking
        easier.

        To make errors non-fatal, pass

            autodie =&gt; 0

        in the constructor.

    *   `log' - array reference to log levels, passed through to
        MozRepl::RemoteObject

    *   `bufsize' - Net::Telnet buffer size, if the default of 1MB is not
        enough

    *   `events' - the set of default Javascript events to listen for while
        waiting for a reply

        The default set is

          DOMFrameContentLoaded
          DOMContentLoaded
          pageshow
          error
          abort
          stop

    *   `app' - a premade Firefox::Application

    *   `repl' - a premade MozRepl::RemoteObject instance or a connection
        string suitable for initializing one

    *   `use_queue' - whether to use the command queueing of
        MozRepl::RemoteObject. Default is 1.

    *   `pre_events' - the events that are sent to an input field before its
        value is changed. By default this is `[focus]'.

    *   `post_events' - the events that are sent to an input field after its
        value is changed. By default this is `[blur, change]'.

JAVASCRIPT METHODS
  `$mech-&gt;allow( %options )'
    Enables or disables browser features for the current tab. The following
    options are recognized:

    *   `plugins' - Whether to allow plugin execution.

    *   `javascript' - Whether to allow Javascript execution.

    *   `metaredirects' - Attribute stating if refresh based redirects can
        be allowed.

    *   `frames', `subframes' - Attribute stating if it should allow
        subframes (framesets/iframes) or not.

    *   `images' - Attribute stating whether or not images should be loaded.

    Options not listed remain unchanged.

    Disable Javascript
      $mech-&gt;allow( javascript =&gt; 0 );

  `$mech-&gt;js_errors()'
      print $_-&gt;{message}
          for $mech-&gt;js_errors();

    An interface to the Javascript Error Console

    Returns the list of errors in the JEC

    Maybe this should be called `js_messages' or `js_console_messages'
    instead.

  `$mech-&gt;clear_js_errors'
        $mech-&gt;clear_js_errors();

    Clears all Javascript messages from the console

  `$mech-&gt;eval_in_page( $str [, $env [, $document]] )'
  `$mech-&gt;eval( $str [, $env [, $document]] )'
      my ($value, $type) = $mech-&gt;eval( '2+2' );

    Evaluates the given Javascript fragment in the context of the web page.
    Returns a pair of value and Javascript type.

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

    The returned result needs to be treated with extreme care because it
    might lead to Javascript execution in the context of your application
    instead of the context of the webpage. This should be evident for
    functions and complex data structures like objects. When working with
    results from untrusted sources, you can only safely use simple types
    like `string'.

    If you want to modify the environment the code is run under, pass in a
    hash reference as the second parameter. All keys will be inserted into
    the `this' object as well as `this.window'. Also, complex data
    structures are only supported if they contain no objects. If you need
    finer control, you'll have to write the Javascript yourself.

    This method is special to WWW::Mechanize::Firefox.

    Also, using this method opens a potential security risk as the returned
    values can be objects and using these objects can execute malicious code
    in the context of the Firefox application.

  `$mech-&gt;unsafe_page_property_access( ELEMENT )'
    Allows you unsafe access to properties of the current page. Using such
    properties is an incredibly bad idea.

    This is why the function `die's. If you really want to use this
    function, edit the source code.

UI METHODS
    See also Firefox::Application for how to add more than one tab and how
    to manipulate windows and tabs.

  `$mech-&gt;application()'
        my $ff = $mech-&gt;application();

    Returns the Firefox::Application object for manipulating more parts of
    the Firefox UI and application.

  `$mech-&gt;tab'
    Gets the object that represents the Firefox tab used by
    WWW::Mechanize::Firefox.

    This method is special to WWW::Mechanize::Firefox.

  `$mech-&gt;autodie( [$state] )'
      $mech-&gt;autodie(0);

    Accessor to get/set whether warnings become fatal.

  `$mech-&gt;progress_listener( $source, %callbacks )'
        my $eventlistener = progress_listener(
            $browser,
            onLocationChange =&gt; \&amp;onLocationChange,
        );

    Sets up the callbacks for the `nsIWebProgressListener' interface to be
    the Perl subroutines you pass in.

    Returns a handle. Once the handle gets released, all callbacks will get
    stopped. Also, all Perl callbacks will get deregistered from the
    Javascript bridge, so make sure not to use the same callback in
    different progress listeners at the same time.

  `$mech-&gt;repl'
      my ($value,$type) = $mech-&gt;repl-&gt;expr('2+2');

    Gets the MozRepl::RemoteObject instance that is used.

    This method is special to WWW::Mechanize::Firefox.

  `$mech-&gt;events'
      $mech-&gt;events( ['load'] );

    Sets or gets the set of Javascript events that WWW::Mechanize::Firefox
    will wait for after requesting a new page. Returns an array reference.

    This method is special to WWW::Mechanize::Firefox.

  `$mech-&gt;on_event'
      $mech-&gt;on_event(1); # prints every page load event

      # or give it a callback
      $mech-&gt;on_event(sub { warn "Page loaded with $ev-&gt;{name} event" });

    Gets/sets the notification handler for the Javascript event that
    finished a page load. Set it to `1' to output via `warn', or a code
    reference to call it with the event.

    This method is special to WWW::Mechanize::Firefox.

  `$mech-&gt;cookies'
      my $cookie_jar = $mech-&gt;cookies();

    Returns a HTTP::Cookies object that was initialized from the live
    Firefox instance.

    Note: `-&gt;set_cookie' is not yet implemented, as is saving the cookie
    jar.

  `$mech-&gt;highlight_node( @nodes )'
        my @links = $mech-&gt;selector('a');
        $mech-&gt;highlight_node(@links);

    Convenience method that marks all nodes in the arguments with

      background: red;
      border: solid black 1px;
      display: block; /* if the element was display: none before */

    This is convenient if you need visual verification that you've got the
    right nodes.

    There currently is no way to restore the nodes to their original visual
    state except reloading the page.

NAVIGATION METHODS
  `$mech-&gt;get( $url, %options )'
      $mech-&gt;get( $url, ':content_file' =&gt; $tempfile );

    Retrieves the URL `URL' into the tab.

    It returns a faked HTTP::Response object for interface compatibility
    with WWW::Mechanize.

    Recognized options:

    *   `:content_file' - filename to store the data in

    *   `no_cache' - if true, bypass the browser cache

    *   `synchronize' - wait until all elements have loaded

        The default is to wait until all elements have loaded. You can
        switch this off by passing

            synchronize =&gt; 0

        for example if you want to manually poll for an element that appears
        fairly early during the load of a complex page.

  `$mech-&gt;get_local( $filename , %options )'
      $mech-&gt;get_local('test.html');

    Shorthand method to construct the appropriate `file://' URI and load it
    into Firefox. Relative paths will be interpreted as relative to `$0'.

    This method accepts the same options as `-&gt;get()'.

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

  `$mech-&gt;synchronize( $event, $callback )'
    Wraps a synchronization semaphore around the callback and waits until
    the event `$event' fires on the browser. If you want to wait for one of
    multiple events to occur, pass an array reference as the first
    parameter.

    Usually, you want to use it like this:

      my $l = $mech-&gt;xpath('//a[@onclick]', single =&gt; 1);
      $mech-&gt;synchronize('DOMFrameContentLoaded', sub {
          $l-&gt;__click()
      });

    It is necessary to synchronize with the browser whenever a click
    performs an action that takes longer and fires an event on the browser
    object.

    The `DOMFrameContentLoaded' event is fired by Firefox when the whole DOM
    and all `iframe's have been loaded. If your document doesn't have
    frames, use the `DOMContentLoaded' event instead.

    If you leave out `$event', the value of `-&gt;events()' will be used
    instead.

  `$mech-&gt;res' / `$mech-&gt;response'
        my $response = $mech-&gt;response();

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

  `$mech-&gt;success'
        $mech-&gt;get('http://google.com');
        print "Yay"
            if $mech-&gt;success();

    Returns a boolean telling whether the last request was successful. If
    there hasn't been an operation yet, returns false.

    This is a convenience function that wraps `$mech-&gt;res-&gt;is_success'.

  `$mech-&gt;status'
        $mech-&gt;get('http://google.com');
        print $mech-&gt;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.

  `$mech-&gt;reload( [$bypass_cache] )'
        $mech-&gt;reload();

    Reloads the current page. If `$bypass_cache' is a true value, the
    browser is not allowed to use a cached page. This is the difference
    between pressing `F5' (cached) and `shift-F5' (uncached).

    Returns the (new) response.

  `$mech-&gt;back( [$synchronize] )'
        $mech-&gt;back();

    Goes one page back in the page history.

    Returns the (new) response.

  `$mech-&gt;forward( [$synchronize] )'
        $mech-&gt;forward();

    Goes one page forward in the page history.

    Returns the (new) response.

  `$mech-&gt;uri'
        print "We are at " . $mech-&gt;uri;

    Returns the current document URI.

CONTENT METHODS
  `$mech-&gt;document'
    Returns the DOM document object.

    This is WWW::Mechanize::Firefox specific.

  `$mech-&gt;docshell'
        my $ds = $mech-&gt;docshell;

    Returns the `docShell' Javascript object associated with the tab.

    This is WWW::Mechanize::Firefox specific.

  `$mech-&gt;content'
      print $mech-&gt;content;

    This always returns the content as a Unicode string. It tries to decode
    the raw content according to its input encoding.

    This is likely not binary-safe.

    It also currently only works for HTML pages.

  $mech-&gt;text()
    Returns the text of the current HTML content. If the content isn't HTML,
    $mech will die.

  `$mech-&gt;content_encoding'
        print "The content is encoded as ", $mech-&gt;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-&gt;update_html( $html )'
      $mech-&gt;update_html($html);

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

  `$mech-&gt;save_content( $localname [, $resource_directory] [, %options ] )'
      $mech-&gt;get('http://google.com');
      $mech-&gt;save_content('google search page','google search page files');

    Saves the given URL to the given filename. The URL will be fetched from
    the cache if possible, avoiding unnecessary network traffic.

    If `$resource_directory' is given, the whole page will be saved. All
    CSS, subframes and images will be saved into that directory, while the
    page HTML itself will still be saved in the file pointed to by
    `$localname'.

    Returns a `nsIWebBrowserPersist' object through which you can cancel the
    download by calling its `-&gt;cancelSave' method. Also, you can poll the
    download status through the `-&gt;{currentState}' property.

    If you are interested in the intermediate download progress, create a
    ProgressListener through `$mech-&gt;progress_listener' and pass it in the
    `progress' option.

    The download will continue in the background. It will not show up in the
    Download Manager.

  `$mech-&gt;save_url( $url, $localname, [%options] )'
      $mech-&gt;save_url('http://google.com','google_index.html');

    Saves the given URL to the given filename. The URL will be fetched from
    the cache if possible, avoiding unnecessary network traffic.

    Returns a `nsIWebBrowserPersist' object through which you can cancel the
    download by calling its `-&gt;cancelSave' method. Also, you can poll the
    download status through the `-&gt;{currentState}' property.

    If you are interested in the intermediate download progress, create a
    ProgressListener through `$mech-&gt;progress_listener' and pass it in the
    `progress' option.

    The download will continue in the background. It will also not show up
    in the Download Manager.

  `$mech-&gt;base'
      print $mech-&gt;base;

    Returns the URL base for the current page.

    The base is either specified through a `base' tag or is the current URL.

    This method is specific to WWW::Mechanize::Firefox

  `$mech-&gt;content_type'
  `$mech-&gt;ct'
      print $mech-&gt;content_type;

    Returns the content type of the currently loaded document

  `$mech-&gt;is_html()'
      print $mech-&gt;is_html();

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

  `$mech-&gt;title'
      print "We are on page " . $mech-&gt;title;

    Returns the current document title.

EXTRACTION METHODS
  `$mech-&gt;links'
      print $_-&gt;text . " -&gt; " . $_-&gt;url . "\n"
          for $mech-&gt;links;

    Returns all links in the document as WWW::Mechanize::Link objects.

    Currently accepts no parameters. See `-&gt;xpath' or `-&gt;selector' when you
    want more control.

  `$mech-&gt;find_link_dom( %options )'
      print $_-&gt;{innerHTML} . "\n"
          for $mech-&gt;find_link_dom( text_contains =&gt; 'CPAN' );

    A method to find links, like WWW::Mechanize's `-&gt;find_links' method.
    This method returns DOM objects from Firefox instead of
    WWW::Mechanize::Link objects.

    Note that Firefox might have reordered the links or frame links in the
    document so the absolute numbers passed via `n' might not be the same
    between WWW::Mechanize and WWW::Mechanize::Firefox.

    Returns the DOM object as MozRepl::RemoteObject::Instance.

    The supported options are:

    *   `text' and `text_contains' and `text_regex'

        Match the text of the link as a complete string, substring or
        regular expression.

        Matching as a complete string or substring is a bit faster, as it is
        done in the XPath engine of Firefox.

    *   `id' and `id_contains' and `id_regex'

        Matches the `id' attribute of the link completely or as part

    *   `name' and `name_contains' and `name_regex'

        Matches the `name' attribute of the link

    *   `url' and `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 `croak's if no link is found. If the `single' option is
        true, it also `croak's when more than one link is found.

  `$mech-&gt;find_link( %options )'
      print $_-&gt;text . "\n"
          for $mech-&gt;find_link_dom( text_contains =&gt; 'CPAN' );

    A method quite similar to WWW::Mechanize's method. The options are
    documented in `-&gt;find_link_dom'.

    Returns a WWW::Mechanize::Link object.

    This defaults to not look through child frames.

  `$mech-&gt;find_all_links( %options )'
      print $_-&gt;text . "\n"
          for $mech-&gt;find_link_dom( text_regex =&gt; qr/google/i );

    Finds all links in the document. The options are documented in
    `-&gt;find_link_dom'.

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

    This defaults to not look through child frames.

  `$mech-&gt;find_all_links_dom %options'
      print $_-&gt;{innerHTML} . "\n"
          for $mech-&gt;find_link_dom( text_regex =&gt; qr/google/i );

    Finds all matching linky DOM nodes in the document. The options are
    documented in `-&gt;find_link_dom'.

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

    This defaults to not look through child frames.

  `$mech-&gt;follow_link $link'
  `$mech-&gt;follow_link %options'
      $mech-&gt;follow_link( xpath =&gt; '//a[text() = "Click here!"]' );

    Follows the given link. Takes the same parameters that `find_link_dom'
    uses. In addition, `synchronize' can be passed to (not) force waiting
    for a new page to be loaded.

    Note that `-&gt;follow_link' will only try to follow link-like things like
    `A' tags.

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

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

    Runs an XPath query in Firefox against the current document.

    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-&gt;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::Firefox object.

    *   `node' - node relative to which the query is to be executed

    *   `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 `-&gt;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.

    Returns the matched nodes.

    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.

    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-&gt;selector $css_selector, %options'
      my @text = $mech-&gt;selector('p.content');

    Returns all nodes matching the given CSS selector. If `$css_selector' is
    an array reference, it returns all nodes matched by any of the CSS
    selectors in the array.

    This takes the same options that `-&gt;xpath' does.

    In the long run, this should go into a general plugin for
    WWW::Mechanize.

  `$mech-&gt;by_id $id, %options'
      my @text = $mech-&gt;by_id('_foo:bar');

    Returns all nodes matching the given ids. If `$id' is an array
    reference, it returns all nodes matched by any of the ids in the array.

    This method is equivalent to calling `-&gt;xpath' :

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

    It is convenient when your element ids get mistaken for CSS selectors.

  `$mech-&gt;click $name [,$x ,$y]'
      $mech-&gt;click( 'go' );
      $mech-&gt;click({ xpath =&gt; '//button[@name="go"]' });

    Has the effect of clicking a button on the current form. The first
    argument is the `name' of the button to be clicked. The second and third
    arguments (optional) allow you to specify the (x,y) coordinates of the
    click.

    If there is only one button on the form, `$mech-&gt;click()' with no
    arguments simply clicks that one button.

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

    *   `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

    *   `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 =&gt; qq{//*[\@id="$id"}

    *   `synchronize' - Synchronize the click (default is 1)

        Synchronizing means that WWW::Mechanize::Firefox will wait until one
        of the events listed in `events' is fired. You want to switch it off
        when there will be no HTTP response or DOM event fired, for example
        for clicks that only modify the DOM.

    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-&gt;click_button( ... )'
      $mech-&gt;click_button( name =&gt; 'go' );
      $mech-&gt;click_button( input =&gt; $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.

    *   `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 `-&gt;click' instead.

FORM METHODS
  `$mech-&gt;current_form'
      print $mech-&gt;current_form-&gt;{name};

    Returns the current form.

    This method is incompatible with WWW::Mechanize. It returns the DOM
    `&lt;form&gt;' object and not a HTML::Form instance.

    Note that WWW::Mechanize::Firefox has little way to know that the
    current form is not displayed in the browser anymore, so it often holds
    on to the last value. If you want to make sure that a fresh or no form
    is used, remove it:

        $mech-&gt;clear_current_form;
    
    The current form will be reset by WWW::Mechanize::Firefox on calls to
    `-&gt;get()' and `-&gt;get_local()', and on calls to `-&gt;submit()' and
    `-&gt;submit_with_fields'.

  `$mech-&gt;form_name $name [, %options]'
      $mech-&gt;form_name( 'search' );

    Selects the current form by its name. The options are identical to those
    accepted by the $mech-xpath&gt; method.

  `$mech-&gt;form_id $id [, %options]'
      $mech-&gt;form_id( 'login' );

    Selects the current form by its `id' attribute. The options are
    identical to those accepted by the $mech-xpath&gt; method.

    This is equivalent to calling

        $mech-&gt;by_id($id,single =&gt; 1,%options)

  `$mech-&gt;form_number $number [, %options]'
      $mech-&gt;form_number( 2 );

    Selects the *number*th form. The options are identical to those accepted
    by the $mech-&gt;xpath method.

  `$mech-&gt;form_with_fields [$options], @fields'
      $mech-&gt;form_with_fields(
          'user', 'password'
      );

    Find the form which has the listed fields.

    If the first argument is a hash reference, it's taken as options to
    `-&gt;xpath'.

    See also $mech-&gt;submit_form.

  `$mech-&gt;forms %options'
      my @forms = $mech-&gt;forms();

    When called in a list context, returns a list of the forms found in the
    last fetched page. In a scalar context, returns a reference to an array
    with those forms.

    The options are identical to those accepted by the $mech-&gt;selector
    method.

    The returned elements are the DOM `&lt;form&gt;' elements.

  `$mech-&gt;field $selector, $value, [,\@pre_events [,\@post_events]]'
      $mech-&gt;field( user =&gt; 'joe' );
      $mech-&gt;field( not_empty =&gt; '', [], [] ); # bypass JS validation

    Sets the field with the name given in `$selector' to the given value.
    Returns the value.

    The method understands very basic CSS selectors in the value for
    `$selector', like the HTML::Form find_input() method.

    A selector prefixed with '#' must match the id attribute of the input. A
    selector prefixed with '.' matches the class attribute. A selector
    prefixed with '^' or with no prefix matches the name attribute.

    By passing the array reference `@pre_events', you can indicate which
    Javascript events you want to be triggered before setting the value.
    `@post_events' contains the events you want to be triggered after
    setting the value.

    By default, the events set in the constructor for `pre_events' and
    `post_events' are triggered.

  `$mech-&gt;value( $selector_or_element, [%options] )'
        print $mech-&gt;value( 'user' );

    Returns the value of the field given by `$selector_or_name' or of the
    DOM element passed in.

    The legacy form of

        $mech-&gt;value( name =&gt; value );

    is also still supported but will likely be deprecated in favour of the
    `-&gt;field' method.

    For fields that can have multiple values, like a `select' field, the
    method is context sensitive and returns the first selected value in
    scalar context and all values in list context.

  `$mech-&gt;get_set_value( %options )'
    Allows fine-grained access to getting/setting a value with a different
    API. Supported keys are:

      pre
      post
      name
      value

    in addition to all keys that `$mech-&gt;xpath' supports.

  `$mech-&gt;select( $name, $value )'
  `$mech-&gt;select( $name, \@values )'
    Given the name of a `select' field, set its value to the value
    specified. If the field is not `&lt;select multiple&gt;' and the `$value' is
    an array, only the first value will be set. Passing `$value' as a hash
    with an `n' key selects an item by number (e.g. `{n =&gt; 3}' or `{n =&gt;
    [2,4]}'). The numbering starts at 1. This applies to the current form.

    If you have a field with `&lt;select multiple&gt;' and you pass a single
    `$value', then `$value' will be added to the list of fields selected,
    without clearing the others. However, if you pass an array reference,
    then all previously selected values will be cleared.

    Returns true on successfully setting the value. On failure, returns
    false and calls `$self&gt;warn()' with an error message.

  `$mech-&gt;tick( $name, $value [, $set ] )'
        $mech-&gt;tick("confirmation_box", 'yes');

    "Ticks" the first checkbox that has both the name and value associated
    with it on the current form. Dies if there is no named check box for
    that value. Passing in a false value as the third optional argument will
    cause the checkbox to be unticked.

    (Un)ticking the checkbox is done by sending a click event to it if
    needed. If `$value' is `undef', the first checkbox matching `$name' will
    be (un)ticked.

    If `$name' is a reference to a hash, that hash will be used as the
    options to `-&gt;find_link_dom' to find the element.

  `$mech-&gt;untick($name, $value)'
      $mech-&gt;untick('spam_confirm','yes',undef)

    Causes the checkbox to be unticked. Shorthand for

      $mech-&gt;tick($name,$value,undef)

  `$mech-&gt;submit'
      $mech-&gt;submit;

    Submits the current form. Note that this does not fire the `onClick'
    event and thus also does not fire eventual Javascript handlers. Maybe
    you want to use `$mech-&gt;click' instead.

  `$mech-&gt;submit_form( %options )'
      $mech-&gt;submit_form(
          with_fields =&gt; {
              user =&gt; 'me',
              pass =&gt; 'secret',
          }
      );

    This method lets you select a form from the previously fetched page,
    fill in its fields, and submit it. 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, all of which
    are optional.

    *   `form =&gt; $mech-&gt;current_form()'

        Specifies the form to be filled and submitted. Defaults to the
        current form.

    *   `fields =&gt; \%fields'

        Specifies the fields to be filled in the current form

    *   `with_fields =&gt; \%fields'

        Probably all you need for the common case. It combines a smart form
        selector and data setting in one operation. It selects the first
        form that contains all 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-&gt;form_with_fields() and $mech-&gt;set_fields()).

        If you choose this, the form_number, form_name, form_id and fields
        options will be ignored.

  `$mech-&gt;set_fields( $name =&gt; $value, ... )'
      $mech-&gt;set_fields(
          user =&gt; 'me',
          pass =&gt; 'secret',
      );

    This method sets multiple fields of the current form. It takes a list of
    field name and value pairs. If there is more than one field with the
    same name, the first one found is set. If you want to select which of
    the duplicate field to set, use a value which is an anonymous array
    which has the field value and its number as the 2 elements.

  `$mech-&gt;set_visible( @values )'
      $mech-&gt;set_visible( $username, $password );

    This method sets fields of the current form without having to know their
    names. So if you have a login screen that wants a username and password,
    you do not have to fetch the form and inspect the source (or use the
    `mech-dump' utility, installed with WWW::Mechanize) to see what the
    field names are; you can just say

      $mech-&gt;set_visible( $username, $password );

    and the first and second fields will be set accordingly. The method is
    called set_visible because it acts only on visible fields; hidden form
    inputs are not considered.

    The specifiers that are possible in WWW::Mechanize are not yet
    supported.

  `$mech-&gt;is_visible $element'
  `$mech-&gt;is_visible %options'
      if ($mech-&gt;is_visible( selector =&gt; '#login' )) {
          print "You can log in now.";
      };

    Returns true if the element is visible, that is, it is a member of the
    DOM and neither it nor its ancestors have a CSS `visibility' attribute
    of `hidden' or a `display' attribute of `none'.

    You can either pass in a DOM element or a set of key/value pairs to
    search the document for the element you want.

    *   `xpath' - the XPath query

    *   `selector' - the CSS selector

    *   `dom' - a DOM node

    The remaining options are passed through to either the /$mech-&gt;xpath or
    /$mech-&gt;selector method.

  `$mech-&gt;wait_until_invisible( $element )'
  `$mech-&gt;wait_until_invisible( %options )'
      $mech-&gt;wait_until_invisible( $please_wait );

    Waits until an element is not visible anymore.

    Takes the same options as $mech-&gt;is_visible.

    In addition, the following options are accepted:

    *   `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.

  `$mech-&gt;clickables'
        print "You could click on\n";
        for my $el ($mech-&gt;clickables) {
            print $el-&gt;{innerHTML}, "\n";
        };

    Returns all clickable elements, that is, all elements with an `onclick'
    attribute.

  `$mech-&gt;expand_frames( $spec )'
      my @frames = $mech-&gt;expand_frames();

    Expands the frame selectors (or `1' to match all frames) into their
    respective DOM document nodes according to the current document. All
    frames will be visited in breadth first order.

    This is mostly an internal method.

IMAGE METHODS
  `$mech-&gt;content_as_png( [$tab, \%coordinates ] )'
        my $png_data = $mech-&gt;content_as_png();

    Returns the given tab or the current page rendered as PNG image.

    All parameters are optional.

    *   `$tab' defaults to the current tab.

    *   If the coordinates are given, that rectangle will be cut out. The
        coordinates should be a hash with the four usual entries,
        `left',`top',`width',`height'.

    This is specific to WWW::Mechanize::Firefox.

    Currently, the data transfer between Firefox and Perl is done
    Base64-encoded. It would be beneficial to find what's necessary to make
    JSON handle binary data more gracefully.

  `$mech-&gt;element_as_png( $element )'
        my $shiny = $mech-&gt;selector('#shiny', single =&gt; 1);
        my $i_want_this = $mech-&gt;element_as_png($shiny);

    Returns PNG image data for a single element

  `$mech-&gt;element_coordinates( $element )'
        my $shiny = $mech-&gt;selector('#shiny', single =&gt; 1);
        my ($pos) = $mech-&gt;element_coordinates($shiny);
        print $pos-&gt;{x},',', $pos-&gt;{y};

    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.

COOKIE HANDLING
    Firefox cookies will be read through HTTP::Cookies::MozRepl. This is
    relatively slow currently.

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.

  Link attributes
    In Firefox, the `name' attribute of links seems always to be present on
    links, even if it's empty. This is in difference to WWW::Mechanize,
    where the `name' attribute can be `undef'.

  Frame tags
    Firefox is much less lenient than WWW::Mechanize when it comes to FRAME
    tags. A page will not contain a FRAME tag if it contains content other
    than the FRAMESET. WWW::Mechanize has no such restriction.

  Unsupported Methods
    *   `-&gt;find_all_inputs'

        This function is likely best implemented through `$mech-&gt;selector'.

    *   `-&gt;find_all_submits'

        This function is likely best implemented through `$mech-&gt;selector'.

    *   `-&gt;images'

        This function is likely best implemented through `$mech-&gt;selector'.

    *   `-&gt;find_image'

        This function is likely best implemented through `$mech-&gt;selector'.

    *   `-&gt;find_all_images'

        This function is likely best implemented through `$mech-&gt;selector'.

  Functions that will likely never be implemented
    These functions are unlikely to be implemented because they make little
    sense in the context of Firefox.

    *   `-&gt;add_header'

    *   `-&gt;delete_header'

    *   `-&gt;clone'

    *   `-&gt;credentials( $username, $password )'

    *   `-&gt;get_basic_credentials( $realm, $uri, $isproxy )'

    *   `-&gt;clear_credentials()'

    *   `-&gt;put'

        I have no use for it

    *   `-&gt;post'

        I have no use for it

TODO
    *   Add `limit' parameter to `-&gt;xpath()' to allow an early exit-case
        when searching through frames.

    *   Implement download progress via
        `nsIWebBrowserPersist.progressListener' and our own
        `nsIWebProgressListener'.

    *   Rip out parts of Test::HTML::Content and graft them onto the
        `links()' and `find_link()' methods here. Firefox is a conveniently
        unified XPath engine.

        Preferrably, there should be a common API between the two.

    *   Spin off XPath queries (`-&gt;xpath') and CSS selectors (`-&gt;selector')
        into their own Mechanize plugin(s).

INSTALLING
    *   Install the `mozrepl' add-on into Firefox

    *   Start the `mozrepl' add-on or you will see test failures/skips in
        the module when calling `-&gt;new'. You may want to set `mozrepl' to
        start when the browser starts.

SEE ALSO
    *   The MozRepl Firefox plugin at http://wiki.github.com/bard/mozrepl

    *   WWW::Mechanize - the module whose API grandfathered this module

    *   WWW::Scripter - another WWW::Mechanize-workalike with Javascript
        support

    *   https://developer.mozilla.org/En/FUEL/Window for JS events relating
        to tabs

    *   https://developer.mozilla.org/en/Code_snippets/Tabbed_browser#Reusin
        g_tabs for more tab info

    *   https://developer.mozilla.org/en/Document_Loading_-_From_Load_Start_
        to_Finding_a_Handler for information on how to possibly override the
        "Save As" dialog

    *   http://code.google.com/p/selenium/source/browse/trunk/javascript/fir
        efox-driver/extension/components/promptService.js for information on
        how to override a lot of other prompts (like proxy etc.)

REPOSITORY
    The public repository of this module is
    http://github.com/Corion/www-mechanize-firefox.

SUPPORT
    The public support forum of this module is http://perlmonks.org/.

TALKS
    I've given two talks about this module at Perl conferences:

    http://corion.net/talks/WWW-Mechanize-FireFox/www-mechanize-firefox.html

    http://corion.net/talks/WWW-Mechanize-FireFox/www-mechanize-firefox.en.h
    tml

BUG TRACKER
    Please report bugs in this module via the RT CPAN bug queue at
    https://rt.cpan.org/Public/Dist/Display.html?Name=WWW-Mechanize-Firefox
    or via mail to www-mechanize-firefox-Bugs@rt.cpan.org.

AUTHOR
    Max Maischein `corion@cpan.org'

COPYRIGHT (c)
    Copyright 2009-2011 by Max Maischein `corion@cpan.org'.

LICENSE
    This module is released under the same terms as Perl itself.

</pre></body></html>