Initial Commit

database/perl/vendor/lib/Test2/Manual/Testing/Introduction.pm

@@ -0,0 +1,293 @@
+package Test2::Manual::Testing::Introduction;
+use strict;
+use warnings;
+
+our $VERSION = '0.000139';
+
+1;
+
+__END__
+
+=head1 NAME
+
+Test2::Manual::Testing::Introduction - Introduction to testing with Test2.
+
+=head1 DESCRIPTION
+
+This tutorial is a beginners introduction to testing. This will take you
+through writing a test file, making assertions, and running your test.
+
+=head1 BOILERPLATE
+
+=head2 THE TEST FILE
+
+Test files typically are placed inside the C<t/> directory, and end with the
+C<.t> file extension.
+
+C<t/example.t>:
+
+    use Test2::V0;
+
+    # Assertions will go here
+
+    done_testing;
+
+This is all the boilerplate you need.
+
+=over 4
+
+=item use Test2::V0;
+
+This loads a collection of testing tools that will be described later in the
+tutorial. This will also turn on C<strict> and C<warnings> for you.
+
+=item done_testing;
+
+This should always be at the end of your test files. This tells L<Test2> that
+you are done making assertions. This is important as C<test2> will assume the
+test did not complete successfully without this, or some other form of test
+"plan".
+
+=back
+
+=head2 DIST CONFIG
+
+You should always list bundles and tools directly. You should not simply list
+L<Test2::Suite> and call it done, bundles and tools may be moved out of
+L<Test2::Suite> to their own dists at any time.
+
+=head3 Dist::Zilla
+
+    [Prereqs / TestRequires]
+    Test2::V0 = 0.000060
+
+=head3 ExtUtils::MakeMaker
+
+    my %WriteMakefileArgs = (
+      ...,
+      "TEST_REQUIRES" => {
+        "Test2::V0" => "0.000060"
+      },
+      ...
+    );
+
+=head3 Module::Install
+
+    test_requires 'Test2::V0' => '0.000060';
+
+=head3 Module::Build
+
+    my $build = Module::Build->new(
+        ...,
+        test_requires => {
+            "Test2::V0" => "0.000060",
+        },
+        ...
+    );
+
+=head1 MAKING ASSERTIONS
+
+The most simple tool for making assertions is C<ok()>. C<ok()> lets you assert
+that a condition is true.
+
+    ok($CONDITION, "Description of the condition");
+
+Here is a complete C<t/example.t>:
+
+    use Test2::V0;
+
+    ok(1, "1 is true, so this will pass");
+
+    done_testing;
+
+=head1 RUNNING THE TEST
+
+Test files are simply scripts. Just like any other script you can run the test
+directly with perl. Another option is to use a test "harness" which runs the
+test for you, and provides extra information and checks the scripts exit value
+for you.
+
+=head2 RUN DIRECTLY
+
+    $ perl -Ilib t/example.t
+
+Which should produce output like this:
+
+    # Seeded srand with seed '20161028' from local date.
+    ok 1 - 1 is true, so this will pass
+    1..1
+
+If the test had failed (C<ok(0, ...)>) it would look like this:
+
+    # Seeded srand with seed '20161028' from local date.
+    not ok 1 - 0 is false, so this will fail
+    1..1
+
+Test2 will also set the exit value of the script, a successful run will have an
+exit value of 0, a failed run will have a non-zero exit value.
+
+=head2 USING YATH
+
+The C<yath> command line tool is provided by L<Test2::Harness> which you may
+need to install yourself from cpan. C<yath> is the harness written specifically
+for L<Test2>.
+
+    $ yath -Ilib t/example.t
+
+This will produce output similar to this:
+
+    ( PASSED )  job  1    t/example.t
+
+    ================================================================================
+
+    Run ID: 1508027909
+
+    All tests were successful!
+
+You can also request verbose output with the C<-v> flag:
+
+    $ yath -Ilib -v t/example.t
+
+Which produces:
+
+    ( LAUNCH )  job  1    example.t
+    (  NOTE  )  job  1    Seeded srand with seed '20171014' from local date.
+    [  PASS  ]  job  1  + 1 is true, so this will pass
+    [  PLAN  ]  job  1    Expected asserions: 1
+    ( PASSED )  job  1    example.t
+
+    ================================================================================
+
+    Run ID: 1508028002
+
+    All tests were successful!
+
+=head2 USING PROVE
+
+The C<prove> command line tool is provided by the L<Test::Harness> module which
+comes with most versions of perl. L<Test::Harness> is dual-life, which means
+you can also install the latest version from cpan.
+
+    $ prove -Ilib t/example.t
+
+This will produce output like this:
+
+    example.t .. ok
+    All tests successful.
+    Files=1, Tests=1,  0 wallclock secs ( 0.01 usr  0.00 sys +  0.05 cusr  0.00 csys =  0.06 CPU)
+    Result: PASS
+
+You can also request verbose output with the C<-v> flag:
+
+    $ prove -Ilib -v t/example.t
+
+The verbose output looks like this:
+
+    example.t ..
+    # Seeded srand with seed '20161028' from local date.
+    ok 1 - 1 is true, so this will pass
+    1..1
+    ok
+    All tests successful.
+    Files=1, Tests=1,  0 wallclock secs ( 0.02 usr  0.00 sys +  0.06 cusr  0.00 csys =  0.08 CPU)
+    Result: PASS
+
+=head1 THE "PLAN"
+
+All tests need a "plan". The job of a plan is to make sure you ran all the
+tests you expected. The plan prevents a passing result from a test that exits
+before all the tests are run.
+
+There are 2 primary ways to set the plan:
+
+=over 4
+
+=item done_testing()
+
+The most common, and recommended way to set a plan is to add C<done_testing> at
+the end of your test file. This will automatically calculate the plan for you
+at the end of the test. If the test were to exit early then C<done_testing>
+would not run and no plan would be found, forcing a failure.
+
+=item plan($COUNT)
+
+The C<plan()> function allows you to specify an exact number of assertions you
+want to run. If you run too many or too few assertions then the plan will not
+match and it will be counted as a failure. The primary problem with this way of
+planning is that you need to add up the number of assertions, and adjust the
+count whenever you update the test file.
+
+C<plan()> must be used before all assertions, or after all assertions, it
+cannot be done in the middle of making assertions.
+
+=back
+
+=head1 ADDITIONAL ASSERTION TOOLS
+
+The L<Test2::V0> bundle provides a lot more than C<ok()>,
+C<plan()>, and C<done_testing()>. The biggest tools to note are:
+
+=over 4
+
+=item is($a, $b, $description)
+
+C<is()> allows you to compare 2 structures and insure they are identical. You
+can use it for simple string comparisons, or even deep data structure
+comparisons.
+
+    is("foo", "foo", "Both strings are identical");
+
+    is(["foo", 1], ["foo", 1], "Both arrays contain the same elements");
+
+=item like($a, $b, $description)
+
+C<like()> is similar to C<is()> except that it only checks items listed on the
+right, it ignores any extra values found on the left.
+
+    like([1, 2, 3, 4], [1, 2, 3], "Passes, the extra element on the left is ignored");
+
+You can also used regular expressions on the right hand side:
+
+    like("foo bar baz", qr/bar/, "The string matches the regex, this passes");
+
+You can also nest the regexes:
+
+    like([1, 2, 'foo bar baz', 3], [1, 2, qr/bar/], "This passes");
+
+=back
+
+=head1 SEE ALSO
+
+L<Test2::Manual> - Primary index of the manual.
+
+=head1 SOURCE
+
+The source code repository for Test2-Manual can be found at
+F<https://github.com/Test-More/Test2-Suite/>.
+
+=head1 MAINTAINERS
+
+=over 4
+
+=item Chad Granum E<lt>exodist@cpan.orgE<gt>
+
+=back
+
+=head1 AUTHORS
+
+=over 4
+
+=item Chad Granum E<lt>exodist@cpan.orgE<gt>
+
+=back
+
+=head1 COPYRIGHT
+
+Copyright 2018 Chad Granum E<lt>exodist@cpan.orgE<gt>.
+
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+See F<http://dev.perl.org/licenses/>
+
+=cut