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

SEE ALSO

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

CONTACTING US

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

SOURCE

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

MAINTAINERS

156       Chad Granum <exodist@cpan.org>
157

AUTHORS

159       Chad Granum <exodist@cpan.org>
160

COPYRIGHT

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