Test::XPath(3pm)

🎀 Test::XPath 🎀

okay bestie, welcome to the Test::XPath(3pm) page — it lives in User Contributed Perl Documentation, and it's about testing your XML and HTML with XPath, which is genuinely one of the most underrated flexes in all of Perl. let's get into it 💅

---

✨ NAME ✨

Test::XPath — test XML and HTML content and structure with XPath expressions. that's it, that's the whole vibe 🦋

---

✨ SYNOPSIS ✨

here's the whole thing in action, no cap:

use Test::More tests => 5;
use Test::XPath;

my $xml = <<'XML';
<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( '/html/head', 'There should be a head' );
$tx->is( '/html/head/title', 'Hello', 'The title should be correct' );

# Recursing into a document:
my @css = qw(foo.css bar.css);
$tx->ok( '/html/head/style[@type="text/css"]', sub {
    my $css = shift @css;
    shift->is( './@src', $css, "Style src should be $css");
}, 'Should have style' );

# Better yet, use PerlX::MethodCallWithBlock:
use PerlX::MethodCallWithBlock;
my @css = qw(foo.css bar.css);
use PerlX::MethodCallWithBlock;
$tx->ok( '/html/head/style[@type="text/css"]', 'Should have style' ) {
    my $css = shift @css;
    shift->is( './@src', $css, "Style src should be $css");
};

# Or use CSS Selectors:
$tx = Test::XPath->new( xml => $xml, filter => 'css_selector' );
$tx->ok( '> html > head', 'There should be a head' );

like, look at that. recursive callbacks, method calls with blocks, CSS selectors instead of XPath — it's giving versatility 💖

---

✨ DESCRIPTION ✨

Use the absolute power of XPath expressions to validate the structure of your XML and HTML documents. that's the whole point, and it slaps. 🔥

🌈 About XPath 🌈

XPath is a powerful query language for XML documents. Test::XPath leans on the libxml2 implementation that XML::LibXML gives you. and libxml2? pretty much the canonical library for XML processing — it serves up an efficient and complete implementation of the XPath spec, periodt. 👑

XPath works by selecting nodes in an XML document. Nodes, generally speaking, line up with the elements (a.k.a. tags) defined in your XML, the text inside those elements, attribute values, and comments. the expressions you use to make those selections have this URI-like syntax, and the basics go like this:

• $nodename — selects all child nodes with the name.
• / — selects the root node.
• // — selects nodes from the current node that match the selection, regardless of where they are in the node hierarchy.
• . — selects the current node.
• .. — selects the parent of the current node.
• @ — selects attributes.

and some examples, because examples are the moment:

• head — selects all of the child nodes of the head element.
• /html — selects the root html element.
• body/p — selects all p elements that are children of the body element.
• //p — selects all p elements no matter where they are in the document.
• body//p — selects all p elements that are descendants of the body element, no matter where they appear under the body element.
• //@lang — selects all attributes named lang.

There are also useful predicates to select certain nodes. some examples:

