Permalink
Browse files

Fleshing it out

  • Loading branch information...
exodist committed Oct 15, 2017
1 parent 6c71884 commit eb5c04aee1d7a64246670030da9ba57d273b3e3f
View
@@ -24,6 +24,10 @@ writing tests.
The L<Test2::Manual::Tooling> POD is the hub for documentation related to
writing new tools.
=head1 END TO END
The L<Test2::Manual::EndToEnd> is an overview of Test2 from load to finish.
=head1 CONTRIBUTING
The L<Test2::Manual::Contributing> POD is for people who want to contribute to
@@ -0,0 +1,113 @@
package Test2::Manual::Contributing;
1;
__END__
=head1 NAME
Test2::Manual::Contributing - How to contribute to the Test2 project.
=head1 DESCRIPTION
This is a short manual page dedicated to helping people who wish to contribute
to the Test2 project.
=head1 WAYS TO HELP
=head2 REPORT BUGS
The easiest way to help is to report bugs when you find them. Bugs are a fact
of life when writing or using software. If you use Test2 long enough you are
likely to find a bug. When you find such a bug it would help us out if you
would submit a ticket.
=head3 BUG TRACKERS
Always try to find the preferred bug tracker for the module that has the bug.
Here are the big 3 for the main Test2 project:
=over 4
=item Test2/Test-Builder/Test-More
L<https://github.com/Test-More/test-more/issues>
=item Test2-Suite
L<https://github.com/Test-More/Test2-Suite/issues>
=item Test2-Harness
L<https://github.com/Test-More/Test2-Harness/issues>
=back
=head2 SUBMIT PATCHES
You are welcome to fix bugs you find, or from the tracker. We also often accept
patches that add new features or update documentation. The preferred method of
submitting patches is a github pull request, that said we also accept patches
via email.
=head2 ADD/UPDATE DOCUMENTATION
Documentation can be flawed just like code can be. Documentation can also
become outdated. If you see some incorrect documentation, or documentation that
is missing, we would love to get a patch to fix it!
=head2 ANSWER QUESTIONS ON IRC/SLACK
We are always hanging out on L<irc://irc.perl.org>, the #perl-qa and #toolchain
channels are a good place to find us.
There is also a Test2 slack channel: L<https://perl-test2.slack.com>.
=head2 WRITE NEW TOOLS USING TEST2
Writing a new tool using Test2 is always a good way to contribute. When you
write a tool that you think is useful, it is nice to share it by putting it on
CPAN.
=head2 PORT OLD TOOLS TO TEST2
The C<Test::*> namespace has been around for a long time, and has a LOT of
tools. The C<Test2::Tools::*> namespace is fairly young, and has less tools.
Finding a useful old tool with no modern equivelent, and writing a port is a
very good use of your time.
=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<http://github.com/Test-More/Test2-Manual/>.
=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 2017 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
@@ -2,6 +2,8 @@ package Test2::Manual::EndToEnd;
use strict;
use warnings;
1;
__END__
=head1 NAME
@@ -168,14 +170,21 @@ You have a shiney new context object, or a clone of the existing context.
=item The Test2::Event::Ok module is loaded.
The C<send_event()> method will automatically load any Event package necessary.
Normally C<send_event()> will assume the first argument is an event class
without the C<Test2::Event::> prefix, which it will add for you. If you want to
use an event class that is in a different namespace you can prefix the class
name with a C<+> to tell the tool that you are giving a fully qualified class
name:
my $event = $ctx->send_event('+Fully::Qualified::Event', pass => $bool, name => $name);
=item A new instance of Test2::Event::Ok is created.
The event object is instantiated using the provided parameters.
=item The event object is sent to the hub.
The hub taks over from here.
The hub takes over from here.
=item The hub runs the event through any filters.
@@ -253,7 +262,7 @@ If IPC is turned on, a final culling will take place.
The follow-up hooks are a way to run actions when a hub is complete. This is
useful for adding cleanup tasks, or final tests to the end of a test.
=item The final plan even is generated and processed.
=item The final plan event is generated and processed.
The final plan event will be produced using the current test count as the
number of tests planned.
@@ -37,9 +37,10 @@ lexically scoped, or they may be global.
=item Test2::Bundle::*
Bundles combine toolsets and plugins together to reduce your boilerplate. First
time test writers are encouraged to start with the L<Test2::Bundle::Extended>
bundle. If you find yourself loading several plugins and toolsets over and over
again you could benefit from writing your own bundle.
time test writers are encouraged to start with the L<Test2::V0> bundle (which
is an exception to the namespace rule as it does not live under
C<Test2::Bundle::>). If you find yourself loading several plugins and toolsets
over and over again you could benefit from writing your own bundle.
=item Test2::Require::*
@@ -66,47 +67,47 @@ and define new ones, typically with a new bundle. In short, if we feel the need
to break something we will do so by creating a new bundle, and discouraging the
old one, but we will not break the old one.
So for example, if you use L<Test2::Bundle::Extended>, and L<Dist::Zilla> you
So for example, if you use L<Test2::V0>, and L<Dist::Zilla> you
should have this in your config:
[Prereqs / TestRequires]
Test2::Bundle::Extended = 0.000060
Test2::V0 = 0.000060
You B<SHOULD NOT> do this:
[Prereqs / TestRequires]
Test2::Suite = 0.000060
Because L<Test2::Bundle::Extended> might not always be part of L<Test2::Suite>.
Because L<Test2::V0> might not always be part of L<Test2::Suite>.
When writing new tests you should often check L<Test2::Suite> to see what the
current recommended bundle is.
=head3 Dist::Zilla
[Prereqs / TestRequires]
Test2::Bundle::Extended = 0.000060
Test2::V0 = 0.000060
=head3 ExtUtils::MakeMaker
my %WriteMakefileArgs = (
...,
"TEST_REQUIRES" => {
"Test2::Bundle::Extended" => "0.000060"
"Test2::V0" => "0.000060"
},
...
);
=head3 Module::Install
test_requires 'Test2::Bundle::Extended' => '0.000060';
test_requires 'Test2::V0' => '0.000060';
=head3 Module::Build
my $build = Module::Build->new(
...,
test_requires => {
"Test2::Bundle::Extended" => "0.000060",
"Test2::V0" => "0.000060",
},
...
);
@@ -118,6 +119,12 @@ current recommended bundle is.
L<Test2::Manual::Testing::Introduction> is an introduction to writing tests
using the L<Test2> tools.
=head2 MIGRATING FROM TEST::BUILDER and TEST::MORE
L<Test2::Manual::Testing::Migrating> Is a tutorial for converting old tests
that use L<Test2::Builder> or L<Test::More> to the newer L<Test2> way of doing
things.
=head2 ADVANCED PLANNING
L<Test2::Manual::Testing::Planning> is a tutorial on the many ways to set a
@@ -133,12 +140,8 @@ L<Test2::Manual::Testing::Todo> is a tutorial for markings tests as TODO.
=head3 SIMPLE COMPARISONS
* Include refs
=head3 ADVANCED COMPARISONS
* Deep strucutres, DSL
=head2 TESTING EXPORTERS
=head2 TESTING CLASSES
@@ -159,10 +162,6 @@ L<Test2::Manual::Testing::Todo> is a tutorial for markings tests as TODO.
=head2 WRITING YOUR OWN BUNDLE
=head2 TESTING YOUR TEST TOOLS
* Also covered in the Tooling section.
=head1 TOOLSET DOCUMENTATION
=head1 PLUGIN DOCUMENTATION
@@ -24,7 +24,7 @@ C<.t> file extension.
C<t/example.t>:
use Test2::Bundle::Extended;
use Test2::V0;
# Assertions will go here
@@ -34,7 +34,7 @@ This is all the boilerplate you need.
=over 4
=item use Test2::Bundle::Extended;
=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.
@@ -57,28 +57,28 @@ L<Test2::Suite> to their own dists at any time.
=head3 Dist::Zilla
[Prereqs / TestRequires]
Test2::Bundle::Extended = 0.000060
Test2::V0 = 0.000060
=head3 ExtUtils::MakeMaker
my %WriteMakefileArgs = (
...,
"TEST_REQUIRES" => {
"Test2::Bundle::Extended" => "0.000060"
"Test2::V0" => "0.000060"
},
...
);
=head3 Module::Install
test_requires 'Test2::Bundle::Extended' => '0.000060';
test_requires 'Test2::V0' => '0.000060';
=head3 Module::Build
my $build = Module::Build->new(
...,
test_requires => {
"Test2::Bundle::Extended" => "0.000060",
"Test2::V0" => "0.000060",
},
...
);
@@ -92,7 +92,7 @@ that a condition is true.
Here is a complete C<t/example.t>:
use Test2::Bundle::Extended;
use Test2::V0;
ok(1, "1 is true, so this will pass");
@@ -134,25 +134,31 @@ for L<Test2>.
This will produce output similar to this:
[PASSED] = example.t
( PASSED ) job 1 t/example.t
=== ALL TESTS SUCCEEDED ===
================================================================================
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] _ example.t
[PARSER] + Test2::Harness::Parser::EventStream
[ NOTE ] + Seeded srand with seed '20161028' from local date.
[ENCODE] + utf8
[ OK ] + 1 is true, so this will pass
[ PLAN ] + Plan is 1 assertions
[PASSED] = example.t
( 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 SUCCEEDED ===
All tests were successful!
=head2 USING PROVE
@@ -216,7 +222,7 @@ cannot be done in the middle of making assertions.
=head1 ADDITONAL ASSERTION TOOLS
The L<Test2::Bundle::Extended> bundle provides a lot more than C<ok()>,
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
Oops, something went wrong.

0 comments on commit eb5c04a

Please sign in to comment.