1package Test2::Manual::Testing::Introduction; 2use strict; 3use warnings; 4 5our $VERSION = '0.000162'; 6 71; 8 9__END__ 10 11=head1 NAME 12 13Test2::Manual::Testing::Introduction - Introduction to testing with Test2. 14 15=head1 DESCRIPTION 16 17This tutorial is a beginners introduction to testing. This will take you 18through writing a test file, making assertions, and running your test. 19 20=head1 BOILERPLATE 21 22=head2 THE TEST FILE 23 24Test files typically are placed inside the C<t/> directory, and end with the 25C<.t> file extension. 26 27C<t/example.t>: 28 29 use Test2::V0; 30 31 # Assertions will go here 32 33 done_testing; 34 35This is all the boilerplate you need. 36 37=over 4 38 39=item use Test2::V0; 40 41This loads a collection of testing tools that will be described later in the 42tutorial. This will also turn on C<strict> and C<warnings> for you. 43 44=item done_testing; 45 46This should always be at the end of your test files. This tells L<Test2> that 47you are done making assertions. This is important as C<test2> will assume the 48test did not complete successfully without this, or some other form of test 49"plan". 50 51=back 52 53=head2 DIST CONFIG 54 55You should always list bundles and tools directly. You should not simply list 56L<Test2::Suite> and call it done, bundles and tools may be moved out of 57L<Test2::Suite> to their own dists at any time. 58 59=head3 Dist::Zilla 60 61 [Prereqs / TestRequires] 62 Test2::V0 = 0.000060 63 64=head3 ExtUtils::MakeMaker 65 66 my %WriteMakefileArgs = ( 67 ..., 68 "TEST_REQUIRES" => { 69 "Test2::V0" => "0.000060" 70 }, 71 ... 72 ); 73 74=head3 Module::Install 75 76 test_requires 'Test2::V0' => '0.000060'; 77 78=head3 Module::Build 79 80 my $build = Module::Build->new( 81 ..., 82 test_requires => { 83 "Test2::V0" => "0.000060", 84 }, 85 ... 86 ); 87 88=head1 MAKING ASSERTIONS 89 90The most simple tool for making assertions is C<ok()>. C<ok()> lets you assert 91that a condition is true. 92 93 ok($CONDITION, "Description of the condition"); 94 95Here is a complete C<t/example.t>: 96 97 use Test2::V0; 98 99 ok(1, "1 is true, so this will pass"); 100 101 done_testing; 102 103=head1 RUNNING THE TEST 104 105Test files are simply scripts. Just like any other script you can run the test 106directly with perl. Another option is to use a test "harness" which runs the 107test for you, and provides extra information and checks the scripts exit value 108for you. 109 110=head2 RUN DIRECTLY 111 112 $ perl -Ilib t/example.t 113 114Which should produce output like this: 115 116 # Seeded srand with seed '20161028' from local date. 117 ok 1 - 1 is true, so this will pass 118 1..1 119 120If the test had failed (C<ok(0, ...)>) it would look like this: 121 122 # Seeded srand with seed '20161028' from local date. 123 not ok 1 - 0 is false, so this will fail 124 1..1 125 126Test2 will also set the exit value of the script, a successful run will have an 127exit value of 0, a failed run will have a non-zero exit value. 128 129=head2 USING YATH 130 131The C<yath> command line tool is provided by L<Test2::Harness> which you may 132need to install yourself from cpan. C<yath> is the harness written specifically 133for L<Test2>. 134 135 $ yath -Ilib t/example.t 136 137This will produce output similar to this: 138 139 ( PASSED ) job 1 t/example.t 140 141 ================================================================================ 142 143 Run ID: 1508027909 144 145 All tests were successful! 146 147You can also request verbose output with the C<-v> flag: 148 149 $ yath -Ilib -v t/example.t 150 151Which produces: 152 153 ( LAUNCH ) job 1 example.t 154 ( NOTE ) job 1 Seeded srand with seed '20171014' from local date. 155 [ PASS ] job 1 + 1 is true, so this will pass 156 [ PLAN ] job 1 Expected asserions: 1 157 ( PASSED ) job 1 example.t 158 159 ================================================================================ 160 161 Run ID: 1508028002 162 163 All tests were successful! 164 165=head2 USING PROVE 166 167The C<prove> command line tool is provided by the L<Test::Harness> module which 168comes with most versions of perl. L<Test::Harness> is dual-life, which means 169you can also install the latest version from cpan. 170 171 $ prove -Ilib t/example.t 172 173This will produce output like this: 174 175 example.t .. ok 176 All tests successful. 177 Files=1, Tests=1, 0 wallclock secs ( 0.01 usr 0.00 sys + 0.05 cusr 0.00 csys = 0.06 CPU) 178 Result: PASS 179 180You can also request verbose output with the C<-v> flag: 181 182 $ prove -Ilib -v t/example.t 183 184The verbose output looks like this: 185 186 example.t .. 187 # Seeded srand with seed '20161028' from local date. 188 ok 1 - 1 is true, so this will pass 189 1..1 190 ok 191 All tests successful. 192 Files=1, Tests=1, 0 wallclock secs ( 0.02 usr 0.00 sys + 0.06 cusr 0.00 csys = 0.08 CPU) 193 Result: PASS 194 195=head1 THE "PLAN" 196 197All tests need a "plan". The job of a plan is to make sure you ran all the 198tests you expected. The plan prevents a passing result from a test that exits 199before all the tests are run. 200 201There are 2 primary ways to set the plan: 202 203=over 4 204 205=item done_testing() 206 207The most common, and recommended way to set a plan is to add C<done_testing> at 208the end of your test file. This will automatically calculate the plan for you 209at the end of the test. If the test were to exit early then C<done_testing> 210would not run and no plan would be found, forcing a failure. 211 212=item plan($COUNT) 213 214The C<plan()> function allows you to specify an exact number of assertions you 215want to run. If you run too many or too few assertions then the plan will not 216match and it will be counted as a failure. The primary problem with this way of 217planning is that you need to add up the number of assertions, and adjust the 218count whenever you update the test file. 219 220C<plan()> must be used before all assertions, or after all assertions, it 221cannot be done in the middle of making assertions. 222 223=back 224 225=head1 ADDITIONAL ASSERTION TOOLS 226 227The L<Test2::V0> bundle provides a lot more than C<ok()>, 228C<plan()>, and C<done_testing()>. The biggest tools to note are: 229 230=over 4 231 232=item is($a, $b, $description) 233 234C<is()> allows you to compare 2 structures and insure they are identical. You 235can use it for simple string comparisons, or even deep data structure 236comparisons. 237 238 is("foo", "foo", "Both strings are identical"); 239 240 is(["foo", 1], ["foo", 1], "Both arrays contain the same elements"); 241 242=item like($a, $b, $description) 243 244C<like()> is similar to C<is()> except that it only checks items listed on the 245right, it ignores any extra values found on the left. 246 247 like([1, 2, 3, 4], [1, 2, 3], "Passes, the extra element on the left is ignored"); 248 249You can also used regular expressions on the right hand side: 250 251 like("foo bar baz", qr/bar/, "The string matches the regex, this passes"); 252 253You can also nest the regexes: 254 255 like([1, 2, 'foo bar baz', 3], [1, 2, qr/bar/], "This passes"); 256 257=back 258 259=head1 SEE ALSO 260 261L<Test2::Manual> - Primary index of the manual. 262 263=head1 SOURCE 264 265The source code repository for Test2-Manual can be found at 266F<https://github.com/Test-More/Test2-Suite/>. 267 268=head1 MAINTAINERS 269 270=over 4 271 272=item Chad Granum E<lt>exodist@cpan.orgE<gt> 273 274=back 275 276=head1 AUTHORS 277 278=over 4 279 280=item Chad Granum E<lt>exodist@cpan.orgE<gt> 281 282=back 283 284=head1 COPYRIGHT 285 286Copyright 2018 Chad Granum E<lt>exodist@cpan.orgE<gt>. 287 288This program is free software; you can redistribute it and/or 289modify it under the same terms as Perl itself. 290 291See F<http://dev.perl.org/licenses/> 292 293=cut 294