1Test::Regexp(3) User Contributed Perl Documentation Test::Regexp(3)
2
6 Test::Regexp - Test your regular expressions
7
9 use Test::Regexp 'no_plan';
10 match subject => "Foo",
12 pattern => qr /\w+/;
13 match subject => "Foo bar",
15 keep_pattern => qr /(?<first_word>\w+)\s+(\w+)/,
16 captures => [[first_word => 'Foo'], ['bar']];
17 no_match subject => "Baz",
19 pattern => qr /Quux/;
20 $checker = Test::Regexp -> new -> init (
22 keep_pattern => qr /(\w+)\s+\g{-1}/,
23 name => "Double word matcher",
24 );
25 $checker -> match ("foo foo", ["foo"]);
27 $checker -> no_match ("foo bar");
28
30 This module is intended to test your regular expressions. Given a
31 subject string and a regular expression (aka pattern), the module not
32 only tests whether the regular expression complete matches the subject
33 string, it performs a "utf8::upgrade" or "utf8::downgrade" on the
34 subject string and performs the tests again, if necessary. Furthermore,
35 given a pattern with capturing parenthesis, it checks whether all
36 captures are present, and in the right order. Both named and unnamed
37 captures are checked.
38 By default, the module exports two subroutines, "match" and "no_match".
40 The latter is actually a thin wrapper around "match", calling it with
41 "match => 0".
42 "Complete matching"
44 A match is only considered to successfully match if the entire string
45 is matched - that is, if $& matches the subject string. So:
46 Subject Pattern
48 "aaabb" qr /a+b+/ # Considered ok
50 "aaabb" qr /a+/ # Not considered ok
51 For efficiency reasons, when the matching is performed the pattern is
53 actually anchored at the start. It's not anchored at the end as that
54 would potentially influence the matching.
55 UTF8 matching
57 Certain regular expression constructs match differently depending on
58 whether UTF8 matching is in effect or not. This is only relevant if the
59 subject string has characters with code points between 128 and 255, and
60 no characters above 255 -- in such a case, matching may be different
61 depending on whether the subject string has the UTF8 flag on or not.
62 "Test::Regexp" detects such a case, and will then run the tests twice;
63 once with the subject string "utf8::downgraded", and once with the
64 subject string "utf8::upgraded".
65 Number of tests
67 There's no fixed number of tests that is run. The number of tests
68 depends on the number of captures, the number of different names of
69 captures, and whether there is the need to up- or downgrade the subject
70 string.
71 It is therefore recommended to use "use Text::Regexp tests =>
73 'no_plan';". In a later version, "Test::Regexp" will use a version of
74 "Test::Builder" that allows for nested tests.
75 Details
77 The number of tests is as follows:
79 If no match is expected ("no_match => 0", or "no_match" is used), only
81 one test is performed.
82 Otherwise (we are expecting a match), if "pattern" is used, there will
84 be three tests.
85 For "keep_pattern", there will be four tests, plus one tests for each
87 capture, an additional test for each named capture, and a test for each
88 name used in the set of named captures. So, if there are "N" captures,
89 there will be at least "4 + N" tests, and at most "4 + 3 * N" tests.
90 If both "pattern" and "keep_pattern" are used, the number of tests add
92 up.
93 If "Test::Regexp" decides to upgrade or downgrade, the number of tests
95 double.
96 "use" options
98 When using "Test::Regexp", there are a few options you can give it.
99 "tests => 'no_plan'", "tests => 123"
101 The number of tests you are going to run. Since takes some work to
102 figure out how many tests will be run, for now the recommendation
103 is to use "tests => 'no_plan'".
104 "import => [methods]"
106 By default, the subroutines "match" and "no_match" are exported. If
107 you want to import a subset, use the "import" tag, and give it an
108 arrayref with the names of the subroutines to import.
109 "match"
111 The subroutine "match" is the workhorse of the module. It takes a
112 number of named arguments, most of them optional, and runs one or more
113 tests. It returns 1 if all tests were run successfully, and 0 if one or
114 more tests failed. The following options are available:
115 "subject => STRING"
117 The string against which the pattern is tested is passed to "match"
118 using the "subject" option. It's an error to not pass in a subject.
119 "pattern => PATTERN", "keep_pattern => PATTERN"
121 A pattern (aka regular expression) to test can be passed with one
122 of "pattern" or "keep_pattern". The former should be used if the
123 pattern does not have any matching parenthesis; the latter if the
124 pattern does have capturing parenthesis. If both "pattern" and
125 "keep_pattern" are provided, the subject is tested against both.
126 It's an error to not give either "pattern" or "keep_pattern".
127 "captures => [LIST]"
129 If a regular expression is passed with "keep_pattern" you should
130 pass in a list of captures using the "captures" option.
131 This list should contain all the captures, in order. For unnamed
133 captures, this should just be the string matched by the capture;
134 for a named capture, this should be a two element array, the first
135 element being the name of the capture, the second element the
136 capture. Named and unnamed captures may be mixed, and the same name
137 for a capture may be repeated.
138 Example:
140 match subject => "Eland Wapiti Caribou",
142 keep_pattern => qr /(\w+)\s+(?<a>\w+)\s+(\w+)/,
143 captures => ["Eland", [a => "Wapiti"], "Caribou"];
144 "name => NAME"
146 The "name" of the test. It's being used in the test comment.
147 "comment => NAME"
149 An alternative for "name". If both are present, "comment" is used.
150 "utf8_upgrade => 0", "utf8_downgrade => 0"
152 As explained in "UTF8 matching", "Test::Regexp" detects whether a
153 subject may provoke different matching depending on its UTF8 flag,
154 and then it "utf8::upgrades" or "utf8::downgrades" the subject
155 string and runs the test again. Setting "utf8_upgrade" to 0
156 prevents "Test::Regexp" from downgrading the subject string, while
157 setting "utf8_upgrade" to 0 prevents "Test::Regexp" from upgrading
158 the subject string.
159 "match => BOOLEAN"
161 By default, "match" assumes the pattern should match. But it also
162 important to test which strings do not match a regular expression.
163 This can be done by calling "match" with "match => 0" as parameter.
164 (Or by calling "no_match" instead of "match"). In this case, the
165 test is a failure if the pattern completely matches the subject
166 string. A "captures" argument is ignored.
167 "reason => STRING"
169 If the match is expected to fail (so, when "match => 0" is passed,
170 or if "no_match" is called), a reason may be provided with the
171 "reason" option. The reason is then printed in the comment of the
172 test.
173 "test => STRING"
175 If the match is expected to pass (when "match" is called, without
176 "match" being false), and this option is passed, a message is
177 printed indicating what this specific test is testing (the argument
178 to "test").
179 "todo => STRING"
181 If the "todo" parameter is used (with a defined value), the tests
182 are assumed to be TODO tests. The argument is used as the TODO
183 message.
184 "full_text => BOOL"
186 By default, long test messages are truncated; if a true value is
187 passed, the message will not get truncated.
188 "escape => INTEGER"
190 Controls how non-ASCII and non-printables are displayed in
191 generated test messages:
192 0 No characters are escape, everything is displayed as is.
194 1 Show newlines, linefeeds and tabs using their usual escape
196 sequences ("\n", "\r", and "\t").
197 2 Show any character outside of the printable ASCII characters as
199 named escapes ("\N{UNICODE NAME}"), or a hex escape if the
200 unicode name is not found ("\x{XX}"). This is the default if
201 "-CO" is not in effect ("${^UNICODE}" is false).
202 Newlines, linefeeds and tabs are displayed as above.
204 3 Show any character outside of the printable ASCII characters as
206 hext escapes ("\x{XX}").
207 Newlines, linefeeds and tabs are displayed as above.
209 4 Show the non-printable ASCII characters as hex escapes
211 ("\x{XX}"); any non-ASCII character is displayed as is. This is
212 the default if "-CO" is in effect ("${^UNICODE}" is true).
213 Newlines, linefeeds and tabs are displayed as above.
215 "no_keep_message => BOOL"
217 If matching against a keeping pattern, a message "(with -Keep)" is
218 added to the comment. Setting this parameter suppresses this
219 message. Mostly useful for "Regexp::Common510".
220 "no_match"
222 Similar to "match", except that it tests whether a pattern does not
223 match a string. Accepts the same arguments as "match", except for
224 "match".
225 OO interface
227 Since one typically checks a pattern with multiple strings, and it can
228 be tiresome to repeatedly call "match" or "no_match" with the same
229 arguments, there's also an OO interface. Using a pattern, one
230 constructs an object and can then repeatedly call the object to match a
231 string.
232 To construct and initialize the object, call the following:
234 my $checker = Test::Regexp -> new -> init (
236 pattern => qr /PATTERN/,
237 keep_pattern => qr /(PATTERN)/,
238 ...
239 );
240 "init" takes exactly the same arguments as "match", with the exception
242 of "subject" and "captures". To perform a match, all "match" (or
243 "no_match") on the object. The first argument should be the subject the
244 pattern should match against (see the "subject" argument of "match"
245 discussed above). If there is a match against a capturing pattern, the
246 second argument is a reference to an array with the matches (see the
247 "captures" argument of "match" discussed above).
248 Both "match" and "no_match" can take additional (named) arguments,
250 identical to the none-OO "match" and "no_match" routines.
251
253 The reason "Test::Regexp" was created is to aid testing for the rewrite
254 of "Regexp::Common".
255
257 The current sources of this module are found on github,
258 <git://github.com/Abigail/Test-Regexp.git>.
259
261 Abigail <mailto:test-regexp@abigail.be>.
262
264 Copyright (C) 2009 by Abigail
265 Permission is hereby granted, free of charge, to any person obtaining a
267 copy of this software and associated documentation files (the
268 "Software"), to deal in the Software without restriction, including
269 without limitation the rights to use, copy, modify, merge, publish,
270 distribute, sublicense, and/or sell copies of the Software, and to
271 permit persons to whom the Software is furnished to do so, subject to
272 the following conditions:
273 The above copyright notice and this permission notice shall be included
275 in all copies or substantial portions of the Software.
276 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
278 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
279 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
280 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
281 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
282 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
283 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
284
286 To install this module, run, after unpacking the tar-ball, the
287 following commands:
288 perl Makefile.PL
290 make
291 make test
292 make install
293perl v5.38.0 2023-07-21 Test::Regexp(3)