.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Test::XPath 3pm"
.TH Test::XPath 3pm "2019-02-22" "perl v5.28.1" "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"
.IX Header "Name"
Test::XPath \- Test \s-1XML\s0 and \s-1HTML\s0 content and structure with XPath expressions
.SH "Synopsis"
.IX Header "Synopsis"
.Vb 2
\&  use Test::More tests => 5;
\&  use Test::XPath;
\&
\&  my $xml = <<\*(AqXML\*(Aq;
\&  <html>
\&    <head>
\&      <title>Hello</title>
\&      <style type="text/css" src="foo.css"></style>
\&      <style type="text/css" src="bar.css"></style>
\&    </head>
\&    <body>
\&      <h1>Welcome to my lair.</h1>
\&    </body>
\&  </html>
\&  XML
\&
\&  my $tx = Test::XPath\->new( xml => $xml );
\&
\&  $tx\->ok( \*(Aq/html/head\*(Aq, \*(AqThere should be a head\*(Aq );
\&  $tx\->is( \*(Aq/html/head/title\*(Aq, \*(AqHello\*(Aq, \*(AqThe title should be correct\*(Aq );
\&
\&  # Recursing into a document:
\&  my @css = qw(foo.css bar.css);
\&  $tx\->ok( \*(Aq/html/head/style[@type="text/css"]\*(Aq, sub {
\&      my $css = shift @css;
\&      shift\->is( \*(Aq./@src\*(Aq, $css, "Style src should be $css");
\&  }, \*(AqShould have style\*(Aq );
\&
\&  # Better yet, use PerlX::MethodCallWithBlock:
\&  use PerlX::MethodCallWithBlock;
\&  my @css = qw(foo.css bar.css);
\&  use PerlX::MethodCallWithBlock;
\&  $tx\->ok( \*(Aq/html/head/style[@type="text/css"]\*(Aq, \*(AqShould have style\*(Aq ) {
\&      my $css = shift @css;
\&      shift\->is( \*(Aq./@src\*(Aq, $css, "Style src should be $css");
\&  };
\&
\&  # Or use CSS Selectors:
\&  $tx = Test::XPath\->new( xml => $xml, filter => \*(Aqcss_selector\*(Aq );
\&  $tx\->ok( \*(Aq> html > head\*(Aq, \*(AqThere should be a head\*(Aq );
.Ve
.SH "Description"
.IX Header "Description"
Use the power of XPath expressions to validate the structure of your \s-1XML\s0 and
\&\s-1HTML\s0 documents.
.SS "About XPath"
.IX Subsection "About XPath"
XPath is a powerful query language for \s-1XML\s0 documents. Test::XPath relies on
the libxml2 implementation provided by XML::LibXML. libxml2 \*(-- pretty much
the canonical library for \s-1XML\s0 processing \*(-- provides an efficient and complete
implementation of the XPath spec.
.PP
XPath works by selecting nodes in an \s-1XML\s0 document. Nodes, in general,
correspond to the elements (a.k.a. tags) defined in the \s-1XML,\s0 text within those
elements, attribute values, and comments. The expressions for making such
selections use a URI-like syntax, the basics of which are:
.ie n .IP "$nodename" 4
.el .IP "\f(CW$nodename\fR" 4
.IX Item "$nodename"
Selects all child nodes with the name.
.ie n .IP """/""" 4
.el .IP "\f(CW/\fR" 4
.IX Item "/"
Selects the root node.
.ie n .IP """//""" 4
.el .IP "\f(CW//\fR" 4
.IX Item "//"
Selects nodes from the current node that match the selection, regardless of
where they are in the node hierarchy.
.ie n .IP """.""" 4
.el .IP "\f(CW.\fR" 4
.IX Item "."
Selects the current node.
.ie n .IP """..""" 4
.el .IP "\f(CW..\fR" 4
.IX Item ".."
Selects the parent of the current node.
.ie n .IP """@""" 4
.el .IP "\f(CW@\fR" 4
.IX Item "@"
Selects attributes.
.PP
And some examples:
.ie n .IP """head""" 4
.el .IP "\f(CWhead\fR" 4
.IX Item "head"
Selects all of the child nodes of the \*(L"head\*(R" element.
.ie n .IP """/html""" 4
.el .IP "\f(CW/html\fR" 4
.IX Item "/html"
Selects the root \*(L"html\*(R" element.
.ie n .IP """body/p""" 4
.el .IP "\f(CWbody/p\fR" 4
.IX Item "body/p"
Selects all \*(L"p\*(R" elements that are children of the \*(L"body\*(R" element.
.ie n .IP """//p""" 4
.el .IP "\f(CW//p\fR" 4
.IX Item "//p"
Selects all \*(L"p\*(R" elements no matter where they are in the document.
.ie n .IP """body//p""" 4
.el .IP "\f(CWbody//p\fR" 4
.IX Item "body//p"
Selects all \*(L"p\*(R" elements that are descendants of the \*(L"body\*(R" element, no matter
where they appear under the \*(L"body\*(R" element.
.ie n .IP """//@lang""" 4
.el .IP "\f(CW//@lang\fR" 4
.IX Item "//@lang"
Selects all attributes named \*(L"lang\*(R".
.PP
There are also useful predicates to select certain nodes. Some examples:
.ie n .IP """body//p[1]""" 4
.el .IP "\f(CWbody//p[1]\fR" 4
.IX Item "body//p[1]"
Select the first paragraph under the body element.
.ie n .IP """body//p[last()]""" 4
.el .IP "\f(CWbody//p[last()]\fR" 4
.IX Item "body//p[last()]"
Select the last paragraph under the body element.
.ie n .IP """//script[@src]""" 4
.el .IP "\f(CW//script[@src]\fR" 4
.IX Item "//script[@src]"
Select all \*(L"script\*(R" nodes that have a \*(L"src\*(R" attribute.
.ie n .IP """//script[@src=\*(Aqfoo.js\*(Aq]""" 4
.el .IP "\f(CW//script[@src=\*(Aqfoo.js\*(Aq]\fR" 4
.IX Item "//script[@src=foo.js]"
Select all \*(L"script\*(R" nodes that have a \*(L"src\*(R" attribute set to \*(L"foo.js\*(R".
.ie n .IP """//img[@height > 400]""" 4
.el .IP "\f(CW//img[@height > 400]\fR" 4
.IX Item "//img[@height > 400]"
Select all \*(L"img\*(R" nodes with a height attribute greater than 400.
.ie n .IP """head/*""" 4
.el .IP "\f(CWhead/*\fR" 4
.IX Item "head/*"
Select all child nodes below the \*(L"head\*(R" node.
.ie n .IP """p[@*]""" 4
.el .IP "\f(CWp[@*]\fR" 4
.IX Item "p[@*]"
Select all \*(L"p\*(R" nodes that have any attribute.
.ie n .IP """count(//p)""" 4
.el .IP "\f(CWcount(//p)\fR" 4
.IX Item "count(//p)"
Select a count of all \*(L"p\*(R" nodes in the document.
.ie n .IP """contains(//title, ""Welcome"")""" 4
.el .IP "\f(CWcontains(//title, ``Welcome'')\fR" 4
.IX Item "contains(//title, ""Welcome"")"
Select true if the title node contains the string \*(L"Welcome\*(R", and false if it
does not.
.PP
There are a bunch of core functions in XPath. In addition to the (\f(CW\*(C`last()\*(C'\fR
and \f(CW\*(C`count()\*(C'\fR) examples above, there are functions for node sets, booleans,
numbers, and strings. See the
XPath 1.0 W3C Recommendation <http://www.w3.org/TR/xpath>, for thorough (and
quite readable) documentation of XPath support, including syntax and the core
functions. The W3Schools tutorial <http://www.w3schools.com/Xpath/default.asp>
provides a nice overview of XPath.
.SS "Testing \s-1HTML\s0"
.IX Subsection "Testing HTML"
If you want to use XPath to test the content and structure of an \s-1HTML\s0 document,
be sure to pass the \f(CW\*(C`is_html\*(C'\fR option to \f(CW\*(C`new()\*(C'\fR, like so:
.PP
.Vb 1
\&  my $tx = Test::XPath\->new( xml => $html, is_html => 1 );
.Ve
.PP
Test::XPath will then use XML::LibXML's \s-1HTML\s0 parser to parse the document,
rather than its \s-1XML\s0 parser. The upshot is that you won't have to worry about
namespace prefixes, and XML::LibXML won't try to fetch any \s-1DTD\s0 specified in
the \s-1DOCTYPE\s0 section of your \s-1HTML.\s0
.SH "Class Interface"
.IX Header "Class Interface"
.SS "Constructor"
.IX Subsection "Constructor"
\fI\f(CI\*(C`new\*(C'\fI\fR
.IX Subsection "new"
.PP
.Vb 1
\&  my $tx = Test::XPath\->new( xml => $xml );
.Ve
.PP
Creates and returns an XML::XPath object. This object can be used to run XPath
tests on the \s-1XML\s0 passed to it. The supported parameters are:
.ie n .IP """xml""" 4
.el .IP "\f(CWxml\fR" 4
.IX Item "xml"
.Vb 1
\&  xml => \*(Aq<foo><bar>hey</bar></foo>\*(Aq,
.Ve
.Sp
The \s-1XML\s0 to be parsed and tested. Required unless the \f(CW\*(C`file\*(C'\fR or \f(CW\*(C`doc\*(C'\fR option
is passed.
.ie n .IP """file""" 4
.el .IP "\f(CWfile\fR" 4
.IX Item "file"
.Vb 1
\&  file => \*(Aqrss.xml\*(Aq,
.Ve
.Sp
Name of a file containing the \s-1XML\s0 to be parsed and tested. Required unless the
\&\f(CW\*(C`xml\*(C'\fR or \f(CW\*(C`doc\*(C'\fR option is passed.
.ie n .IP """doc""" 4
.el .IP "\f(CWdoc\fR" 4
.IX Item "doc"
.Vb 1
\&  doc => XML::LibXML\->new\->parse_file($xml_file),
.Ve
.Sp
An XML::LibXML document object. Required unless the \f(CW\*(C`xml\*(C'\fR or \f(CW\*(C`file\*(C'\fR option
is passed.
.ie n .IP """is_html""" 4
.el .IP "\f(CWis_html\fR" 4
.IX Item "is_html"
.Vb 1
\&  is_html => 1,
.Ve
.Sp
If the \s-1XML\s0 you're testing is actually \s-1HTML,\s0 pass this option a true value and
XML::LibXML's \s-1HTML\s0 parser will be used instead of the \s-1XML\s0 parser. This is
especially useful if your \s-1HTML\s0 has a \s-1DOCTYPE\s0 declaration or an \s-1XML\s0 namespace
(xmlns attribute) and you don't want the parser grabbing the \s-1DTD\s0 over the
Internet and you don't want to mess with a namespace prefix in your XPath
expressions.
.ie n .IP """xmlns""" 4
.el .IP "\f(CWxmlns\fR" 4
.IX Item "xmlns"
.Vb 4
\&  xmlns => {
\&      x => \*(Aqhttp://www.w3.org/1999/xhtml\*(Aq,
\&      a => \*(Aqhttp://www.w3.org/2007/app\*(Aq,
\&  },
.Ve
.Sp
Set up prefixes for \s-1XML\s0 namespaces. Required if your \s-1XML\s0 uses namespaces and
you want to write reasonable XPath expressions.
.ie n .IP """options""" 4
.el .IP "\f(CWoptions\fR" 4
.IX Item "options"
.Vb 1
\&  options => { recover_silently => 1, no_network => 1 },
.Ve
.Sp
Optional hash reference of
XML::LibXML::Parser options, such as
\&\*(L"validation\*(R", \*(L"recover\*(R", \*(L"suppress_errors\*(R", and \*(L"no_network\*(R". These can be
useful for tweaking the behavior of the parser.
.ie n .IP """filter""" 4
.el .IP "\f(CWfilter\fR" 4
.IX Item "filter"
.Vb 2
\&  filter => \*(Aqcss_selector\*(Aq,
\&  filter => sub { my $xpath = shift; },
.Ve
.Sp
Pass a filter name or a code reference for Test::XPath to use to filter XPath
expressions before passing them on to XML::LibXML. The code reference argument
allows you to transform XPath expressions if, for example, you use a custom
XPath syntax that's more concise than XPath.
.Sp
There is currently only one built-in filter, \f(CW\*(C`css_selector\*(C'\fR. So if you pass
.Sp
.Vb 1
\&  filter => \*(Aqcss_selector\*(Aq,
.Ve
.Sp
Then any paths passed to \f(CW\*(C`ok()\*(C'\fR, \f(CW\*(C`is()\*(C'\fR, etc., will be passed through
HTML::Selector::XPath. This allows you to use \s-1CSS\s0 selector syntax, which
can be more compact for simple expressions. For example, this \s-1CSS\s0 selector:
.Sp
.Vb 1
\&    $tx\->is(\*(Aqdiv#content div.article h1\*(Aq, \*(Aq...\*(Aq)
.Ve
.Sp
Is equivalent to this XPath expression:
.Sp
.Vb 1
\&    $tx\->is(\*(Aq//div[@id="content"]//div[@class="article"]//h1\*(Aq, \*(Aq...\*(Aq)
.Ve
.SH "Instance Interface"
.IX Header "Instance Interface"
.SS "Assertions"
.IX Subsection "Assertions"
\fI\f(CI\*(C`ok\*(C'\fI\fR
.IX Subsection "ok"
.PP
.Vb 2
\&  $tx\->ok( $xpath, $description )
\&  $tx\->ok( $xpath, $coderef, $description )
.Ve
.PP
Test that an XPath expression evaluated against the \s-1XML\s0 document returns a
true value. If the XPath expression finds no nodes, the result will be false.
If it finds a value, the value must be a true value (in the Perl sense).
.PP
.Vb 2
\&  $tx\->ok( \*(Aq//foo/bar\*(Aq, \*(AqShould have bar element under foo element\*(Aq );
\&  $tx\->ok( \*(Aqcontains(//title, "Welcome")\*(Aq, \*(AqTitle should "Welcome"\*(Aq );
.Ve
.PP
You can also run recursive tests against your document by passing a code
reference as the second argument to \f(CW\*(C`ok()\*(C'\fR. Once the initial selection has
been completed, each selected node will be assigned to the \f(CW\*(C`node\*(C'\fR attribute
and the XML::XPath object passed to the code reference. For example, if you
wanted to test for the presence of \*(L"story\*(R" elements in your document, and to
test that each such element had an incremented \*(L"id\*(R" attribute, you'd do
something like this:
.PP
.Vb 4
\&  my $i = 0;
\&  $tx\->ok( \*(Aq//assets/story\*(Aq, sub {
\&      shift\->is(\*(Aq./@id\*(Aq, ++$i, "ID should be $i in story $i");
\&  }, \*(AqShould have story elements\*(Aq );
.Ve
.PP
Even better, use PerlX::MethodCallWithBlock to pass a block to the method
instead of a code reference:
.PP
.Vb 5
\&  use PerlX::MethodCallWithBlock;
\&  my $i = 0;
\&  $tx\->ok( \*(Aq//assets/story\*(Aq, \*(AqShould have story elements\*(Aq ) {
\&      shift\->is(\*(Aq./@id\*(Aq, ++$i, "ID should be $i in story $i");
\&  };
.Ve
.PP
For convenience, the XML::XPath object is also assigned to \f(CW$_\fR for the
duration of the call to the code reference. Either way, you can call \f(CW\*(C`ok()\*(C'\fR
and pass code references anywhere in the hierarchy. For example, to ensure
that an Atom feed has entries and that each entry has a title, a link, and a
very specific author element with name, uri, and email subnodes, you can do
this:
.PP
.Vb 8
\&  $tx\->ok( \*(Aq/feed/entry\*(Aq, sub {
\&      $_\->ok( \*(Aq./title\*(Aq, \*(AqShould have a title\*(Aq );
\&      $_\->ok( \*(Aq./author\*(Aq, sub {
\&          $_\->is( \*(Aq./name\*(Aq,  \*(AqMark Pilgrim\*(Aq,        \*(AqMark should be author\*(Aq );
\&          $_\->is( \*(Aq./uri\*(Aq,   \*(Aqhttp://example.org/\*(Aq, \*(AqURI should be correct\*(Aq );
\&          $_\->is( \*(Aq./email\*(Aq, \*(Aqf8dy@example.com\*(Aq,    \*(AqEmail should be right\*(Aq );
\&      }, \*(AqShould have author elements\*(Aq );
\&  }, \*(AqShould have entry elments\*(Aq );
.Ve
.PP
\fI\f(CI\*(C`not_ok\*(C'\fI\fR
.IX Subsection "not_ok"
.PP
.Vb 1
\&  $tx\->not_ok( $xpath, $description )
.Ve
.PP
The reverse of the non-recursive \f(CW\*(C`ok()\*(C'\fR, the test succeeds if the XPath
expression matches no part of the document.
.PP
.Vb 1
\&  $tx\->not_ok( \*(Aq//foo/bar[@id=0]\*(Aq, \*(AqShould have no bar elements with Id 0\*(Aq );
.Ve
.PP
\fI\f(CI\*(C`is\*(C'\fI\fR
.IX Subsection "is"
.PP
\fI\f(CI\*(C`isnt\*(C'\fI\fR
.IX Subsection "isnt"
.PP
.Vb 2
\&  $tx\->is( $xpath, $want, $description );
\&  $tx\->isnt( $xpath, $dont_want, $description );
.Ve
.PP
\&\f(CW\*(C`is()\*(C'\fR and \f(CW\*(C`isnt()\*(C'\fR compare the value returned by evaluation of the XPath
expression against the document to a value using \f(CW\*(C`eq\*(C'\fR and \f(CW\*(C`ne\*(C'\fR,
respectively.
.PP
.Vb 2
\&  $tx\->is( \*(Aq/html/head/title\*(Aq, \*(AqWelcome\*(Aq, \*(AqTitle should be welcoming\*(Aq );
\&  $tx\->isnt( \*(Aq/html/head/link/@type\*(Aq, \*(Aqhello\*(Aq, \*(AqLink type should not\*(Aq );
.Ve
.PP
As with \f(CW\*(C`Test::More::ok()\*(C'\fR, a failing test will yield a useful diagnostic
message, something like:
.PP
.Vb 4
\&  #   Failed test \*(AqTitle should be welcoming\*(Aq
\&  #   at t/foo.t line 47.
\&  #          got: \*(AqBienvenidos\*(Aq
\&  #     expected: \*(AqHello\*(Aq
.Ve
.PP
\fI\f(CI\*(C`like\*(C'\fI\fR
.IX Subsection "like"
.PP
\fI\f(CI\*(C`unlike\*(C'\fI\fR
.IX Subsection "unlike"
.PP
.Vb 2
\&  $tx\->like( $xpath, qr/want/, $description );
\&  $tx\->unlike( $xpath, qr/dont_want/, $description );
.Ve
.PP
Similar to \f(CW\*(C`is()\*(C'\fR and \f(CW\*(C`isnt()\*(C'\fR, but these methods match the value returned
by the XPath expression against a regular expression.
.PP
.Vb 2
\&  $tx\->like( \*(Aq/html/head/title\*(Aq, qr/^Foobar Inc.: .+/, \*(AqTitle context\*(Aq );
\&  $tx\->unlike( \*(Aq/html/head/title\*(Aq, qr/Error/, \*(AqShould be no error in title\*(Aq );
.Ve
.PP
As with \f(CW\*(C`Test::More::like()\*(C'\fR, a failing test will yield a useful diagnostic
message, something like:
.PP
.Vb 4
\&  #   Failed test \*(AqTitle should, like, welcome\*(Aq
\&  #   at t/foo.t line 62.
\&  #                   \*(AqBye\*(Aq
\&  #     doesn\*(Aqt match \*(Aq(?\-xism:^Howdy$)\*(Aq
.Ve
.PP
\fI\f(CI\*(C`cmp_ok\*(C'\fI\fR
.IX Subsection "cmp_ok"
.PP
.Vb 1
\&  $tx\->cmp_ok( $xpath, $op, $want, $description );
.Ve
.PP
Like \f(CW\*(C`Test::More::cmp_ok()\*(C'\fR, this method allows you to compare the value
returned by an XPath expression to a value using any binary Perl operator.
.PP
.Vb 2
\&  $tx\->cmp_ok( \*(Aq/html/head/title\*(Aq, \*(Aqeq\*(Aq, \*(AqWelcome\*(Aq );
\&  $tx\->cmp_ok( \*(Aq//story[1]/@id\*(Aq, \*(Aq==\*(Aq, 1 );
.Ve
.PP
As with \f(CW\*(C`Test::More::cmp_ok()\*(C'\fR, a failing test will yield a useful diagnostic
message, something like:
.PP
.Vb 5
\&  #   Failed test
\&  #   at t/foo.t line 104.
\&  #     \*(Aq0\*(Aq
\&  #         &&
\&  #     \*(Aq1\*(Aq
.Ve
.SS "Accessors"
.IX Subsection "Accessors"
\fI\f(CI\*(C`node\*(C'\fI\fR
.IX Subsection "node"
.PP
.Vb 1
\&  my $node = $tx\->node;
.Ve
.PP
Returns the current context node. This will usually be the node for the entire
document, but in recursive tests run in code references passed to \f(CW\*(C`ok()\*(C'\fR, the
node will be one of the nodes selected for the test.
.PP
\fI\f(CI\*(C`xpc\*(C'\fI\fR
.IX Subsection "xpc"
.PP
Returns the XML::LibXML::XPathContext used to execute the XPath
expressions. It can be useful to access this object in order to create new
XPath functions to use in your tests. For example, say that you wanted to
define a \f(CW\*(C`grep()\*(C'\fR XPath function that returns true for a node value that
matches a regular expression. You can define one like so:
.PP
.Vb 8
\&  $tx\->xpc\->registerFunction( grep => sub {
\&      my ($nodelist, $regex) =  @_;
\&      my $result = XML::LibXML::NodeList\->new;
\&      for my $node ($nodelist\->get_nodelist) {
\&          $result\->push($node) if $node\->textContent =~ $regex;
\&      }
\&      return $result;
\&  } );
.Ve
.PP
You can then use \f(CW\*(C`grep()\*(C'\fR like any other XPath function to select only those
nodes with content matching a regular expression. This example makes sure that
there are \*(L"email\*(R" nodes under \*(L"author\*(R" nodes that end in \*(L"@example.com\*(R" or
\&\*(L"example.org\*(R":
.PP
.Vb 4
\&  $tx\->ok(
\&      \*(Aqgrep(//author/email, "@example[.](?:com|org)$")\*(Aq,
\&      \*(AqShould have example email\*(Aq
\&  );
.Ve
.SS "Utilities"
.IX Subsection "Utilities"
\fI\f(CI\*(C`find_value\*(C'\fI\fR
.IX Subsection "find_value"
.PP
.Vb 1
\&  my $val = $tx\->find_value($xpath);
.Ve
.PP
Returns the value returned by evaluation of the XPath expression against the
document relative to the current node. This is the method used internally to
fetch the value to be compared by \f(CW\*(C`is\*(C'\fR, \f(CW\*(C`isnt\*(C'\fR, \f(CW\*(C`like\*(C'\fR, \f(CW\*(C`unlike\*(C'\fR, and
\&\f(CW\*(C`cmp_ok\*(C'\fR. A simple example:
.PP
.Vb 1
\&  my $val = $tx\->find_value(\*(Aq/html/head/title\*(Aq);
.Ve
.SH "See Also"
.IX Header "See Also"
.IP "\(bu" 4
\&\s-1XML\s0 Path Language (XPath) Version 1.0 W3C Recommendation <http://www.w3.org/TR/xpath>.
.IP "\(bu" 4
W3Schools XPath Tutorial <https://www.w3schools.com/xml/xpath_intro.asp>.
.IP "\(bu" 4
XML::LibXML::XPathContext \- The XML::LibXML XPath evaluation library.
.IP "\(bu" 4
Test::XML::XPath \- Another library for testing XPath assertions using a
functional interface. Ships with Test::XML.
.IP "\(bu" 4
Test::HTML::Content \- Another module that that offers \f(CW\*(C`xpath_ok()\*(C'\fR and
\&\f(CW\*(C`no_xpath()\*(C'\fR test functions.
.SH "Support"
.IX Header "Support"
This module is stored in an open GitHub
repository <http://github.com/manwar/test-xpath/tree/>. Feel free to fork and
contribute!
.PP
Please file bug reports via GitHub
Issues <http://github.com/manwar/test-xpath/issues/> or by sending mail to
bug\-Test\-XPath@rt.cpan.org <mailto:bug-Test-XPath@rt.cpan.org>.
.SH "Author"
.IX Header "Author"
David E. Wheeler <david@kineticode.com>
.PP
Currently maintained by Mohammad S Anwar <mohammad.anwar@yahoo.com>
.SH "Copyright and License"
.IX Header "Copyright and License"
Copyright (c) 2009\-2010 David E. Wheeler. Some Rights Reserved.
.PP
This module is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.