• body//p[1] — select the first paragraph under the body element.
• body//p[last()] — select the last paragraph under the body element.
• //script[@src] — select all script nodes that have a src attribute.
• //script[@src='foo.js'] — select all script nodes that have a src attribute set to foo.js.
• //img[@height > 400] — select all img nodes with a height attribute greater than 400.
• head/* — select all child nodes below the head node.
• p[@*] — select all p nodes that have any attribute.
• count(//p) — select a count of all p nodes in the document.
• contains(//title, "Welcome") — select true if the title node contains the string Welcome, and false if it does not.

There are a bunch of core functions in XPath. on top of the last() and count() examples up there, there are functions for node sets, booleans, numbers, and strings. go read the XPath 1.0 W3C Recommendation at http://www.w3.org/TR/xpath for thorough (and honestly quite readable) documentation of XPath support, including syntax and the core functions. and the W3Schools tutorial at http://www.w3schools.com/Xpath/default.asp gives you a nice overview of XPath. iykyk 📚✨

🌸 Testing HTML 🌸

if you want to use XPath to test the content and structure of an HTML document, bestie, be sure to pass the is_html option to new(), like so:

my $tx = Test::XPath->new( xml => $html, is_html => 1 );

Test::XPath will then use XML::LibXML's HTML parser to parse the document, rather than its XML parser. the upshot? you won't have to worry about namespace prefixes, and XML::LibXML won't try to fetch any DTD specified in the DOCTYPE section of your HTML. two problems, gone, no cap. 🙈

---

✨ Class Interface ✨

💜 Constructor 💜

new

my $tx = Test::XPath->new( xml => $xml );

Creates and returns an XML::XPath object. this object is your little main character — you use it to run XPath tests on the XML you passed in. here are the supported parameters:

• xml — the XML to be parsed and tested. Required unless the file or doc option is passed.

xml => '<foo><bar>hey</bar></foo>',

• file — name of a file containing the XML to be parsed and tested. Required unless the xml or doc option is passed.

file => 'rss.xml',

• doc — an XML::LibXML document object. Required unless the xml or file option is passed.

doc => XML::LibXML->new->parse_file($xml_file),

• is_html — if the XML you're testing is actually HTML, pass this option a true value and XML::LibXML's HTML parser will be used instead of the XML parser. this is especially useful if your HTML has a DOCTYPE declaration or an XML namespace (xmlns attribute) and you don't want the parser grabbing the DTD over the Internet and you don't want to mess with a namespace prefix in your XPath expressions.

is_html => 1,

• xmlns — set up prefixes for XML namespaces. Required if your XML uses namespaces and you want to write reasonable XPath expressions.

xmlns => {
    x => 'http://www.w3.org/1999/xhtml',
    a => 'http://www.w3.org/2007/app',
},

• options — optional hash reference of XML::LibXML::Parser options, such as validation, recover, suppress_errors, and no_network. these can be useful for tweaking the behavior of the parser.

options => { recover_silently => 1, no_network => 1 },

• filter — 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 lets you transform XPath expressions if, for example, you use a custom XPath syntax that's more concise than XPath.

filter => 'css_selector',
filter => sub { my $xpath = shift; },

There is currently only one built-in filter, css_selector. so if you pass

filter => 'css_selector',

Then any paths passed to ok(), is(), etc., will be passed through HTML::Selector::XPath. this allows you to use CSS selector syntax, which can be more compact for simple expressions. for example, this CSS selector:

$tx->is('div#content div.article h1', '...')

Is equivalent to this XPath expression:

$tx->is('//div[@id="content"]//div[@class="article"]//h1', '...')

🦋 Instance Interface 🦋

✨ Assertions ✨

ok — the moment of truth 💅

$tx->ok( $xpath, $description )
$tx->ok( $xpath, $coderef, $description )

Okay so this one tests that running an XPath expression against the XML document gives back a true value. If the XPath expression finds no nodes, the result is gonna be false, no cap. And if it does find a value, that value has to be true in the Perl sense. That's it, that's the vibe check. 💖

$tx->ok( '//foo/bar', 'Should have bar element under foo element' );
$tx->ok( 'contains(//title, "Welcome")', 'Title should "Welcome"' );

But wait — you can also run recursive tests against your document by passing a code reference as the second argument to ok(). Once that first selection is done, every selected node gets assigned to the node attribute, and the XML::XPath object gets passed to the code reference. So like, say you wanted to test for the presence of story elements in your doc and check that each one had an incremented id attribute — you'd do something like this:

my $i = 0;
$tx->ok( '//assets/story', sub {
    shift->is('./@id', ++$i, "ID should be $i in story $i");
}, 'Should have story elements' );

And even better, use PerlX::MethodCallWithBlock to pass a block to the method instead of a code reference — it's giving main character energy fr:

use PerlX::MethodCallWithBlock;
my $i = 0;
$tx->ok( '//assets/story', 'Should have story elements' ) {
    shift->is('./@id', ++$i, "ID should be $i in story $i");
};

For convenience, the XML::XPath object is also assigned to $_ for the whole duration of the call to the code reference. Either way, you can call ok() and pass code references anywhere in the hierarchy. For example, to make sure 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:

$tx->ok( '/feed/entry', sub {
    $_->ok( './title', 'Should have a title' );
    $_->ok( './author', sub {
        $_->is( './name',  'Mark Pilgrim',        'Mark should be author' );
        $_->is( './uri',   'http://example.org/', 'URI should be correct' );
        $_->is( './email', 'f8dy@example.com',    'Email should be right' );
    }, 'Should have author elements' );
}, 'Should have entry elments' );

---

not_ok — the reverse, iconic 🙈

$tx->not_ok( $xpath, $description )

This is the reverse of the non-recursive ok(), bestie. The test succeeds if the XPath expression matches no part of the document at all. Zero. Nada. 🎀

$tx->not_ok( '//foo/bar[@id=0]', 'Should have no bar elements with Id 0' );

is

isnt

$tx->is( $xpath, $want, $description );
$tx->isnt( $xpath, $dont_want, $description );

is() and isnt() compare the value returned by evaluation of the XPath expression against the document to a value, using eq and ne respectively. Classic. 🌸

$tx->is( '/html/head/title', 'Welcome', 'Title should be welcoming' );
$tx->isnt( '/html/head/link/@type', 'hello', 'Link type should not' );

As with Test::More::ok(), a failing test will yield a useful diagnostic message, something like:

#   Failed test 'Title should be welcoming'
#   at t/foo.t line 47.
#          got: 'Bienvenidos'
#     expected: 'Hello'

like

unlike

$tx->like( $xpath, qr/want/, $description );
$tx->unlike( $xpath, qr/dont_want/, $description );

Similar to is() and isnt(), but these methods match the value returned by the XPath expression against a regular expression instead. Regex girlies rise up 💅

$tx->like( '/html/head/title', qr/^Foobar Inc.: .+/, 'Title context' );
$tx->unlike( '/html/head/title', qr/Error/, 'Should be no error in title' );

As with Test::More::like(), a failing test will yield a useful diagnostic message, something like:

#   Failed test 'Title should, like, welcome'
#   at t/foo.t line 62.
#                   'Bye'
#     doesn't match '(?-xism:^Howdy$)'

cmp_ok — bring your own operator 🫶

$tx->cmp_ok( $xpath, $op, $want, $description );

Like Test::More::cmp_ok(), this method lets you compare the value returned by an XPath expression to a value using any binary Perl operator. Go off. ⭐

$tx->cmp_ok( '/html/head/title', 'eq', 'Welcome' );
$tx->cmp_ok( '//story[1]/@id', '==', 1 );

As with Test::More::cmp_ok(), a failing test will yield a useful diagnostic message, something like:

#   Failed test
#   at t/foo.t line 104.
#     '0'
#         &&
#     '1'

---

🎀 Accessors 🎀

node

my $node = $tx->node;

Returns the current context node. Usually this is the node for the entire document, but in recursive tests run in code references passed to ok(), the node will be one of the nodes selected for the test. iykyk 💖

xpc

Returns the XML::LibXML::XPathContext used to execute the XPath expressions. It can be super useful to grab this object so you can create new XPath functions to use in your tests. Like, say you wanted to define a grep() XPath function that returns true for a node value matching a regular expression — you can define one like so:

$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;
} );

Then you can use grep() like literally any other XPath function to select only those nodes whose content matches a regular expression. This example makes sure that there are email nodes under author nodes that end in @example.com or example.org:

$tx->ok(
    'grep(//author/email, "@example[.](?:com|org)$")',
    'Should have example email'
);

🧚 Utilities 🧚

find_value

my $val = $tx->find_value($xpath);

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 that gets compared by is, isnt, like, unlike, and cmp_ok. Simple lil example: ✨

my $val = $tx->find_value('/html/head/title');

---

🌈 See Also 🌈

• XML Path Language (XPath) Version 1.0 W3C Recommendation <http://www.w3.org/TR/xpath>.
• W3Schools XPath Tutorial <https://www.w3schools.com/xml/xpath_intro.asp>.
• XML::LibXML::XPathContext - The XML::LibXML XPath evaluation library.
• Test::XML::XPath - Another library for testing XPath assertions using a functional interface. Ships with Test::XML.
• Test::HTML::Content - Another module that that offers xpath_ok() and no_xpath() test functions.

💜 Support 💜

This module is stored in an open GitHub repository <http://github.com/manwar/test-xpath/tree/>. Feel free to fork and contribute! Fr fr, the door is open 🫶

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

👑 Author 👑

David E. Wheeler <david@kineticode.com>

Currently maintained by Mohammad S Anwar <mohammad.anwar@yahoo.com>

⭐ Copyright and License ⭐

Copyright (c) 2009-2010 David E. Wheeler. Some Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

And that's a wrap, bestie!! 🎉 This was Test::XPath(3pm) as shipped with perl v5.34.0, dated 2022-08-19. Go write some slay XPath assertions, you absolute icon 💖✨🦋