Test::XML::Count - Perl extension for testing element count at a certain depth

Test-XML-Count documentation Contained in the Test-XML-Count distribution.

Index

Code Index:

NAME

Top

Test::XML::Count - Perl extension for testing element count at a certain depth

SYNOPSIS

Top

 use Test::XML::Count tests => 8;

 my $xml = "<foo><bar/><bar/><bar/></foo>";

 # These will pass
 xml_node_count $xml, '/foo', 1;
 xml_node_count $xml, '/foo/bar', 3;
 xml_max_nodes $xml, '/foo', 1;
 xml_min_nodes $xml, '/foo/bar' 3;

 # These will fail
 xml_node_count $xml, '/foo', 10;
 xml_node_count $xml, '/article', 1; # need an article
 xml_min_nodes $xml, '/foo/bar', 10; # at least 10 <bar>'s in <foo>
 xml_max_nodes $xml, '/foo/bar', 1;  # at MOST 1 <bar> in <foo>

DESCRIPTION

Top

This test module allows you to check XML element counts. This is useful in testing applications which generate XML against known source data. At The New York Times, we use it during development to quickly verify that our RSS feeds meet very basic structural standards. For example, every news article needs to have exactly one of each of headline, byline, date and text, and at least one image.

This module fills a gap in Test::XML::Simple, which only has facilities to verify that an element exists (but not how many of it exist as direct siblings). This is a great way to validate the structure of your XML documents without doing any deep (SLOW) comparison. It also avoids having to hard code fragile element values that may change between tests or over time. Use Test::XML::Count in conjunction with your existing XML testing tools -- "SEE ALSO".

SHAMELESS PLUG

Top

This module was developed by the New York Times Company as an internal testing tool, and graciously donated to the Perl community. To show your support for our open source intiative you may send an email to mailto://open@nytimes.com and let us know how you are using this module.

Please visit http://open.nytimes.com, our open source blog to see what we are up to, http://code.nytimes.com to see some of our open projects and then check out http://nytimes.com for the latest news!

SUBROUTINES

Top

xml_node_count $xml, $xpath, $count, $name;

Test passes if the XML string in $xml contains $count of the element specified by the XPath in $xpath. Optionally name the test with $name.

xml_min_nodes $xml, $xpath, $count, $name;

Test passes if the XML string in $xml contains at least $count of the element specified by the XPath in $xpath. Optionally name the test with $name.

xml_max_nodes $xml, $xpath, $count, $name;

Test passes if the XML string in $xml contains at most $count of the element specified by the XPath in $xpath. Optionally name the test with $name.

EXPORTS

Top

Everything in "SUBROUTINES" by default, as expected.

SEE ALSO

Top

Test::XML

Test::More

Test::Builder

XML::LibXML

XPath Specification: http://www.w3.org/TR/xpath

XPath For Dummies: http://www.w3schools.com/xpath/xpath_syntax.asp

Our code blog: http://open.nytimes.com

AUTHOR

Top

Adam J Kaplan, <akaplan@nytimes dotcom<gt>

COPYRIGHT AND LICENSE

Top

Copyright (C) 2008 by Adam J Kaplan and The New York Times

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.

Test-XML-Count documentation Contained in the Test-XML-Count distribution. 
###################################################
# Text::XML::Count
#
# A module to help test element occurance counts
# in XML documents.
#
# Author: Adam Kaplan <akaplan@nytime dot com>
###################################################
# $Id$
###################################################
package Test::XML::Count;

use 5.006000;
use base 'Test::Builder::Module';
use strict;
use warnings;
use XML::LibXML;
use Test::Builder;
use Test::More;

require Exporter;

our @ISA = qw(Exporter);

our @EXPORT = qw(
	xml_node_count
	xml_min_nodes
	xml_max_nodes
);

our $VERSION = '0.02';

my $TEST = Test::Builder->new();
my $PARSER = XML::LibXML->new();
my $LAST_XML = '';
my $LAST_DOC;

sub import {
	my $class = shift @_;
	Test::XML::Count->export_to_level(1, $class);
	$TEST->exported_to(caller);
	$TEST->plan(@_);
}

sub _parse_and_get_nodelist {
	my $xml = shift or fail("XML string is not defined");
	my $xpath = shift or fail("XPath string is not defined");

	# Parsing is slow & probably not needed more than once per test file; Avoid.
	return $LAST_DOC if $xml eq $LAST_XML;
	# don't die if bad/unbalanced xml
	eval {$LAST_DOC = $PARSER->parse_string($xml)}; 
	return ($@) ? $TEST->fail($@) : $LAST_DOC->findnodes($xpath);
}

## Preloaded methods go here.

# boolean xml_node_count : xml string, xpath, number, test name
sub xml_node_count($$$;$) {
	my ($xml, $xpath, $count, $name) = @_;
	$TEST->ok (_parse_and_get_nodelist($xml, $xpath)->size() == $count, $name);
}

# boolean xml_min_nodes : xml string, xpath, number, test name
sub xml_min_nodes($$$;$) {
	my ($xml, $xpath, $count, $name) = @_;
	$TEST->ok (_parse_and_get_nodelist($xml, $xpath)->size() >= $count, $name);
}

# boolean xml_max_nodes : xml string, xpath, number, test name
sub xml_max_nodes($$$;$) {
	my ($xml, $xpath, $count, $name) = @_;
	$TEST->ok (_parse_and_get_nodelist($xml, $xpath)->size() <= $count, $name);
}

1;
__END__