.\" 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 3pm"
.TH Weasel 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 \- Perl's php/Mink\-inspired abstracted web\-driver framework
.SH "VERSION"
.IX Header "VERSION"
0.31
.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"
This module abstracts away the differences between the various
web-driver protocols, like the Mink project does for \s-1PHP.\s0
.PP
While heavily inspired by Mink, \f(CW\*(C`Weasel\*(C'\fR aims to improve over it
by being extensible, providing not just access to the underlying
browser, yet to provide building blocks for further development
and abstraction.
.PP
Pherkin::Extension::Weasel provides integration with
Test::BDD::Cucumber (aka pherkin), for \s-1BDD\s0 testing.
.PP
For the actual page interaction, this module needs a driver to
be installed.  Currently, that means Weasel::Driver::Selenium2.
Other driver implementations, such as Sahi <http://sahipro.com/>
can be independently developed and uploaded to \s-1CPAN,\s0 or contributed.
(We welcome and encourage both!)
.SS "\s-1DIFFERENCES WITH OTHER FRAMEWORKS\s0"
.IX Subsection "DIFFERENCES WITH OTHER FRAMEWORKS"
.IP "Mnemonics for element lookup patterns" 4
.IX Item "Mnemonics for element lookup patterns"
The central registry of xpath expressions to find common page elements
helps to keep page access code clean. E.g. compare:
.Sp
.Vb 2
\&   use Weasel::FindExpanders::HTML;
\&   $session\->page\->find(\*(Aq*contains\*(Aq, text => \*(AqSome text\*(Aq);
.Ve
.Sp
With
.Sp
.Vb 2
\&   $session\->page\->find(".//*[contains(.,\*(AqSome text\*(Aq)]
\&                              [not(.//*[contains(.,\*(AqSome text\*(Aq)])]");
.Ve
.Sp
Multiple patterns can be registered for a single mnemonic, which
will be concatenated to a single xpath expression to find the matching
tags in a single driver query.
.Sp
Besides good performance, this has the benefit that the following
.Sp
.Vb 1
\&   $session\->page\->find(\*(Aq*button\*(Aq, text => \*(AqClick!\*(Aq);
.Ve
.Sp
can be easily extended to match
Dojo toolkit's <http://dojotoolkit.org/documentation/> buttons, which
on the \s-1HTML\s0 level don't contain visible button or input tags, simply
by using the widget support set:
.Sp
.Vb 1
\&   use Weasel::Widgets::Dojo;
.Ve
.IP "Widgets encapsulate specific behaviours" 4
.IX Item "Widgets encapsulate specific behaviours"
All elements in \f(CW\*(C`Weasel\*(C'\fR are of the base type \f(CW\*(C`Weasel::Element\*(C'\fR, which
encapsulates the regular element interactions (click, find children, etc).
.Sp
While most elements will be represented by \f(CW\*(C`Weasel::Element\*(C'\fR, it's possible
to implement other wrappers.  These offer a logical extension point to
implement tag-specific utility functions.  E.g.
\&\f(CW\*(C`Weasel::Widgets::HTML::Select\*(C'\fR, which adds the utility function
\&\f(CW\*(C`select_option\*(C'\fR.
.Sp
These widgets also offer a good way to override default behaviours.  One
such case is the Dojo implementation of a 'select' element.  This element
replaces the select tag entirely and in contrast with the original, doesn't
keep the options as child elements of the 'select'\-replacing tag.  By using
the Dojo widget library
.Sp
.Vb 1
\&   use Weasel::Widget::Dojo;
.Ve
.Sp
the lack of the parent/child relation between the the select and its options
is transparently handled by overriding the widget's \f(CW\*(C`find\*(C'\fR and \f(CW\*(C`find_all\*(C'\fR
methods.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.IP "\s-1KEYS\s0" 4
.IX Item "KEYS"
Returns a reference to a hash with names of the keys in the
hash keys and single-character strings containing the key
codes as the values.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.IP "default_session" 4
.IX Item "default_session"
The name of the default session to return from \f(CW\*(C`session\*(C'\fR, in case
no name argument is provided.
.IP "sessions" 4
.IX Item "sessions"
Holds the sessions registered with the \f(CW\*(C`Weasel\*(C'\fR instance.
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.ie n .IP "session([$name [, $value]])" 4
.el .IP "session([$name [, \f(CW$value\fR]])" 4
.IX Item "session([$name [, $value]])"
Returns the session identified by \f(CW$name\fR.
.Sp
If \f(CW$value\fR is specified, it's associated with the given \f(CW$name\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 1
\&  Erik Huelsmann
.Ve
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.Vb 2
\&  Erik Huelsmann
\&  Yves Lavoie
.Ve
.SH "MAINTAINERS"
.IX Header "MAINTAINERS"
.Vb 1
\&  Erik Huelsmann
.Ve
.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 "BUGS"
.IX Header "BUGS"
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.