=pod

=encoding UTF-8

=head1 NAME

Test::Tutorial::WritingTests - A Complete Introduction to writing tests

=head1 What are tests?

Tests are code that verifies other code produces the expected output for a
given input. An example may help:

    # This code will die if math doesbn't work.
    die "Math is broken" unless 1 + 1 == 2;

However it is better to use a framework intended for testing:

    ok( 1 + 1 == 2, "Math Works" );

This will tell you if the test passes or fails, and will give you extra
information like the name of the test, and what line it was written on if it
fails.

=head1 Simple example.

    use Test::More;

    ok( 1, "1 is true, this test will pass" );
    ok( 0, "0 is false, this test will fail" );

    is( 1 + 1, 2, "1 + 1 == 2" );

    my @array = first_3_numbers();

    is_deeply(
        \@array,
        [ 1, 2, 3 ],
        "function returned an array of 3 numbers"
    );

    # When you are done, call this to satisfy the plan
    done_testing

See L<Test::More> for C<ok()>, C<is()>, C<is_deeply()>, and several other
useful tools.

=head1 What is a plan?

You need to declare how many tests should be seen, this is to ensure your test
does not die partway through. There are 2 ways to declare a plan, 1 way to
decline to make a plan, and a way to skip everything.

=over 4

=item done_testing

    use Test::More;

    ok(1, "pass");

    done_testing;

Using done_testing means you do not need to update the plan every time you
change your test script.

=item Test count

At import:

    use Test::More tests => 1;
    ok(1, "pass");

Plan on its own:

    use Test::More;
    plan tests => 1;
    ok(1, "pass");

=item No Plan

    use Test::More 'no_plan';

No plan, no way to verify everything ran.

=item skip_all

    use Test::More skip_all => "We won't run these now";

Just don't do anything.

=back

=head1 See Also

L<Test::More>

=head1 Writing tools.

See L<Test::Tutorial::WritingTools>

=head1 SOURCE

The source code repository for Test::More can be found at
F<http://github.com/Test-More/test-more/>.

=head1 MAINTAINER

=over 4

=item Chad Granum E<lt>exodist@cpan.orgE<gt>

=back

=head1 AUTHORS

The following people have all contributed to the Test-More dist (sorted using
VIM's sort function).

=over 4

=item Chad Granum E<lt>exodist@cpan.orgE<gt>

=item Fergal Daly E<lt>fergal@esatclear.ie>E<gt>

=item Mark Fowler E<lt>mark@twoshortplanks.comE<gt>

=item Michael G Schwern E<lt>schwern@pobox.comE<gt>

=item 唐鳳

=back

=head1 COPYRIGHT

There has been a lot of code migration between modules,
here are all the original copyrights together:

=over 4

=item Test::Stream

=item Test::Stream::Tester

Copyright 2014 Chad Granum E<lt>exodist7@gmail.comE<gt>.

This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

See F<http://www.perl.com/perl/misc/Artistic.html>

=item Test::Simple

=item Test::More

=item Test::Builder

Originally authored by Michael G Schwern E<lt>schwern@pobox.comE<gt> with much
inspiration from Joshua Pritikin's Test module and lots of help from Barrie
Slaymaker, Tony Bowden, blackstar.co.uk, chromatic, Fergal Daly and the perl-qa
gang.

Idea by Tony Bowden and Paul Johnson, code by Michael G Schwern
E<lt>schwern@pobox.comE<gt>, wardrobe by Calvin Klein.

Copyright 2001-2008 by Michael G Schwern E<lt>schwern@pobox.comE<gt>.

This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

See F<http://www.perl.com/perl/misc/Artistic.html>

=item Test::use::ok

To the extent possible under law, 唐鳳 has waived all copyright and related
or neighboring rights to L<Test-use-ok>.

This work is published from Taiwan.

L<http://creativecommons.org/publicdomain/zero/1.0>

=item Test::Tester

This module is copyright 2005 Fergal Daly <fergal@esatclear.ie>, some parts
are based on other people's work.

Under the same license as Perl itself

See http://www.perl.com/perl/misc/Artistic.html

=item Test::Builder::Tester

Copyright Mark Fowler E<lt>mark@twoshortplanks.comE<gt> 2002, 2004.

This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.

=back
