1Test2(3)              User Contributed Perl Documentation             Test2(3)
2
3
4

NAME

6       Test2 - Framework for writing test tools that all work together.
7

DESCRIPTION

9       Test2 is a new testing framework produced by forking Test::Builder,
10       completely refactoring it, adding many new features and capabilities.
11
12   WHAT IS NEW?
13       Easier to test new testing tools.
14           From the beginning Test2 was built with introspection capabilities.
15           With Test::Builder it was difficult at best to capture test tool
16           output for verification. Test2 Makes it easy with
17           Test2::API::intercept().
18
19       Better diagnostics capabilities.
20           Test2 uses an Test2::API::Context object to track filename, line
21           number, and tool details. This object greatly simplifies tracking
22           for where errors should be reported.
23
24       Event driven.
25           Test2 based tools produce events which get passed through a
26           processing system before being output by a formatter. This event
27           system allows for rich plugin and extension support.
28
29       More complete API.
30           Test::Builder only provided a handful of methods for generating
31           lines of TAP.  Test2 took inventory of everything people were doing
32           with Test::Builder that required hacking it up. Test2 made public
33           API functions for nearly all the desired functionality people
34           didn't previously have.
35
36       Support for output other than TAP.
37           Test::Builder assumed everything would end up as TAP. Test2 makes
38           no such assumption. Test2 provides ways for you to specify
39           alternative and custom formatters.
40
41       Subtest implementation is more sane.
42           The Test::Builder implementation of subtests was certifiably
43           insane. Test2 uses a stacked event hub system that greatly improves
44           how subtests are implemented.
45
46       Support for threading/forking.
47           Test2 support for forking and threading can be turned on using
48           Test2::IPC.  Once turned on threading and forking operate sanely
49           and work as one would expect.
50

GETTING STARTED

52       If you are interested in writing tests using new tools then you should
53       look at Test2::Suite. Test2::Suite is a separate cpan distribution that
54       contains many tools implemented on Test2.
55
56       If you are interested in writing new tools you should take a look at
57       Test2::API first.
58

NAMESPACE LAYOUT

60       This describes the namespace layout for the Test2 ecosystem. Not all
61       the namespaces listed here are part of the Test2 distribution, some are
62       implemented in Test2::Suite.
63
64   Test2::Tools::
65       This namespace is for sets of tools. Modules in this namespace should
66       export tools like ok() and is(). Most things written for Test2 should
67       go here.  Modules in this namespace MUST NOT export subs from other
68       tools. See the "Test2::Bundle::" namespace if you want to do that.
69
70   Test2::Plugin::
71       This namespace is for plugins. Plugins are modules that change or
72       enhance the behavior of Test2. An example of a plugin is a module that
73       sets the encoding to utf8 globally. Another example is a module that
74       causes a bail-out event after the first test failure.
75
76   Test2::Bundle::
77       This namespace is for bundles of tools and plugins. Loading one of
78       these may load multiple tools and plugins. Modules in this namespace
79       should not implement tools directly. In general modules in this
80       namespace should load tools and plugins, then re-export things into the
81       consumers namespace.
82
83   Test2::Require::
84       This namespace is for modules that cause a test to be skipped when
85       conditions do not allow it to run. Examples would be modules that skip
86       the test on older perls, or when non-essential modules have not been
87       installed.
88
89   Test2::Formatter::
90       Formatters live under this namespace. Test2::Formatter::TAP is the only
91       formatter currently. It is acceptable for third party distributions to
92       create new formatters under this namespace.
93
94   Test2::Event::
95       Events live under this namespace. It is considered acceptable for third
96       party distributions to add new event types in this namespace.
97
98   Test2::Hub::
99       Hub subclasses (and some hub utility objects) live under this
100       namespace. It is perfectly reasonable for third party distributions to
101       add new hub subclasses in this namespace.
102
103   Test2::IPC::
104       The IPC subsystem lives in this namespace. There are not many good
105       reasons to add anything to this namespace, with exception of IPC
106       drivers.
107
108       Test2::IPC::Driver::
109
110       IPC drivers live in this namespace. It is fine to create new IPC
111       drivers and to put them in this namespace.
112
113   Test2::Util::
114       This namespace is for general utilities used by testing tools. Please
115       be considerate when adding new modules to this namespace.
116
117   Test2::API::
118       This is for Test2 API and related packages.
119
120   Test2::
121       The Test2:: namespace is intended for extensions and frameworks. Tools,
122       Plugins, etc should not go directly into this namespace. However
123       extensions that are used to build tools and plugins may go here.
124
125       In short: If the module exports anything that should be run directly by
126       a test script it should probably NOT go directly into "Test2::XXX".
127

SEE ALSO

129       Test2::API - Primary API functions.
130
131       Test2::API::Context - Detailed documentation of the context object.
132
133       Test2::IPC - The IPC system used for threading/fork support.
134
135       Test2::Formatter - Formatters such as TAP live here.
136
137       Test2::Event - Events live in this namespace.
138
139       Test2::Hub - All events eventually funnel through a hub. Custom hubs
140       are how intercept() and run_subtest() are implemented.
141

CONTACTING US

143       Many Test2 developers and users lurk on <irc://irc.perl.org/#perl-qa>
144       and <irc://irc.perl.org/#toolchain>. We also have a slack team that can
145       be joined by anyone with an "@cpan.org" email address
146       <https://perl-test2.slack.com/> If you do not have an "@cpan.org" email
147       you can ask for a slack invite by emailing Chad Granum
148       <exodist@cpan.org>.
149

SOURCE

151       The source code repository for Test2 can be found at
152       http://github.com/Test-More/test-more/.
153

MAINTAINERS

155       Chad Granum <exodist@cpan.org>
156

AUTHORS

158       Chad Granum <exodist@cpan.org>
159

COPYRIGHT

161       Copyright 2020 Chad Granum <exodist@cpan.org>.
162
163       This program is free software; you can redistribute it and/or modify it
164       under the same terms as Perl itself.
165
166       See http://dev.perl.org/licenses/
167
168
169
170perl v5.38.0                      2023-07-21                          Test2(3)