.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Weasel::Session 3pm"
.TH Weasel::Session 3pm "2023-08-21" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Weasel::Session \- Connection to an encapsulated test driver
.SH "VERSION"
.IX Header "VERSION"
0.30
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use Weasel;
\&  use Weasel::Session;
\&  use Weasel::Driver::Selenium2;
\&
\&  my $weasel = Weasel\->new(
\&       default_session => \*(Aqdefault\*(Aq,
\&       sessions => {
\&          default => Weasel::Session\->new(
\&            driver => Weasel::Driver::Selenium2\->new(%opts),
\&          ),
\&       });
\&
\&  $weasel\->session\->get(\*(Aqhttp://localhost/index\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.IP "driver" 4
.IX Item "driver"
Holds a reference to the sessions's driver.
.IP "widget_groups" 4
.IX Item "widget_groups"
Contains the list of widget groups to be used with the session, or
uses all groups when undefined.
.Sp
Note: this functionality allows one to load multiple groups into the running
perl instance, while using different groups in various sessions.
.IP "base_url" 4
.IX Item "base_url"
Holds the prefix that will be prepended to every \s-1URL\s0 passed
to this \s-1API.\s0
The prefix can be an environment variable, e.g. ${\s-1VARIABLE\s0}.
It will be expanded and default to hppt://localhost:5000 if not defined.
If it is not an environment variable, it will be used as is.
.IP "page" 4
.IX Item "page"
Holds the root element of the target \s-1HTML\s0 page (the 'html' tag).
.IP "log_hook" 4
.IX Item "log_hook"
Upon instantiation can be set to log consumer; a function of 3 arguments:
 1. the name of the event
 2. the text to be logged (or a coderef to be called without arguments returning such)
.IP "page_class" 4
.IX Item "page_class"
Upon instantiation can be set to an alternative class name for the \f(CW\*(C`page\*(C'\fR
attribute.
.IP "retry_timeout" 4
.IX Item "retry_timeout"
The number of seconds to poll for a condition to become true. Global
setting for the \f(CW\*(C`wait_for\*(C'\fR function.
.IP "poll_delay" 4
.IX Item "poll_delay"
The number of seconds to wait between state polling attempts. Global
setting for the \f(CW\*(C`wait_for\*(C'\fR function.
.IP "state" 4
.IX Item "state"
Holds one of
.RS 4
.IP "\(bu" 4
initial
.IP "\(bu" 4
started
.IP "\(bu" 4
stopped
.RE
.RS 4
.Sp
Before the first page is loaded into the browser, the value of the
\&\f(CW\*(C`state\*(C'\fR property is \f(CW\*(C`initial\*(C'\fR. After the first \f(CW\*(C`get\*(C'\fR call, the
value changes to \f(CW\*(C`started\*(C'\fR.
.RE
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.IP "clear($element)" 4
.IX Item "clear($element)"
Clears any input entered into elements supporting it.  Generally applies to
textarea elements and input elements of type text and password.
.IP "click([$element])" 4
.IX Item "click([$element])"
Simulates a single mouse click. If an element argument is provided, that
element is clicked.  Otherwise, the browser window is clicked at the
current mouse location.
.ie n .IP "find($element, $locator [, scheme => $scheme] [, widget_args => \e@args ] [, %locator_args])" 4
.el .IP "find($element, \f(CW$locator\fR [, scheme => \f(CW$scheme\fR] [, widget_args => \e@args ] [, \f(CW%locator_args\fR])" 4
.IX Item "find($element, $locator [, scheme => $scheme] [, widget_args => @args ] [, %locator_args])"
Finds the first child of \f(CW$element\fR matching \f(CW$locator\fR.
.Sp
See Weasel::Element's \f(CW\*(C`find\*(C'\fR function for more documentation.
.ie n .IP "find_all($element, $locator, [, scheme => $scheme] [, widget_args => \e@args ] [, %locator_args ])" 4
.el .IP "find_all($element, \f(CW$locator\fR, [, scheme => \f(CW$scheme\fR] [, widget_args => \e@args ] [, \f(CW%locator_args\fR ])" 4
.IX Item "find_all($element, $locator, [, scheme => $scheme] [, widget_args => @args ] [, %locator_args ])"
Finds all child elements of \f(CW$element\fR matching \f(CW$locator\fR. Returns,
depending on scalar or list context, an arrayref or a list with matching
elements.
.Sp
See Weasel::Element's \f(CW\*(C`find_all\*(C'\fR function for more documentation.
.IP "get($url)" 4
.IX Item "get($url)"
Loads \f(CW$url\fR into the active browser window of the driver connection,
after prefixing with \f(CW\*(C`base_url\*(C'\fR.
.ie n .IP "get_attribute($element, $attribute)" 4
.el .IP "get_attribute($element, \f(CW$attribute\fR)" 4
.IX Item "get_attribute($element, $attribute)"
Returns the value of the attribute named by \f(CW$attribute\fR of the element
identified by \f(CW$element\fR, or \f(CW\*(C`undef\*(C'\fR if the attribute isn't defined.
.IP "get_text($element)" 4
.IX Item "get_text($element)"
Returns the 'innerHTML' of the element identified by \f(CW$element\fR.
.ie n .IP "set_attribute($element_id, $attribute_name, $value)" 4
.el .IP "set_attribute($element_id, \f(CW$attribute_name\fR, \f(CW$value\fR)" 4
.IX Item "set_attribute($element_id, $attribute_name, $value)"
\&\s-1DEPRECATED\s0
.Sp
Changes the value of the attribute named by \f(CW$attribute_name\fR to \f(CW$value\fR
for the element identified by \f(CW$element_id\fR.
.IP "get_selected($element_id)" 4
.IX Item "get_selected($element_id)"
\&\s-1DEPRECATED\s0
.Sp
Please use \f(CW\*(C`$self\-\*(C'\fRget_attribute('selected')> instead.
.ie n .IP "set_selected($element_id, $value)" 4
.el .IP "set_selected($element_id, \f(CW$value\fR)" 4
.IX Item "set_selected($element_id, $value)"
\&\s-1DEPRECATED\s0
.Sp
Please use \f(CW\*(C`$self\-\*(C'\fRset_attribute('selected', \f(CW$value\fR)> instead.
.IP "is_displayed($element)" 4
.IX Item "is_displayed($element)"
Returns a boolean value indicating if the element identified by
\&\f(CW$element\fR is visible on the page, i.e. that it can be scrolled into
the viewport for interaction.
.IP "screenshot($fh)" 4
.IX Item "screenshot($fh)"
Writes a screenshot of the browser's window to the filehandle \f(CW$fh\fR.
.Sp
Note: this version assumes pictures of type \s-1PNG\s0 will be written;
  later versions may provide a means to query the exact image type of
  screenshots being generated.
.IP "start" 4
.IX Item "start"
Starts a new or stopped session.
.Sp
Sets \f(CW\*(C`state\*(C'\fR back to the value \f(CW\*(C`initial\*(C'\fR.
.IP "restart" 4
.IX Item "restart"
Restarts a session by resetting it and starting.
.Sp
Sets \f(CW\*(C`state\*(C'\fR back to the value \f(CW\*(C`initial\*(C'\fR.
.IP "stop" 4
.IX Item "stop"
.PD 0
.IP "started" 4
.IX Item "started"
.PD
Returns a \f(CW\*(C`true\*(C'\fR value when the session has been started.
.IP "get_page_source($fh)" 4
.IX Item "get_page_source($fh)"
Writes a get_page_source of the browser's window to the filehandle \f(CW$fh\fR.
.ie n .IP "send_keys($element, @keys)" 4
.el .IP "send_keys($element, \f(CW@keys\fR)" 4
.IX Item "send_keys($element, @keys)"
Send the characters specified in the strings in \f(CW@keys\fR to \f(CW$element\fR,
simulating keyboard input.
.IP "tag_name($element)" 4
.IX Item "tag_name($element)"
Returns the tag name of the element identified by \f(CW$element\fR.
.ie n .IP "wait_for($callback, [ retry_timeout => $number,] [poll_delay => $number,] [ on_timeout => \e&cb ])" 4
.el .IP "wait_for($callback, [ retry_timeout => \f(CW$number\fR,] [poll_delay => \f(CW$number\fR,] [ on_timeout => \e&cb ])" 4
.IX Item "wait_for($callback, [ retry_timeout => $number,] [poll_delay => $number,] [ on_timeout => &cb ])"
Polls \f(CW$callback\fR\->() until it returns true, or \f(CW\*(C`wait_timeout\*(C'\fR expires
\&\*(-- whichever comes first.
.Sp
The arguments retry_timeout and poll_delay can be used to override the
session-global settings.
.ie n .IP "_logged($wrapped_fn, $event, $log_item, $log_item_pre)" 4
.el .IP "_logged($wrapped_fn, \f(CW$event\fR, \f(CW$log_item\fR, \f(CW$log_item_pre\fR)" 4
.IX Item "_logged($wrapped_fn, $event, $log_item, $log_item_pre)"
Invokes \f(CW\*(C`log_hook\*(C'\fR when it's defined, before and after calling \f(CW$wrapped_fn\fR
with no arguments, with the 'pre_' and 'post_' prefixes to the event name.
.Sp
\&\f(CW$log_item\fR can be a fixed string or a function of one argument returning
the string to be logged. The argument passed into the function is the value
returned by the \f(CW$wrapped_fn\fR.
.Sp
In case there is no \f(CW$log_item_pre\fR to be called on the 'pre_' event,
\&\f(CW$log_item\fR will be used instead, with no arguments.
.Sp
For performance reasons, the \f(CW$log_item\fR and \f(CW$log_item_pre\fR \- when
coderefs \- aren't called; instead they are passed as-is to the
\&\f(CW$log_hook\fR for lazy evaluation.
.IP "_wrap_widget($_id)" 4
.IX Item "_wrap_widget($_id)"
Finds all matching widget selectors to wrap the driver element in.
.Sp
In case of multiple matches, selects the most specific match
(the one with the highest number of requirements).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Weasel
.SH "AUTHOR"
.IX Header "AUTHOR"
Erik Huelsmann
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.Vb 2
\& Erik Huelsmann
\& Yves Lavoie
.Ve
.SH "MAINTAINERS"
.IX Header "MAINTAINERS"
Erik Huelsmann
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
Bugs can be filed in the GitHub issue tracker for the Weasel project:
 https://github.com/perl\-weasel/weasel/issues
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for Weasel is at
 https://github.com/perl\-weasel/weasel
.SH "SUPPORT"
.IX Header "SUPPORT"
Community support is available through
perl\-weasel@googlegroups.com <mailto:perl-weasel@googlegroups.com>.
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
.Vb 1
\& (C) 2016\-2023  Erik Huelsmann
.Ve
.PP
Licensed under the same terms as Perl.