Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Test::XPath(3)	      User Contributed Perl Documentation	Test::XPath(3)

       Test::XPath - Test XML and HTML content and structure with XPath

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

	 my $xml = <<'XML';
	     <style type="text/css" src="foo.css"></style>
	     <style type="text/css" src="bar.css"></style>
	     <h1>Welcome to my lair.</h1>

	 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' );

       Use the power of	XPath expressions to validate the structure of your
       XML and HTML documents.

   About XPath
       XPath is	a powerful query language for XML documents. Test::XPath
       relies on the libxml2 implementation provided by	XML::LibXML. libxml2
       -- pretty much the canonical library for	XML processing -- provides an
       efficient and complete implementation of	the XPath spec.

       XPath works by selecting	nodes in an XML	document. Nodes, in general,
       correspond to the elements (a.k.a. tags)	defined	in the XML, text
       within those elements, attribute	values,	and comments. The expressions
       for making such selections use a	URI-like syntax, the basics of which

	   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:

	   Selects all of the child nodes of the "head"	element.

	   Selects the root "html" element.

	   Selects all "p" elements that are children of the "body" element.

	   Selects all "p" elements no matter where they are in	the document.

	   Selects all "p" elements that are descendants of the	"body"
	   element, no matter where they appear	under the "body" element.

	   Selects all attributes named	"lang".

       There are also useful predicates	to select certain nodes. Some

	   Select the first paragraph under the	body element.

	   Select the last paragraph under the body element.

	   Select all "script" nodes that have a "src" attribute.

	   Select all "script" nodes that have a "src" attribute set to

       "//img[@height >	400]"
	   Select all "img" nodes with a height	attribute greater than 400.

	   Select all child nodes below	the "head" node.

	   Select all "p" nodes	that have any attribute.

	   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. In	addition to the
       ("last()" and "count()")	examples above,	there are functions for	node
       sets, booleans, numbers,	and strings. See the XPath 1.0 W3C
       Recommendation <>, for	thorough (and quite
       readable) documentation of XPath	support, including syntax and the core
       functions. The W3Schools	tutorial
       <> provides a nice overview
       of XPath.

   Testing HTML
       If you want to use XPath	to test	the content and	structure of an	HTML
       document, 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	is that	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.

Class Interface

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

       Creates and returns an XML::XPath object. This object can be used to
       run XPath tests on the XML passed to it.	The supported parameters are:

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

	   The XML to be parsed	and tested. Required unless the	"file" or
	   "doc" option	is passed.

	     file => 'rss.xml',

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

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

	   An XML::LibXML document object. Required unless the "xml" or	"file"
	   option is passed.

	     is_html =>	1,

	   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.

	     xmlns => {
		 x => '',
		 a => '',

	   Set up prefixes for XML namespaces. Required	if your	XML uses
	   namespaces and you want to write reasonable XPath expressions.

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

	   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.

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

	   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.

	   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

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

       Test that an XPath expression evaluated against the XML 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).

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

       You can also run	recursive tests	against	your document by passing a
       code reference as the second argument to	"ok()".	Once the initial
       selection has been completed, each selected node	will be	assigned to
       the "node" attribute and	the XML::XPath object passed to	the code
       reference. For example, if you wanted to	test for the presence of
       "story" elements	in your	document, and to test that each	such element
       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' );

       Even better, use	PerlX::MethodCallWithBlock to pass a block to the
       method instead of a code	reference:

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

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


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

       The reverse of the non-recursive	"ok()",	the test succeeds if the XPath
       expression matches no part of the document.

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



	 $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",

	 $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'



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

	 $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$)'


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

       Like "Test::More::cmp_ok()", this method	allows you to compare the
       value returned by an XPath expression to	a value	using any binary Perl

	 $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'


	 my $node = $tx->node;

       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 "ok()", the node will	be one of the nodes selected for the test.


       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 "grep()" XPath function that returns true for	a node
       value that matches 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;
	 } );

       You can then use	"grep()" like any other	XPath function to select only
       those nodes with	content	matching a regular expression. This example
       makes sure that there are "email" nodes under "author" nodes that end
       in "" or "":

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


	 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 to be	compared by "is", "isnt",
       "like", "unlike", and "cmp_ok". A simple	example:

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

See Also
       o   XML Path Language (XPath) Version 1.0 W3C Recommendation

       o   W3Schools XPath Tutorial

       o   XML::LibXML::XPathContext - The XML::LibXML XPath evaluation

       o   Test::XML::XPath - Another library for testing XPath	assertions
	   using a functional interface. Ships with Test::XML.

       o   Test::HTML::Content - Another module	that that offers "xpath_ok()"
	   and "no_xpath()" test functions.

       This module is stored in	an open	GitHub repository
       <>. Feel free to fork and

       Please file bug reports via GitHub Issues
       <> or	by sending mail	to <>.

       David E.	Wheeler	<>

       Currently maintained by Mohammad	S Anwar	<>

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.

perl v5.32.0			  2020-08-10			Test::XPath(3)

Name | Synopsis | Description | Class Interface | Instance Interface | See Also | Support | Author | Copyright and License

Want to link to this manual page? Use this URL:

home | help