NAME

XML::Assert - Asserts XPaths into an XML Document for correct values/matches

SYNOPSIS

    use XML::LibXML;
    use XML::Assert;

    my $xml = "<foo xmlns="urn:message"><bar baz="buzz">text</bar></foo>";
    my $xml_ns = "<foo xmlns="urn:message"><bar baz="buzz">text</bar></foo>";

    # get the DOM Document for each string
    my $doc = $parser->parse_string( $xml )->documentElement();
    my $doc_ns1 = $parser->parse_string( $xml_ns1 )->documentElement();

    # create an XML::Assert object
    my $xml_assert = XML::Assert->new();

    # assert that there is:
    # - only one <bar> element in the document
    # - the value of bar is 'text'
    # - the value of bar matches /^tex/
    # - the value of the baz attribute is buzz
    $xml_assert->assert_xpath_count($doc, '//bar', 1);
    $xml_assert->assert_xpath_value_match($doc, '//bar', 'text');
    $xml_assert->assert_xpath_value_match($doc, '//bar', qr{^tex});
    $xml_assert->assert_xpath_value_match($doc, '//bar[1]/@baz', 'buzz');

    # do the same with namespaces ...
    $xml_assert->xmlns({ 'ns' => 'urn:message' });
    $xml_assert->assert_xpath_count($doc, '//ns:bar', 1);
    # ...etc...

DESCRIPTION

This module allows you to test XPaths into an XML Document to check that their number or values are what you expect.

To test the number of nodes you expect to find, use the assert_xpath_count() method. To test the value of a node, use the assert_xpath_value_match(). This method can test against strings or regexes.

You can also text a value against a number of nodes by using the assert_xpath_values_match() method. This can check your value against any number of nodes.

Each of these assert methods throws an exception if they are false. Therefore, there are equivalent methods which do not die, but instead return a truth value. They are does_xpath_count(), does_xpath_value_match() and do_xpath_values_match().

Note: all of the *_match() methods use the smart match operator ~~ against node->text_value() to test for truth.

SUBROUTINES

Please note that all subroutines listed here that start with assert_* throw an error if the assertion is not true. You'd expect this.

Also note that there are a corresponding number of other methods for each assert_* method which either return true or false and do not throw an error. Please be sure to use the correct version for what you need.

assert_xpath_count($doc, $xpath, $count)

Checks that there are $count nodes in the $doc that are returned by the $xpath. Throws an error if this is untrue.

is_xpath_count($doc, $xpath, $count)

Calls the above method but catches any error and instead returns a truth value.

assert_xpath_value_match($doc, $xpath, $match)

Checks that $xpath returns only one node and that node's value matches $match.

does_xpath_value_match($doc, $xpath, $match)

Calls the above method but catches any error and instead returns a truth value.

assert_xpath_values_match($doc, $xpath, $match)

Checks that $xpath returns at least one node and that all nodes returned smart match against $match.

do_xpath_values_match($doc, $xpath, $match)

Calls the above method but catches any error and instead returns a truth value.

assert_attr_value_match($doc, $xpath, $attr, $match)

Checks that $xpath returns only one node, that node has an attr called $attr and that attr's value matches $match.

does_attr_value_match($doc, $xpath, $attr, $match)

Calls the above method but catches any error and instead returns a truth value.

assert_attr_values_match($doc, $xpath, $attr, $match)

Checks that $xpath returns at least one node, that every node has an attr called $attr and that those attr values smart match against $match.

do_attr_values_match($doc, $xpath, $attr, $match)

Calls the above method but catches any error and instead returns a truth value.

register_ns

Takes a hash containing ns => value pairs which are namesapces to register when Asserting into an XML document. If the correct namesapces are not registered, then it's likely that you XPath expressions won't match any of the desired nodes.

PROPERTIES

xmlns

A hashref of prefix => XMLNS, if you have namespaces in the XML document or in the XPaths.

EXPORTS

Nothing.

SEE ALSO

Test::XML::Assert, XML::Compare, XML::LibXML

AUTHOR

Andrew Chilton

Work

<andy at catalyst dot net dot nz>, http://www.catalyst.net.nz/

Personal

<andychilton at gmail dot com>, http://www.chilts.org/blog/

COPYRIGHT & LICENSE

This software development is sponsored and directed by New Zealand Registry Services, http://www.nzrs.net.nz/

The work is being carried out by Catalyst IT, http://www.catalyst.net.nz/

Copyright (c) 2009, NZ Registry Services. All Rights Reserved. This software may be used under the terms of the Artistic License 2.0. Note that this license is compatible with both the GNU GPL and Artistic licenses. A copy of this license is supplied with the distribution in the file COPYING.txt.