Debian Codegraph @

upstream/mageia-cauldron/man3pm/Test2::Manual::Testing::Introduction.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Test2::Manual::Testing::Introduction 3pm"
61 .TH Test2::Manual::Testing::Introduction 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Test2::Manual::Testing::Introduction \- Introduction to testing with Test2.
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 This tutorial is a beginners introduction to testing. This will take you
71 through writing a test file, making assertions, and running your test.
72 .SH BOILERPLATE
73 .IX Header "BOILERPLATE"
74 .SS "THE TEST FILE"
75 .IX Subsection "THE TEST FILE"
76 Test files typically are placed inside the \f(CW\*(C`t/\*(C'\fR directory, and end with the
77 \&\f(CW\*(C`.t\*(C'\fR file extension.
78 .PP
79 \&\f(CW\*(C`t/example.t\*(C'\fR:
80 .PP
81 .Vb 1
82 \& use Test2::V0;
83 \&
84 \& # Assertions will go here
85 \&
86 \& done_testing;
87 .Ve
88 .PP
89 This is all the boilerplate you need.
90 .IP "use Test2::V0;" 4
91 .IX Item "use Test2::V0;"
92 This loads a collection of testing tools that will be described later in the
93 tutorial. This will also turn on \f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`warnings\*(C'\fR for you.
94 .IP done_testing; 4
95 .IX Item "done_testing;"
96 This should always be at the end of your test files. This tells Test2 that
97 you are done making assertions. This is important as \f(CW\*(C`test2\*(C'\fR will assume the
98 test did not complete successfully without this, or some other form of test
99 "plan".
100 .SS "DIST CONFIG"
101 .IX Subsection "DIST CONFIG"
102 You should always list bundles and tools directly. You should not simply list
103 Test2::Suite and call it done, bundles and tools may be moved out of
104 Test2::Suite to their own dists at any time.
105 .PP
106 \fIDist::Zilla\fR
107 .IX Subsection "Dist::Zilla"
108 .PP
109 .Vb 2
110 \& [Prereqs / TestRequires]
111 \& Test2::V0 = 0.000060
112 .Ve
113 .PP
114 \fIExtUtils::MakeMaker\fR
115 .IX Subsection "ExtUtils::MakeMaker"
116 .PP
117 .Vb 7
118 \& my %WriteMakefileArgs = (
119 \& ...,
120 \& "TEST_REQUIRES" => {
121 \& "Test2::V0" => "0.000060"
122 \& },
123 \& ...
124 \& );
125 .Ve
126 .PP
127 \fIModule::Install\fR
128 .IX Subsection "Module::Install"
129 .PP
130 .Vb 1
131 \& test_requires \*(AqTest2::V0\*(Aq => \*(Aq0.000060\*(Aq;
132 .Ve
133 .PP
134 \fIModule::Build\fR
135 .IX Subsection "Module::Build"
136 .PP
137 .Vb 7
138 \& my $build = Module::Build\->new(
139 \& ...,
140 \& test_requires => {
141 \& "Test2::V0" => "0.000060",
142 \& },
143 \& ...
144 \& );
145 .Ve
146 .SH "MAKING ASSERTIONS"
147 .IX Header "MAKING ASSERTIONS"
148 The most simple tool for making assertions is \f(CWok()\fR. \f(CWok()\fR lets you assert
149 that a condition is true.
150 .PP
151 .Vb 1
152 \& ok($CONDITION, "Description of the condition");
153 .Ve
154 .PP
155 Here is a complete \f(CW\*(C`t/example.t\*(C'\fR:
156 .PP
157 .Vb 1
158 \& use Test2::V0;
159 \&
160 \& ok(1, "1 is true, so this will pass");
161 \&
162 \& done_testing;
163 .Ve
164 .SH "RUNNING THE TEST"
165 .IX Header "RUNNING THE TEST"
166 Test files are simply scripts. Just like any other script you can run the test
167 directly with perl. Another option is to use a test "harness" which runs the
168 test for you, and provides extra information and checks the scripts exit value
169 for you.
170 .SS "RUN DIRECTLY"
171 .IX Subsection "RUN DIRECTLY"
172 .Vb 1
173 \& $ perl \-Ilib t/example.t
174 .Ve
175 .PP
176 Which should produce output like this:
177 .PP
178 .Vb 3
179 \& # Seeded srand with seed \*(Aq20161028\*(Aq from local date.
180 \& ok 1 \- 1 is true, so this will pass
181 \& 1..1
182 .Ve
183 .PP
184 If the test had failed (\f(CW\*(C`ok(0, ...)\*(C'\fR) it would look like this:
185 .PP
186 .Vb 3
187 \& # Seeded srand with seed \*(Aq20161028\*(Aq from local date.
188 \& not ok 1 \- 0 is false, so this will fail
189 \& 1..1
190 .Ve
191 .PP
192 Test2 will also set the exit value of the script, a successful run will have an
193 exit value of 0, a failed run will have a non\-zero exit value.
194 .SS "USING YATH"
195 .IX Subsection "USING YATH"
196 The \f(CW\*(C`yath\*(C'\fR command line tool is provided by Test2::Harness which you may
197 need to install yourself from cpan. \f(CW\*(C`yath\*(C'\fR is the harness written specifically
198 for Test2.
199 .PP
200 .Vb 1
201 \& $ yath \-Ilib t/example.t
202 .Ve
203 .PP
204 This will produce output similar to this:
205 .PP
206 .Vb 1
207 \& ( PASSED ) job 1 t/example.t
208 \&
209 \& ================================================================================
210 \&
211 \& Run ID: 1508027909
212 \&
213 \& All tests were successful!
214 .Ve
215 .PP
216 You can also request verbose output with the \f(CW\*(C`\-v\*(C'\fR flag:
217 .PP
218 .Vb 1
219 \& $ yath \-Ilib \-v t/example.t
220 .Ve
221 .PP
222 Which produces:
223 .PP
224 .Vb 5
225 \& ( LAUNCH ) job 1 example.t
226 \& ( NOTE ) job 1 Seeded srand with seed \*(Aq20171014\*(Aq from local date.
227 \& [ PASS ] job 1 + 1 is true, so this will pass
228 \& [ PLAN ] job 1 Expected asserions: 1
229 \& ( PASSED ) job 1 example.t
230 \&
231 \& ================================================================================
232 \&
233 \& Run ID: 1508028002
234 \&
235 \& All tests were successful!
236 .Ve
237 .SS "USING PROVE"
238 .IX Subsection "USING PROVE"
239 The \f(CW\*(C`prove\*(C'\fR command line tool is provided by the Test::Harness module which
240 comes with most versions of perl. Test::Harness is dual\-life, which means
241 you can also install the latest version from cpan.
242 .PP
243 .Vb 1
244 \& $ prove \-Ilib t/example.t
245 .Ve
246 .PP
247 This will produce output like this:
248 .PP
249 .Vb 4
250 \& example.t .. ok
251 \& All tests successful.
252 \& Files=1, Tests=1, 0 wallclock secs ( 0.01 usr 0.00 sys + 0.05 cusr 0.00 csys = 0.06 CPU)
253 \& Result: PASS
254 .Ve
255 .PP
256 You can also request verbose output with the \f(CW\*(C`\-v\*(C'\fR flag:
257 .PP
258 .Vb 1
259 \& $ prove \-Ilib \-v t/example.t
260 .Ve
261 .PP
262 The verbose output looks like this:
263 .PP
264 .Vb 8
265 \& example.t ..
266 \& # Seeded srand with seed \*(Aq20161028\*(Aq from local date.
267 \& ok 1 \- 1 is true, so this will pass
268 \& 1..1
269 \& ok
270 \& All tests successful.
271 \& Files=1, Tests=1, 0 wallclock secs ( 0.02 usr 0.00 sys + 0.06 cusr 0.00 csys = 0.08 CPU)
272 \& Result: PASS
273 .Ve
274 .SH "THE ""PLAN"""
275 .IX Header "THE ""PLAN"""
276 All tests need a "plan". The job of a plan is to make sure you ran all the
277 tests you expected. The plan prevents a passing result from a test that exits
278 before all the tests are run.
279 .PP
280 There are 2 primary ways to set the plan:
281 .IP \fBdone_testing()\fR 4
282 .IX Item "done_testing()"
283 The most common, and recommended way to set a plan is to add \f(CW\*(C`done_testing\*(C'\fR at
284 the end of your test file. This will automatically calculate the plan for you
285 at the end of the test. If the test were to exit early then \f(CW\*(C`done_testing\*(C'\fR
286 would not run and no plan would be found, forcing a failure.
287 .IP plan($COUNT) 4
288 .IX Item "plan($COUNT)"
289 The \f(CWplan()\fR function allows you to specify an exact number of assertions you
290 want to run. If you run too many or too few assertions then the plan will not
291 match and it will be counted as a failure. The primary problem with this way of
292 planning is that you need to add up the number of assertions, and adjust the
293 count whenever you update the test file.
294 .Sp
295 \&\f(CWplan()\fR must be used before all assertions, or after all assertions, it
296 cannot be done in the middle of making assertions.
297 .SH "ADDITIONAL ASSERTION TOOLS"
298 .IX Header "ADDITIONAL ASSERTION TOOLS"
299 The Test2::V0 bundle provides a lot more than \f(CWok()\fR,
300 \&\f(CWplan()\fR, and \f(CWdone_testing()\fR. The biggest tools to note are:
301 .ie n .IP "is($a, $b, $description)" 4
302 .el .IP "is($a, \f(CW$b\fR, \f(CW$description\fR)" 4
303 .IX Item "is($a, $b, $description)"
304 \&\f(CWis()\fR allows you to compare 2 structures and insure they are identical. You
305 can use it for simple string comparisons, or even deep data structure
306 comparisons.
307 .Sp
308 .Vb 1
309 \& is("foo", "foo", "Both strings are identical");
310 \&
311 \& is(["foo", 1], ["foo", 1], "Both arrays contain the same elements");
312 .Ve
313 .ie n .IP "like($a, $b, $description)" 4
314 .el .IP "like($a, \f(CW$b\fR, \f(CW$description\fR)" 4
315 .IX Item "like($a, $b, $description)"
316 \&\f(CWlike()\fR is similar to \f(CWis()\fR except that it only checks items listed on the
317 right, it ignores any extra values found on the left.
318 .Sp
319 .Vb 1
320 \& like([1, 2, 3, 4], [1, 2, 3], "Passes, the extra element on the left is ignored");
321 .Ve
322 .Sp
323 You can also used regular expressions on the right hand side:
324 .Sp
325 .Vb 1
326 \& like("foo bar baz", qr/bar/, "The string matches the regex, this passes");
327 .Ve
328 .Sp
329 You can also nest the regexes:
330 .Sp
331 .Vb 1
332 \& like([1, 2, \*(Aqfoo bar baz\*(Aq, 3], [1, 2, qr/bar/], "This passes");
333 .Ve
334 .SH "SEE ALSO"
335 .IX Header "SEE ALSO"
336 Test2::Manual \- Primary index of the manual.
337 .SH SOURCE
338 .IX Header "SOURCE"
339 The source code repository for Test2\-Manual can be found at
340 \&\fIhttps://github.com/Test\-More/test\-more/\fR.
341 .SH MAINTAINERS
342 .IX Header "MAINTAINERS"
343 .IP "Chad Granum <[email protected]>" 4
344 .IX Item "Chad Granum <[email protected]>"
345 .SH AUTHORS
346 .IX Header "AUTHORS"
347 .IP "Chad Granum <[email protected]>" 4
348 .IX Item "Chad Granum <[email protected]>"
349 .SH COPYRIGHT
350 .IX Header "COPYRIGHT"
351 Copyright Chad Granum <[email protected]>.
352 .PP
353 This program is free software; you can redistribute it and/or
354 modify it under the same terms as Perl itself.
355 .PP
356 See \fIhttp://dev.perl.org/licenses/\fR