blib/lib/Test/XML/Easy.pm

filter: Statementstmt 94.3% 217 / 230 Branchbran 89.5% 86 / 96 Conditioncond 89.2% 25 / 28 MC/DCmcdc 81.2% 13 / 16 Subroutinesub 100% 16 / 16 Podpod 100% 4 / 4 totaltotal 92.5% 361 / 390 CC 61 SCAR 31.0
CC
61
Cov
93%
_is_xml
39.5
is_xml
12.0
isnt_xml
9.0
CRAP 22.3
↑ Summary
1 package Test::XML::Easy;
2  
3 11 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 11 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 11 ▶use vars qw(@EXPORT @ISA);
Subroutine BEGIN: called CC=1 SCAR=0.0
7 11 ▶use Exporter;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 11 @ISA = qw(Exporter);
9  
10 11 our $VERSION = '0.01';
11  
12 11 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 11 ▶use XML::Easy::Text qw(xml10_read_document xml10_write_document);
Subroutine BEGIN: called CC=1 SCAR=0.0
15 11 ▶use XML::Easy::Classify qw(is_xml_element);
Subroutine BEGIN: called CC=1 SCAR=0.0
16 11 ▶use XML::Easy::Syntax qw($xml10_s_rx);
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 11 ▶use Test::Builder;
Subroutine BEGIN: called CC=1 SCAR=0.0
19 11 my $tester = Test::Builder->new();
20  
21 =head1 NAME
22  
23 Test::XML::Easy - test XML with XML::Easy
24  
25 =head1 SYNOPSIS
26  
27 use Test::More tests => 2;
28 use Test::XML::Easy;
29  
30 is_xml $some_xml, <<'ENDOFXML', "a test";
31 <?xml version="1.0" encoding="latin-1">
32 <foo>
33 <bar/>
34 <baz buzz="bizz">fuzz</baz>
35 </foo>
36 ENDOFXML
37  
38 is_xml $some_xml, <<'ENDOFXML', { ignore_whitespace => 1, description => "my test" };
39 <foo>
40 <bar/>
41 <baz buzz="bizz">fuzz</baz>
42 </foo>
43 ENDOFXML
44  
45 isnt_xml $some_xml, $some_xml_it_must_not_be;
46  
47 is_well_formed_xml $some_xml;
48  
49 =head1 DESCRIPTION
50  
51 A simple testing tool, with only pure Perl dependancies, that checks if
52 two XML documents are "the same". In particular this module will check if
53 the documents schemantically equal as defined by the XML 1.0 specification
54 (i.e. that the two documents would construct the same DOM
55 model when parsed, so things like character sets and if you've used two tags
56 or a self closing tags aren't important.)
57  
58 This modules is a strict superset of B<Test::XML>'s interface, meaning if you
59 were using that module to check if two identical documents were the same then
60 this module should function as a drop in replacement. Be warned, however,
61 that this module by default is a lot stricter about how the XML documents
62 are allowed to differ.
63  
64 =head2 Functions
65  
66 This module, by default, exports a number of functions into your namespace.
67  
68 =over
69  
70 =item is_xml($xml_to_test, $expected_xml[, $options_hashref])
71  
72 Tests that the passed XML is "the same" as the expected XML.
73  
74 XML can be passed into this function in one of two ways; Either you can
75 provide a string (which the function will parse for you) or you can pass in
76 B<XML::Easy::Element> objects that you've constructed yourself somehow.
77  
78 This funtion takes several options as the third argument. These can be
79 passed in as a hashref:
80  
81 =over
82  
83 =item description
84  
85 The name of the test that will be used in constructing the C<ok> / C<not ok>
86 test output.
87  
88 =item ignore_whitespace
89  
90 Ignore many whitespace differences in text nodes. Currently
91 this has the same effect as turning on C<ignore_surrounding_whitespace>
92 and C<ignore_different_whitespace>.
93  
94 =item ignore_surrounding_whitespace
95  
96 Ignore differences in leading and trailing whitespace
97 between elements. This means that
98  
99 <p>foo bar baz</p>
100  
101 Is considered the same as
102  
103 <p>
104 foo bar baz
105 </p>
106  
107 And even
108  
109 <p>
110 this is my cat:<img src="http://myfo.to/KsSc.jpg" />
111 </p>
112  
113 Is considered the same as:
114  
115 <p>
116 this is my cat: <img src="http://myfo.to/KsSc.jpg" />
117 </p>
118  
119 Even though, to a web-browser, that extra space is significant whitespace
120 and the two documents would be renderd differently.
121  
122 However, as comments are completely ignored (we treat them as if they were
123 never even in the document) the following:
124  
125 <p>foo<!-- a comment -->bar</p>
126  
127 would be considered different to
128  
129 <p>
130 foo
131 <!-- a comment -->
132 bar
133 </p>
134  
135 As it's the same as comparing the string
136  
137 "foobar"
138  
139 And:
140  
141 "foo
142
143 bar"
144  
145 The same is true for processing instructions and DTD declarations.
146  
147 =item ignore_leading_whitespace
148  
149 The same as C<ignore_surrounding_whitespace> but only ignore
150 the whitespace immediately after an element start or end tag not
151 immedately before.
152  
153 =item ignore_trailing_whitespace
154  
155 The same as C<ignore_surrounding_whitespace> but only ignore
156 the whitespace immediately before an element start or end tag not
157 immedately after.
158  
159 =item ignore_different_whitespace
160  
161 If set to a true value ignores differences in what characters
162 make up whitespace in text nodes. In other words, this option
163 makes the comparison only care that wherever there's whitespace
164 in the expected XML there's any whitespace in the actual XML
165 at all, not what that whitespace is made up of.
166  
167 It means the following
168  
169 <p>
170 foo bar baz
171 </p>
172  
173 Is the same as
174  
175 <p>
176 foo
177 bar
178 baz
179 </p>
180  
181 But not the same as
182  
183 <p>
184 foobarbaz
185 </p>
186  
187 This setting has no effect on attribute comparisons.
188  
189 =item verbose
190  
191 If true, print obsessive amounts of debug info out while
192 checking things
193  
194 =item show_xml
195  
196 This prints out in the diagnostic messages the expected and
197 actual XML on failure.
198  
199 =back
200  
201 If a third argument is passed to this function and that argument
202 is not a hashref then it will be assumed that this argument is
203 the the description as passed above. i.e.
204  
205 is_xml $xml, $expected, "my test";
206  
207 is the same as
208  
209 is_xml $xml, $expected, { description => "my test" };
210  
211 =cut
212  
213 57 ▶sub is_xml($$;$) {
Subroutine is_xml: called CC=12 SCAR=24.8
Pod documented
214 57 my $got = shift;
215 57 my $expected = shift;
216  
217 57 ▶ unless (defined $expected) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $expected) 2 55 57
218 2 croak("expected argument must be defined");
219 }
220  
221 # munge the options
222  
223 55 my $got_original = $got;
224 55 my $expected_original = $expected;
225  
226 55 my $options = shift;
227 55 ▶ $options = { description => $options } unless ref $options eq "HASH";
Branch: 1 branch
BranchTrueFalseTotal
unless ref $options eq "HASH" 7 48 55
228 55 ▶ $options = { %{$options}, description => "xml test" } unless defined $options->{description};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $options->{"description"} 42 13 55
229 55 ▶ unless (is_xml_element($expected)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (&is_xml_element($expected)) 54 1 55
230 # throws an exception if there isn't a problem.
231 54 $expected = eval { xml10_read_document($expected) };
232 54 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 2 52 54
233 2 croak "Couldn't parse expected XML document: $@";
234 }
235 }
236  
237 # convert into something useful if needed
238 53 ▶ unless (is_xml_element($got)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (&is_xml_element($got)) 51 2 53
239 51 my $parsed = eval { xml10_read_document($got) };
240 51 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 4 47 51
241 4 $tester->ok(0, $options->{description});
242 4 $tester->diag("Couldn't parse submitted XML document:");
243 4 $tester->diag(" $@");
244 4 return;
245 }
246  
247 47 $got = $parsed;
248 }
249  
250 49 ▶ if(_is_xml($got,$expected,$options,"", {})) {
Branch: 1 branch
BranchTrueFalseTotal
if (_is_xml($got, $expected, $options, "", scalar {})) 23 26 49
251 23 $tester->ok(1,$options->{description});
252 23 return 1;
253 }
254  
255 26 ▶ if ($options->{show_xml}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($options->{"show_xml"}) 3 23 26
256 3 $tester->diag("The XML that we expected was:");
257 3 ▶ if (is_xml_element($expected_original))
Branch: 1 branch
BranchTrueFalseTotal
if (&is_xml_element($expected_original)) { } 1 2 3
258 1 { $tester->diag(xml10_write_document($expected_original)) }
259 else
260 2 { $tester->diag($expected_original) }
261  
262 3 $tester->diag("The XML that we received was:");
263 3 ▶ if (is_xml_element($got_original))
Branch: 1 branch
BranchTrueFalseTotal
if (&is_xml_element($got_original)) { } 1 2 3
264 1 { $tester->diag(xml10_write_document($got_original)) }
265 else
266 2 { $tester->diag($got_original) }
267 }
268  
269 26 return;
270 }
271 11 push @EXPORT, "is_xml";
272  
273 75 ▶sub _is_xml {
Subroutine _is_xml: called CC=36 SCAR=36.8
274 75 my $got = shift;
275 75 my $expected = shift;
276 75 my $options = shift;
277  
278 # this is the path
279 75 my $path = shift;
280  
281 # the index is used to keep track of how many of a particular
282 # typename of a particular element we've seen as previous siblings
283 # of the node that just got in. It's a hashref with type_name and
284 # the index.
285 75 my $index = shift;
286  
287 # change where the errors are reported from
288 75 local $Test::Builder::Level = $Test::Builder::Level + 1;
289  
290 # work out the details of the node we're looking at
291 # nb add one to the index because xpath is weirdly 1-index
292 # not 0-indexed like most other modern languages
293 75 my $got_name = $got->type_name();
294 75 ▶ my $got_index = ($index->{ $got_name } || 0) + 1;
Condition100%2/2
$index->{$got_name} || 0
l!l
966
MC/DC100%1/1
$index->{$got_name} || 0
$index->{$got_name}
Truth table100%2/2
A
A= $index->{$got_name}
Aresult
11
00
295  
296 ### check if we've got a node to compare to
297  
298 75 ▶ unless ($expected) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($expected) 0 75 75
299 0 $tester->ok(0, $options->{description});
300 0 $tester->diag("Element '$path/$got_name\[$got_index]' was not expected");
301 0 return;
302 }
303  
304 ### check the node name
305  
306 # work out the details of the node we're comparing with
307 75 my $expected_name = $expected->type_name();
308 75 ▶ my $expected_index = ($index->{ $expected_name } || 0) + 1;
Condition100%2/2
$index->{$expected_name} || 0
l!l
966
MC/DC100%1/1
$index->{$expected_name} || 0
$index->{$expected_name}
Truth table100%2/2
A
A= $index->{$expected_name}
Aresult
11
00
309  
310 # alter the index hashref to record we've seen another node
311 # of this name
312 75 $index->{$got_name}++;
313  
314 75 ▶ $tester->diag("comparing '$path/$got_name\[$expected_index]' to '$path/$expected_name\[$expected_index]'...") if $options->{verbose};
Branch: 1 branch
BranchTrueFalseTotal
if $options->{"verbose"} 0 75 75
315  
316 75 ▶ if ($got_name ne $expected_name) {
Branch: 1 branch
BranchTrueFalseTotal
if ($got_name ne $expected_name) 4 71 75
317 4 $tester->ok(0, $options->{description});
318 4 $tester->diag("Element '$path/$got_name\[$got_index]' does not match '$path/$expected_name\[$expected_index]'");
319 4 return;
320 }
321 71 ▶ $tester->diag("...matched name") if $options->{verbose};
Branch: 1 branch
BranchTrueFalseTotal
if $options->{"verbose"} 0 71 71
322  
323 ### check the attributes
324  
325 # we're not looking at decendents, so burn the path of
326 # this node into the path we got passed in
327 71 $path .= "/$got_name\[$got_index]";
328  
329 # XML::Easy returns read only data structures
330 # we want to modify these to keep track of what
331 # we've processed, so we need to copy them
332 71 my %got_attr = %{ $got->attributes };
333 71 my $expected_attr = $expected->attributes;
334  
335 71 foreach my $attr (keys %{ $expected_attr }) {
336 6 ▶ $tester->diag("checking attribute '$path/\@$attr'...") if $options->{verbose};
Branch: 1 branch
BranchTrueFalseTotal
if $options->{"verbose"} 0 6 6
337  
338 6 ▶ if (!exists($got_attr{$attr})) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $got_attr{$attr}) 1 5 6
339 1 $tester->ok(0, $options->{description});
340 1 $tester->diag("expected attribute '$path/\@$attr' not found");
341 1 return;
342 }
343 5 ▶ $tester->diag("...found attribute") if $options->{verbose};
Branch: 1 branch
BranchTrueFalseTotal
if $options->{"verbose"} 0 5 5
344  
345 5 my $expected_string = $expected_attr->{$attr};
346 5 my $got_string = delete $got_attr{$attr};
347  
348 5 ▶ if ($expected_string ne $got_string) {
Branch: 1 branch
BranchTrueFalseTotal
if ($expected_string ne $got_string) 1 4 5
349 1 $tester->ok(0, $options->{description});
350 1 $tester->diag("attribute value for '$path/\@$attr' didn't match");
351 1 $tester->diag("found value:\n");
352 1 $tester->diag(" '$got_string'\n");
353 1 $tester->diag("expected value:\n");
354 1 $tester->diag(" '$expected_string'\n");
355 1 return;
356 }
357 4 ▶ $tester->diag("...the attribute contents matched") if $options->{verbose};
Branch: 1 branch
BranchTrueFalseTotal
if $options->{"verbose"} 0 4 4
358 }
359 69 ▶ if (keys %got_attr) {
Branch: 1 branch
BranchTrueFalseTotal
if (keys %got_attr) 2 67 69
360 2 $tester->ok(0, $options->{description});
361 2 ▶ $tester->diag("found extra unexpected attribute".(keys %got_attr>1 ? "s":"").":");
Branch: 1 branch
BranchTrueFalseTotal
keys %got_attr > 1 ? : 1 1 2
362 2 $tester->diag(" '$path/\@$_'") foreach sort keys %got_attr;
363 2 return;
364 }
365 67 ▶ $tester->diag("the attributes all matched") if $options->{verbose};
Branch: 1 branch
BranchTrueFalseTotal
if $options->{"verbose"} 0 67 67
366  
367 ### check the child nodes
368  
369 # create a new index to pass to our children distint from
370 # the index that was passed in to us (as that one was created
371 # by our parent for me and my siblings)
372 67 my $child_index = {};
373  
374 # grab the child text...element...text...element...text...
375 67 my $got_content = $got->content;
376 67 my $expected_content = $expected->content;
377  
378 # step though the text/elements
379 # nb this loop works in steps of two; The other $i++
380 # is half way through the loop below
381 67 ▶ for (my $i = 0; $i < @{$got_content}; $i++) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i < @{$got_content;}) 86 0 86
382  
383 ### check the text node
384  
385 # extract the text from the object
386 86 my $got_text = $got_content->[ $i ];
387 86 my $expected_text = $expected_content->[ $i ];
388 86 my $comp_got_text = $got_text;
389 86 my $comp_expected_text = $expected_text;
390  
391 86 ▶ if ($options->{ignore_whitespace} || $options->{ignore_leading_whitespace} || $options->{ignore_surrounding_whitespace}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($options->{"ignore_whitespace"} or $options->{"ignore_leading_whitespace"} or $options->{"ignore_surrounding_whitespace"}) 10 76 86
Condition83%5/6
$options->{"ignore_whitespace"} or $options->{"ignore_leading_whitespace"} or $options->{"ignore_surrounding_whitespace"}
l!l&&r!l&&!r
10076
$options->{"ignore_whitespace"} or $options->{"ignore_leading_whitespace"}
l!l&&r!l&&!r
7376
MC/DC66%2/3
$options->{"ignore_whitespace"} or $options->{"ignore_leading_whitespace"} or $options->{"ignore_surrounding_whitespace"}
$options->{"ignore_whitespace"} $options->{"ignore_leading_whitespace"} $options->{"ignore_surrounding_whitespace"}
Truth table75%3/4
A or B or C
A= $options->{"ignore_whitespace"}B= $options->{"ignore_leading_whitespace"}C= $options->{"ignore_surrounding_whitespace"}
ABCresult
1XX1
01X1
0011
0000
392 10 $comp_got_text =~ s/ \A (?:$xml10_s_rx)* //x;
393 10 $comp_expected_text =~ s/ \A (?:$xml10_s_rx)* //x;
394 }
395  
396 86 ▶ if ($options->{ignore_whitespace} || $options->{ignore_trailing_whitespace} || $options->{ignore_surrounding_whitespace}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($options->{"ignore_whitespace"} or $options->{"ignore_trailing_whitespace"} or $options->{"ignore_surrounding_whitespace"}) 10 76 86
Condition83%5/6
$options->{"ignore_whitespace"} or $options->{"ignore_trailing_whitespace"} or $options->{"ignore_surrounding_whitespace"}
l!l&&r!l&&!r
10076
$options->{"ignore_whitespace"} or $options->{"ignore_trailing_whitespace"}
l!l&&r!l&&!r
7376
MC/DC66%2/3
$options->{"ignore_whitespace"} or $options->{"ignore_trailing_whitespace"} or $options->{"ignore_surrounding_whitespace"}
$options->{"ignore_whitespace"} $options->{"ignore_trailing_whitespace"} $options->{"ignore_surrounding_whitespace"}
Truth table75%3/4
A or B or C
A= $options->{"ignore_whitespace"}B= $options->{"ignore_trailing_whitespace"}C= $options->{"ignore_surrounding_whitespace"}
ABCresult
1XX1
01X1
0011
0000
397 10 $comp_got_text =~ s/ (?:$xml10_s_rx)* \z//x;
398 10 $comp_expected_text =~ s/ (?:$xml10_s_rx)* \z//x;
399 }
400  
401 86 ▶ if ($options->{ignore_whitespace} || $options->{ignore_different_whitespace}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($options->{"ignore_whitespace"} or $options->{"ignore_different_whitespace"}) 8 78 86
Condition100%3/3
$options->{"ignore_whitespace"} or $options->{"ignore_different_whitespace"}
l!l&&r!l&&!r
7178
MC/DC100%2/2
$options->{"ignore_whitespace"} or $options->{"ignore_different_whitespace"}
$options->{"ignore_whitespace"} $options->{"ignore_different_whitespace"}
Truth table100%3/3
A or B
A= $options->{"ignore_whitespace"}B= $options->{"ignore_different_whitespace"}
ABresult
1X1
011
000
402 8 $comp_got_text =~ s/ (?:$xml10_s_rx)+ / /gx;
403 8 $comp_expected_text =~ s/ (?:$xml10_s_rx)+ / /gx;
404 }
405  
406 86 ▶ if ($comp_got_text ne $comp_expected_text) {
Branch: 1 branch
BranchTrueFalseTotal
if ($comp_got_text ne $comp_expected_text) 18 68 86
407  
408 18 $tester->ok(0, $options->{description});
409  
410 # I don't like these error message not being specific with xpath but as
411 # far as I know there's no easy way to express in xpath the text immediatly following
412 # a particular element. The best I could come up with was this mouthful:
413 # "$path/following-sibling::text()[ previous-sibling::*[1] == $path ]"
414  
415 18 ▶ if ($i == 0) {
Branch: 2 branches
BranchTrueFalseTotal
if ($i == 0) { } 13 5 18
elsif ($i == @{$got_content;} - 1 and $i == @{$expected_content;} - 1) { } 1 4 5
416 13 ▶ if (@{ $got_content } == 1 && @{ $expected_content } == 1) {
Branch: 1 branch
BranchTrueFalseTotal
if (@{$got_content;} == 1 and @{$expected_content;} == 1) { } 10 3 13
Condition100%3/3
@{$got_content;} == 1 and @{$expected_content;} == 1
!ll&&!rl&&r
2110
MC/DC100%2/2
@{$got_content;} == 1 and @{$expected_content;} == 1
@{$got_content;} == 1 @{$expected_content;} == 1
Truth table100%3/3
A and B
A= @{$got_content;} == 1B= @{$expected_content;} == 1
ABresult
0X0
100
111
417 10 $tester->diag("text inside '$path' didn't match");
418 } else {
419 3 $tester->diag("text immediately inside opening tag of '$path' didn't match");
420 }
421 5 ▶ } elsif ($i == @{ $got_content} - 1 && $i == @{ $expected_content } - 1 ) {
Condition100%3/3
$i == @{$got_content;} - 1 and $i == @{$expected_content;} - 1
!ll&&!rl&&r
311
MC/DC100%2/2
$i == @{$got_content;} - 1 and $i == @{$expected_content;} - 1
$i == @{$got_content;} - 1 $i == @{$expected_content;} - 1
Truth table100%3/3
A and B
A= $i == @{$got_content;} - 1B= $i == @{$expected_content;} - 1
ABresult
0X0
100
111
422 1 $tester->diag("text immediately before closing tag of '$path' didn't match");
423 } else {
424 4 my $name = $got_content->[ $i - 1 ]->type_name;
425 4 my $ind = $child_index->{ $name };
426 4 $tester->diag("text immediately after '$path/$name\[$ind]' didn't match");
427 }
428  
429 18 $tester->diag("found:\n");
430 18 $tester->diag(" '$got_text'\n");
431 18 $tester->diag("expected:\n");
432 18 $tester->diag(" '$expected_text'\n");
433  
434 18 ▶ if ($options->{verbose}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($options->{"verbose"}) 0 18 18
435 0 $tester->diag("compared found text:\n");
436 0 $tester->diag(" '$comp_got_text'\n");
437 0 $tester->diag("against text:\n");
438 0 $tester->diag(" '$comp_expected_text'\n");
439 }
440  
441 18 return;
442 }
443  
444 # move onto the next (elemnent) node if we didn't reach the end
445 68 $i++;
446 68 ▶ last if $i >= @{$got_content};
Branch: 1 branch
BranchTrueFalseTotal
if $i >= @{$got_content;} 42 26 68
447  
448 ### check the element node
449  
450 # simply recurse for that node
451 # (don't bother checking if the expected node is defined or not, the case
452 # where it isn't is handled at the start of _is_xml)
453 26 ▶ return unless _is_xml(
Branch: 1 branch
BranchTrueFalseTotal
unless _is_xml($got_content->[$i], $expected_content->[$i], $options, $path, $child_index) 7 19 26
454 $got_content->[$i],
455 $expected_content->[$i],
456 $options,
457 $path,
458 $child_index
459 );
460 }
461  
462 # check if we expected more nodes
463 42 ▶ if (@{ $expected_content } > @{ $got_content }) {
Branch: 1 branch
BranchTrueFalseTotal
if (@{$expected_content;} > @{$got_content;}) 0 42 42
464 0 my $expected_nom = $expected_content->[ scalar @{ $got_content } ]->type_name;
465 0 my $expected_ind = $child_index->{ $expected_nom } + 1;
466 0 $tester->diag("Couldn't find expected node '$path/$expected_nom\[$expected_ind]'");
467 0 $tester->ok(0, $options->{description});
468 0 return;
469 }
470  
471 42 return 1;
472 }
473  
474 =item isnt_xml($xml_to_test, $not_expected_xml[, $options_hashref])
475  
476 Exactly the same as C<is_xml> (taking exactly the same options) but passes
477 if and only if what is passed is different to the not expected XML.
478  
479 By different, of course, we mean schematically different according to the
480 XML 1.0 specification. For example, this will fail:
481  
482 isnt_xml "<foo/>", "<foo></foo>";
483  
484 as those are schematically the same XML documents.
485  
486 However, it's worth noting that the first argument doesn't even have to be
487 valid XML for the test to pass. Both these pass as they're not schemantically
488 identical to the not expected XML:
489  
490 isnt_xml undef, $not_expecteded_xml;
491 isnt_xml "<foo>", $not_expected_xml;
492  
493 as invalid XML is not ever schemanitcally identical to a valid XML document.
494  
495 If you want to insist what you pass in is valid XML, but just not the
496 same as the other xml document you pass in then you can use two tests:
497  
498 is_well_formed_xml $xml;
499 isnt_xml $xml, $not_expected_xml;
500  
501 This function accepts the C<verbose> option (just as C<is_xml> does) but
502 turning it on doesn't actually output anything extra - there's not useful this
503 function can output that would help you diagnose the failure case.
504  
505 =cut
506  
507 11 ▶sub isnt_xml($$;$) {
Subroutine isnt_xml: called CC=9 SCAR=22.0
Pod documented
508 11 my $got = shift;
509 11 my $expected = shift;
510 11 my $options = shift;
511  
512 11 ▶ $options = { description => $options } unless ref $options eq "HASH";
Branch: 1 branch
BranchTrueFalseTotal
unless ref $options eq "HASH" 7 4 11
513 9 $options = { %{$options}, description => "not xml test" }
514 11 ▶ unless defined $options->{description};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $options->{"description"} 9 2 11
515  
516 # temporarly ignore test output and just get the result of running
517 # the is_xml function as normal
518 11 $tester = bless {}, "Test::XML::Easy::Ignore";
519 11 ▶ my $result = eval { is_xml($got, $expected, $options) ? 0 : 1 };
Branch: 1 branch
BranchTrueFalseTotal
&is_xml($got, $expected, $options) ? : 3 6 9
520 11 $tester = Test::Builder->new();
521  
522 # did we get an error? Note we don't check $@ directly incase
523 # it's been reset by a weird DESTROY() eval...
524 11 ▶ unless (defined($result) && length $result) { croak $@; }
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $result and length $result) 2 9 11
Condition66%2/3
defined $result and length $result
!ll&&!rl&&r
209
MC/DC50%1/2
defined $result and length $result
defined $result length $result
Truth table66%2/3
A and B
A= defined $resultB= length $result
ABresult
0X0
100
111
525  
526 9 ▶ if ($result) {
Branch: 1 branch
BranchTrueFalseTotal
if ($result) 6 3 9
527 6 $tester->ok(1, $options->{description});
528 6 return 1;
529 }
530  
531 3 $tester->ok(0, $options->{description});
532 3 $tester->diag("Unexpectedly matched the XML we didn't expect");
533 3 ▶ if ($options->{show_xml}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($options->{"show_xml"}) 2 1 3
534 2 $tester->diag("The XML that we received was:");
535 2 ▶ if (is_xml_element($got))
Branch: 1 branch
BranchTrueFalseTotal
if (&is_xml_element($got)) { } 1 1 2
536 1 { $tester->diag(xml10_write_document($got)) }
537 else
538 1 { $tester->diag($got) }
539 }
540 3 return;
541 }
542 11 push @EXPORT, "isnt_xml";
543  
544 =item is_well_formed_xml($string_containing_xml[, $description])
545  
546 Passes if and only if the string passed contains well formed XML.
547  
548 =cut
549  
550 4 ▶sub is_well_formed_xml($;$) {
Subroutine is_well_formed_xml: called CC=4 SCAR=13.9
Pod documented
551 4 my $xml_string = shift;
552 4 my $options = shift;
553  
554 4 ▶ $options = { description => $options } unless ref $options eq "HASH";
Branch: 1 branch
BranchTrueFalseTotal
unless ref $options eq "HASH" 3 1 4
555 2 $options = { %{$options}, description => "xml well formed test" }
556 4 ▶ unless defined $options->{description};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $options->{"description"} 2 2 4
557  
558 4 ▶ if(eval { xml10_read_document($xml_string); 1 }) {
Branch: 1 branch
BranchTrueFalseTotal
if (eval { do { &xml10_read_document($xml_string); 1 } }) 3 1 4
559 3 $tester->ok(1, $options->{description});
560 3 return 1;
561 }
562  
563 1 $tester->ok(0, $options->{description});
564 1 $tester->diag($@);
565 1 return;
566 }
567 11 push @EXPORT, "is_well_formed_xml";
568  
569 =item isnt_well_formed_xml($string_not_containing_xml[, $description])
570  
571 Passes if and only if the string passed does not contain well formed XML.
572  
573 =cut
574  
575 4 ▶sub isnt_well_formed_xml($;$) {
Subroutine isnt_well_formed_xml: called CC=4 SCAR=13.9
Pod documented
576 4 my $xml_string = shift;
577 4 my $options = shift;
578  
579 4 ▶ $options = { description => $options } unless ref $options eq "HASH";
Branch: 1 branch
BranchTrueFalseTotal
unless ref $options eq "HASH" 3 1 4
580 2 $options = { %{$options}, description => "xml not well formed test" }
581 4 ▶ unless defined $options->{description};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $options->{"description"} 2 2 4
582  
583 4 ▶ unless (eval { xml10_read_document($xml_string); 1 }) {
Branch: 1 branch
BranchTrueFalseTotal
unless (eval { do { &xml10_read_document($xml_string); 1 } }) 3 1 4
584 3 $tester->ok(1, $options->{description});
585 3 return 1;
586 }
587  
588 1 $tester->ok(0, $options->{description});
589 1 $tester->diag("Unexpectedly well formed XML");
590 1 return;
591 }
592 11 push @EXPORT, "isnt_well_formed_xml";
593  
594 =back
595  
596 =head2 A note on Character Handling
597  
598 If you do not pass it an XML::Easy::Element object then these functions will happly parse
599 XML from the characters contained in whatever scalars you passed in. They will not
600 (and cannot) correctly parse data from a scalar that contains binary data (e.g. that
601 you've sucked in from a raw file handle) as they would have no idea what characters
602 those octlets would represent
603  
604 As long as your XML document contains legal characters from the ASCII range (i.e.
605 chr(1) to chr(127)) this distintion will not matter to you.
606  
607 However, if you use characters above codepoint 127 then you will probably need to
608 convert any bytes you have read in into characters. This is usually done by using
609 C<Encode::decode>, or by using a PerlIO layer on the filehandle as you read the data
610 in.
611  
612 If you don't know what any of this means I suggest you read the Encode::encode manpage
613 very carefully. Tom Insam's slides at L<http://jerakeen.org/talks/perl-loves-utf8/>
614 may or may not help you understand this more (they at the very least contain a
615 cheatsheet for conversion.)
616  
617 The author highly recommends those of you using latin-1 characters from a utf-8 source
618 to use B<Test::utf8> to check the string for common mistakes before handing it C<is_xml>.
619  
620 =head1 AUTHOR
621  
622 Mark Fowler, C<< <mark@twoshortplanks.com> >>
623  
624 Copyright 2009 PhotoBox, All Rights Reserved.
625  
626 This program is free software; you can redistribute it and/or modify it
627 under the same terms as Perl itself.
628  
629 =head1 BUGS
630  
631 There's a few cavets when using this module:
632  
633 =over
634  
635 =item Not a validating parser
636  
637 Infact, we don't process (or compare) DTDs at all. These nodes are completely
638 ignored (it's as if you didn't include them in the string at all.)
639  
640 =item Comments and processing instructions are ignored
641  
642 We totally ignore comments and processing instructions, and it's as
643 if you didn't include them in the string at all either.
644  
645 =item Limited entity handling
646  
647 We only support the five "core" named entities (i.e. C<&amp;>,
648 C<&lt;>, C<&gt;>, C<&apos;> and C<&quot;>) and numerical character references
649 (in decimal or hex form.) It is not possible to declare further named
650 entities and the precence of undeclared named entities will either cause
651 an exception to be thrown (in the case of the expected string) or the test to
652 fail (in the case of the string you are testing)
653  
654 =item No namespace support
655  
656 Currently this is only an XML 1.0 parser, and not XML Namespaces aware (further
657 options may be added to later version of this module to enable namespace support)
658  
659 This means the following document:
660  
661 <foo:fred xmlns:foo="http://www.twoshortplanks.com/namespaces/test/fred" />
662  
663 Is considered to be different to
664  
665 <bar:fred xmlns:bar="http://www.twoshortplanks.com/namespaces/test/fred" />
666  
667 =item XML whitespace handling
668  
669 This module considers "whitespace" to be what the XML specification considers
670 to be whitespace. This is subtily different to what Perl considers to be
671 whitespace.
672  
673 =item No node reordering support
674  
675 Unlike B<Test::XML> this module considers the order of sibling nodes to be
676 significant, and you cannot tell it to ignore the differring order of nodes
677 when comparing the expected and actual output.
678  
679 =back
680  
681 Please see L<http://twoshortplanks.com/dev/testxmleasy> for
682 details of how to submit bugs, access the source control for
683 this project, and contact the author.
684  
685 =head1 SEE ALSO
686  
687 L<Test::More> (for instructions on how to test), L<XML::Easy> (for info
688 on the underlying xml parser) and L<Test::XML> (for a similar module that
689 tests using XML::SchemanticDiff)
690  
691 =cut
692  
693 11 1; # End of Test::XML::Easy
694  
695 package Test::XML::Easy::Ignore;
696  
697 # a handy class you can bless your tester into so we ignore all
698 # calls and don't actually produce any test output
699  
700 9 ▶sub ok { return }
Subroutine ok: called CC=1 SCAR=0.0
701 14 ▶sub diag { return }
Subroutine diag: called CC=1 SCAR=0.0
702  
703 11 1; # End of Test::XML::Easy::Ignore;
↑ Summary