1Test2::Manual::Testing:U:sIenrtrCoodnutcrtiibount(e3d)PTeerslt2D:o:cMuamneunatla:t:iToensting::Introduction(3)
2
6 Test2::Manual::Testing::Introduction - Introduction to testing with
7 Test2.
8
10 This tutorial is a beginners introduction to testing. This will take
11 you through writing a test file, making assertions, and running your
12 test.
13
15 THE TEST FILE
16 Test files typically are placed inside the "t/" directory, and end with
17 the ".t" file extension.
18 "t/example.t":
20 use Test2::V0;
22 # Assertions will go here
24 done_testing;
26 This is all the boilerplate you need.
28 use Test2::V0;
30 This loads a collection of testing tools that will be described
31 later in the tutorial. This will also turn on "strict" and
32 "warnings" for you.
33 done_testing;
35 This should always be at the end of your test files. This tells
36 Test2 that you are done making assertions. This is important as
37 "test2" will assume the test did not complete successfully without
38 this, or some other form of test "plan".
39 DIST CONFIG
41 You should always list bundles and tools directly. You should not
42 simply list Test2::Suite and call it done, bundles and tools may be
43 moved out of Test2::Suite to their own dists at any time.
44 Dist::Zilla
46 [Prereqs / TestRequires]
48 Test2::V0 = 0.000060
49 ExtUtils::MakeMaker
51 my %WriteMakefileArgs = (
53 ...,
54 "TEST_REQUIRES" => {
55 "Test2::V0" => "0.000060"
56 },
57 ...
58 );
59 Module::Install
61 test_requires 'Test2::V0' => '0.000060';
63 Module::Build
65 my $build = Module::Build->new(
67 ...,
68 test_requires => {
69 "Test2::V0" => "0.000060",
70 },
71 ...
72 );
73
75 The most simple tool for making assertions is "ok()". "ok()" lets you
76 assert that a condition is true.
77 ok($CONDITION, "Description of the condition");
79 Here is a complete "t/example.t":
81 use Test2::V0;
83 ok(1, "1 is true, so this will pass");
85 done_testing;
87
89 Test files are simply scripts. Just like any other script you can run
90 the test directly with perl. Another option is to use a test "harness"
91 which runs the test for you, and provides extra information and checks
92 the scripts exit value for you.
93 RUN DIRECTLY
95 $ perl -Ilib t/example.t
96 Which should produce output like this:
98 # Seeded srand with seed '20161028' from local date.
100 ok 1 - 1 is true, so this will pass
101 1..1
102 If the test had failed ("ok(0, ...)") it would look like this:
104 # Seeded srand with seed '20161028' from local date.
106 not ok 1 - 0 is false, so this will fail
107 1..1
108 Test2 will also set the exit value of the script, a successful run will
110 have an exit value of 0, a failed run will have a non-zero exit value.
111 USING YATH
113 The "yath" command line tool is provided by Test2::Harness which you
114 may need to install yourself from cpan. "yath" is the harness written
115 specifically for Test2.
116 $ yath -Ilib t/example.t
118 This will produce output similar to this:
120 ( PASSED ) job 1 t/example.t
122 ================================================================================
124 Run ID: 1508027909
126 All tests were successful!
128 You can also request verbose output with the "-v" flag:
130 $ yath -Ilib -v t/example.t
132 Which produces:
134 ( LAUNCH ) job 1 example.t
136 ( NOTE ) job 1 Seeded srand with seed '20171014' from local date.
137 [ PASS ] job 1 + 1 is true, so this will pass
138 [ PLAN ] job 1 Expected asserions: 1
139 ( PASSED ) job 1 example.t
140 ================================================================================
142 Run ID: 1508028002
144 All tests were successful!
146 USING PROVE
148 The "prove" command line tool is provided by the Test::Harness module
149 which comes with most versions of perl. Test::Harness is dual-life,
150 which means you can also install the latest version from cpan.
151 $ prove -Ilib t/example.t
153 This will produce output like this:
155 example.t .. ok
157 All tests successful.
158 Files=1, Tests=1, 0 wallclock secs ( 0.01 usr 0.00 sys + 0.05 cusr 0.00 csys = 0.06 CPU)
159 Result: PASS
160 You can also request verbose output with the "-v" flag:
162 $ prove -Ilib -v t/example.t
164 The verbose output looks like this:
166 example.t ..
168 # Seeded srand with seed '20161028' from local date.
169 ok 1 - 1 is true, so this will pass
170 1..1
171 ok
172 All tests successful.
173 Files=1, Tests=1, 0 wallclock secs ( 0.02 usr 0.00 sys + 0.06 cusr 0.00 csys = 0.08 CPU)
174 Result: PASS
175
177 All tests need a "plan". The job of a plan is to make sure you ran all
178 the tests you expected. The plan prevents a passing result from a test
179 that exits before all the tests are run.
180 There are 2 primary ways to set the plan:
182 done_testing()
184 The most common, and recommended way to set a plan is to add
185 "done_testing" at the end of your test file. This will
186 automatically calculate the plan for you at the end of the test. If
187 the test were to exit early then "done_testing" would not run and
188 no plan would be found, forcing a failure.
189 plan($COUNT)
191 The "plan()" function allows you to specify an exact number of
192 assertions you want to run. If you run too many or too few
193 assertions then the plan will not match and it will be counted as a
194 failure. The primary problem with this way of planning is that you
195 need to add up the number of assertions, and adjust the count
196 whenever you update the test file.
197 "plan()" must be used before all assertions, or after all
199 assertions, it cannot be done in the middle of making assertions.
200
202 The Test2::V0 bundle provides a lot more than "ok()", "plan()", and
203 "done_testing()". The biggest tools to note are:
204 is($a, $b, $description)
206 "is()" allows you to compare 2 structures and insure they are
207 identical. You can use it for simple string comparisons, or even
208 deep data structure comparisons.
209 is("foo", "foo", "Both strings are identical");
211 is(["foo", 1], ["foo", 1], "Both arrays contain the same elements");
213 like($a, $b, $description)
215 "like()" is similar to "is()" except that it only checks items
216 listed on the right, it ignores any extra values found on the left.
217 like([1, 2, 3, 4], [1, 2, 3], "Passes, the extra element on the left is ignored");
219 You can also used regular expressions on the right hand side:
221 like("foo bar baz", qr/bar/, "The string matches the regex, this passes");
223 You can also nest the regexes:
225 like([1, 2, 'foo bar baz', 3], [1, 2, qr/bar/], "This passes");
227
229 Test2::Manual - Primary index of the manual.
230
232 The source code repository for Test2-Manual can be found at
233 https://github.com/Test-More/Test2-Suite/.
234
236 Chad Granum <exodist@cpan.org>
237
239 Chad Granum <exodist@cpan.org>
240
242 Copyright 2018 Chad Granum <exodist@cpan.org>.
243 This program is free software; you can redistribute it and/or modify it
245 under the same terms as Perl itself.
246 See http://dev.perl.org/licenses/
248perl v5.30.1 2020-0T1e-s3t12::Manual::Testing::Introduction(3)