1Test::LongString(3)   User Contributed Perl Documentation  Test::LongString(3)
2
3
4

NAME

6       Test::LongString - tests strings for equality, with more helpful
7       failures
8

SYNOPSIS

10           use Test::More tests => 1;
11           use Test::LongString;
12           like_string( $html, qr/(perl|cpan)\.org/ );
13
14           #     Failed test (html-test.t at line 12)
15           #          got: "<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Trans"...
16           #       length: 58930
17           #     doesn't match '(?-xism:(perl|cpan)\.org)'
18

DESCRIPTION

20       This module provides some drop-in replacements for the string
21       comparison functions of Test::More, but which are more suitable when
22       you test against long strings.  If you've ever had to search for text
23       in a multi-line string like an HTML document, or find specific items in
24       binary data, this is the module for you.
25

FUNCTIONS

27   is_string( $string, $expected [, $label ] )
28       "is_string()" is equivalent to "Test::More::is()", but with more
29       helpful diagnostics in case of failure.
30
31       •   It doesn't print the entire strings in the failure message.
32
33       •   It reports the lengths of the strings that have been compared.
34
35       •   It reports the length of the common prefix of the strings.
36
37       •   It reports the line and column the strings started to differ on.
38
39       •   In the diagnostics, non-ASCII characters are escaped as "\x{xx}".
40
41       For example:
42
43           is_string( $soliloquy, $juliet );
44
45           #     Failed test (soliloquy.t at line 15)
46           #          got: "To be, or not to be: that is the question:\x{0a}Whether"...
47           #       length: 1490
48           #     expected: "O Romeo, Romeo,\x{0a}wherefore art thou Romeo?\x{0a}Deny thy"...
49           #       length: 154
50           #     strings begin to differ at char 1 (line 1 column 1)
51
52   is_string_nows( $string, $expected [, $label ] )
53       Like "is_string()", but removes whitespace (in the "\s" sense) from the
54       arguments before comparing them.
55
56   like_string( $string, qr/regex/ [, $label ] )
57   unlike_string( $string, qr/regex/ [, $label ] )
58       "like_string()" and "unlike_string()" are replacements for
59       "Test::More:like()" and "unlike()" that only print the beginning of the
60       received string in the output.  Unfortunately, they can't print out the
61       position where the regex failed to match.
62
63           like_string( $soliloquy, qr/Romeo|Juliet|Mercutio|Tybalt/ );
64
65           #     Failed test (soliloquy.t at line 15)
66           #          got: "To be, or not to be: that is the question:\x{0a}Whether"...
67           #       length: 1490
68           #     doesn't match '(?-xism:Romeo|Juliet|Mercutio|Tybalt)'
69
70   contains_string( $string, $substring [, $label ] )
71       "contains_string()" searches for $substring in $string.  It's the same
72       as "like_string()", except that it's not a regular expression search.
73
74           contains_string( $soliloquy, "Romeo" );
75
76           #     Failed test (soliloquy.t at line 10)
77           #         searched: "To be, or not to be: that is the question:\x{0a}Whether"...
78           #   and can't find: "Romeo"
79
80       As of version 0.12, "contains_string()" will also report the Longest
81       Common SubString (LCSS) found in $string and, if the LCSS is short
82       enough, the surroundings will also be shown under LCSS Context. This
83       should help debug tests for really long strings like HTML output, so
84       you'll get something like:
85
86          contains_string( $html, '<div id="MainContent">' );
87          #   Failed test at t/foo.t line 10.
88          #     searched: "<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Stric"...
89          #   can't find: "<div id="MainContent">"
90          #         LCSS: "ainContent""
91          # LCSS context: "dolor sit amet</span>\x{0a}<div id="mainContent" class="
92
93       You can turn off LCSS reporting by setting $Test::LongString::LCSS to
94       0, or by specifying an argument to "use":
95
96           use Test::LongString lcss => 0;
97
98   lacks_string( $string, $substring [, $label ] )
99       "lacks_string()" makes sure that $substring does NOT exist in $string.
100       It's the same as "like_string()", except that it's not a regular
101       expression search.
102
103           lacks_string( $soliloquy, "slings" );
104
105           #     Failed test (soliloquy.t at line 10)
106           #         searched: "To be, or not to be: that is the question:\x{0a}Whether"...
107           #        and found: "slings"
108           #      at position: 147 (line 3 column 4)
109

CONTROLLING OUTPUT

111       By default, only the first 50 characters of the compared strings are
112       shown in the failure message.  This value is in $Test::LongString::Max,
113       and can be set at run-time.
114
115       You can also set it by specifying an argument to "use":
116
117           use Test::LongString max => 100;
118
119       When the compared strings begin to differ after a large prefix,
120       Test::LongString will not print them from the beginning, but will start
121       at the middle, more precisely at $Test::LongString::Context characters
122       before the first difference. By default this value is 10 characters. If
123       you want Test::LongString to always print the beginning of compared
124       strings no matter where they differ, undefine
125       $Test::LongString::Context.
126
127       When computing line numbers this module uses "\n" to count line
128       endings. This may not be appropriate for strings on your platform, and
129       can be overridden by setting the $Test::LongString::EOL variable to a
130       suitable regular expression (either a reference to a regular expression
131       or a string that can be interpolated into a regular expression.)
132
133       You can also set it by specifying an argument to "use":
134
135           use Test::LongString eol => "\x{0a}\x{0c}";
136

AUTHOR

138       Written by Rafael Garcia-Suarez. Thanks to Mark Fowler (and to Joss
139       Whedon) for the inspirational Acme::Test::Buffy. Thanks to Andy Lester
140       for lots of patches.
141
142       This program is free software; you may redistribute it and/or modify it
143       under the same terms as Perl itself.
144
145       A git repository for this module is available at
146
147           git://github.com/rgs/Test-LongString.git
148
149       and the project page at
150
151           http://github.com/rgs/Test-LongString
152

SEE ALSO

154       Test::Builder, Test::Builder::Tester, Test::More.
155
156
157
158perl v5.34.0                      2021-07-23               Test::LongString(3)
Impressum