1Test2::Manual::Testing:U:sIenrtrCoodnutcrtiibount(e3d)PTeerslt2D:o:cMuamneunatla:t:iToensting::Introduction(3)
2
3
4

NAME

6       Test2::Manual::Testing::Introduction - Introduction to testing with
7       Test2.
8

DESCRIPTION

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

BOILERPLATE

15   THE TEST FILE
16       Test files typically are placed inside the "t/" directory, and end with
17       the ".t" file extension.
18
19       "t/example.t":
20
21           use Test2::V0;
22
23           # Assertions will go here
24
25           done_testing;
26
27       This is all the boilerplate you need.
28
29       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
34       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
40   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
45       Dist::Zilla
46
47           [Prereqs / TestRequires]
48           Test2::V0 = 0.000060
49
50       ExtUtils::MakeMaker
51
52           my %WriteMakefileArgs = (
53             ...,
54             "TEST_REQUIRES" => {
55               "Test2::V0" => "0.000060"
56             },
57             ...
58           );
59
60       Module::Install
61
62           test_requires 'Test2::V0' => '0.000060';
63
64       Module::Build
65
66           my $build = Module::Build->new(
67               ...,
68               test_requires => {
69                   "Test2::V0" => "0.000060",
70               },
71               ...
72           );
73

MAKING ASSERTIONS

75       The most simple tool for making assertions is "ok()". "ok()" lets you
76       assert that a condition is true.
77
78           ok($CONDITION, "Description of the condition");
79
80       Here is a complete "t/example.t":
81
82           use Test2::V0;
83
84           ok(1, "1 is true, so this will pass");
85
86           done_testing;
87

RUNNING THE TEST

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
94   RUN DIRECTLY
95           $ perl -Ilib t/example.t
96
97       Which should produce output like this:
98
99           # Seeded srand with seed '20161028' from local date.
100           ok 1 - 1 is true, so this will pass
101           1..1
102
103       If the test had failed ("ok(0, ...)") it would look like this:
104
105           # Seeded srand with seed '20161028' from local date.
106           not ok 1 - 0 is false, so this will fail
107           1..1
108
109       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
112   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
117           $ yath -Ilib t/example.t
118
119       This will produce output similar to this:
120
121           ( PASSED )  job  1    t/example.t
122
123           ================================================================================
124
125           Run ID: 1508027909
126
127           All tests were successful!
128
129       You can also request verbose output with the "-v" flag:
130
131           $ yath -Ilib -v t/example.t
132
133       Which produces:
134
135           ( 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
141           ================================================================================
142
143           Run ID: 1508028002
144
145           All tests were successful!
146
147   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
152           $ prove -Ilib t/example.t
153
154       This will produce output like this:
155
156           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
161       You can also request verbose output with the "-v" flag:
162
163           $ prove -Ilib -v t/example.t
164
165       The verbose output looks like this:
166
167           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

THE "PLAN"

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
181       There are 2 primary ways to set the plan:
182
183       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
190       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
198           "plan()" must be used before all assertions, or after all
199           assertions, it cannot be done in the middle of making assertions.
200

ADDITIONAL ASSERTION TOOLS

202       The Test2::V0 bundle provides a lot more than "ok()", "plan()", and
203       "done_testing()". The biggest tools to note are:
204
205       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
210               is("foo", "foo", "Both strings are identical");
211
212               is(["foo", 1], ["foo", 1], "Both arrays contain the same elements");
213
214       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
218               like([1, 2, 3, 4], [1, 2, 3], "Passes, the extra element on the left is ignored");
219
220           You can also used regular expressions on the right hand side:
221
222               like("foo bar baz", qr/bar/, "The string matches the regex, this passes");
223
224           You can also nest the regexes:
225
226               like([1, 2, 'foo bar baz', 3], [1, 2, qr/bar/], "This passes");
227

SEE ALSO

229       Test2::Manual - Primary index of the manual.
230

SOURCE

232       The source code repository for Test2-Manual can be found at
233       https://github.com/Test-More/Test2-Suite/.
234

MAINTAINERS

236       Chad Granum <exodist@cpan.org>
237

AUTHORS

239       Chad Granum <exodist@cpan.org>
240
242       Copyright 2018 Chad Granum <exodist@cpan.org>.
243
244       This program is free software; you can redistribute it and/or modify it
245       under the same terms as Perl itself.
246
247       See http://dev.perl.org/licenses/
248
249
250
251perl v5.28.2                      2019-0T5e-s1t82::Manual::Testing::Introduction(3)
Impressum