Commit | Line | Data |
---|---|---|
b4514920 CG |
1 | package Test2; |
2 | use strict; | |
3 | use warnings; | |
4 | ||
43de38c4 | 5 | our $VERSION = '1.302133'; |
b4514920 CG |
6 | |
7 | ||
8 | 1; | |
9 | ||
10 | __END__ | |
11 | ||
12 | =pod | |
13 | ||
14 | =encoding UTF-8 | |
15 | ||
16 | =head1 NAME | |
17 | ||
18 | Test2 - Framework for writing test tools that all work together. | |
19 | ||
20 | =head1 DESCRIPTION | |
21 | ||
22 | Test2 is a new testing framework produced by forking L<Test::Builder>, | |
23 | completely refactoring it, adding many new features and capabilities. | |
24 | ||
7aa7bbc7 SH |
25 | =head2 WHAT IS NEW? |
26 | ||
27 | =over 4 | |
28 | ||
29 | =item Easier to test new testing tools. | |
30 | ||
31 | From the beginning Test2 was built with introspection capabilities. With | |
32 | Test::Builder it was difficult at best to capture test tool output for | |
33 | verification. Test2 Makes it easy with C<Test2::API::intercept()>. | |
34 | ||
35 | =item Better diagnostics capabilities. | |
36 | ||
37 | Test2 uses an L<Test2::API::Context> object to track filename, line number, and | |
38 | tool details. This object greatly simplifies tracking for where errors should | |
39 | be reported. | |
40 | ||
41 | =item Event driven. | |
42 | ||
43 | Test2 based tools produce events which get passed through a processing system | |
44 | before being output by a formatter. This event system allows for rich plugin | |
45 | and extension support. | |
46 | ||
47 | =item More complete API. | |
48 | ||
49 | Test::Builder only provided a handful of methods for generating lines of TAP. | |
50 | Test2 took inventory of everything people were doing with Test::Builder that | |
51 | required hacking it up. Test2 made public API functions for nearly all the | |
52 | desired functionality people didn't previously have. | |
53 | ||
54 | =item Support for output other than TAP. | |
55 | ||
56 | Test::Builder assumed everything would end up as TAP. Test2 makes no such | |
57 | assumption. Test2 provides ways for you to specify alternative and custom | |
58 | formatters. | |
59 | ||
60 | =item Subtest implementation is more sane. | |
61 | ||
62 | The Test::Builder implementation of subtests was certifiably insane. Test2 uses | |
63 | a stacked event hub system that greatly improves how subtests are implemented. | |
64 | ||
65 | =item Support for threading/forking. | |
66 | ||
67 | Test2 support for forking and threading can be turned on using L<Test2::IPC>. | |
68 | Once turned on threading and forking operate sanely and work as one would | |
69 | expect. | |
70 | ||
71 | =back | |
72 | ||
b4514920 CG |
73 | =head1 GETTING STARTED |
74 | ||
75 | If you are interested in writing tests using new tools then you should look at | |
7aa7bbc7 | 76 | L<Test2::Suite>. L<Test2::Suite> is a separate cpan distribution that contains |
b4514920 CG |
77 | many tools implemented on Test2. |
78 | ||
79 | If you are interested in writing new tools you should take a look at | |
80 | L<Test2::API> first. | |
81 | ||
82 | =head1 NAMESPACE LAYOUT | |
83 | ||
84 | This describes the namespace layout for the Test2 ecosystem. Not all the | |
85 | namespaces listed here are part of the Test2 distribution, some are implemented | |
86 | in L<Test2::Suite>. | |
87 | ||
88 | =head2 Test2::Tools:: | |
89 | ||
90 | This namespace is for sets of tools. Modules in this namespace should export | |
91 | tools like C<ok()> and C<is()>. Most things written for Test2 should go here. | |
92 | Modules in this namespace B<MUST NOT> export subs from other tools. See the | |
93 | L</Test2::Bundle::> namespace if you want to do that. | |
94 | ||
95 | =head2 Test2::Plugin:: | |
96 | ||
97 | This namespace is for plugins. Plugins are modules that change or enhance the | |
98 | behavior of Test2. An example of a plugin is a module that sets the encoding to | |
99 | utf8 globally. Another example is a module that causes a bail-out event after | |
100 | the first test failure. | |
101 | ||
102 | =head2 Test2::Bundle:: | |
103 | ||
104 | This namespace is for bundles of tools and plugins. Loading one of these may | |
105 | load multiple tools and plugins. Modules in this namespace should not implement | |
106 | tools directly. In general modules in this namespace should load tools and | |
107 | plugins, then re-export things into the consumers namespace. | |
108 | ||
109 | =head2 Test2::Require:: | |
110 | ||
111 | This namespace is for modules that cause a test to be skipped when conditions | |
112 | do not allow it to run. Examples would be modules that skip the test on older | |
113 | perls, or when non-essential modules have not been installed. | |
114 | ||
115 | =head2 Test2::Formatter:: | |
116 | ||
117 | Formatters live under this namespace. L<Test2::Formatter::TAP> is the only | |
58818a66 | 118 | formatter currently. It is acceptable for third party distributions to create |
b4514920 CG |
119 | new formatters under this namespace. |
120 | ||
121 | =head2 Test2::Event:: | |
122 | ||
58818a66 | 123 | Events live under this namespace. It is considered acceptable for third party |
b4514920 CG |
124 | distributions to add new event types in this namespace. |
125 | ||
126 | =head2 Test2::Hub:: | |
127 | ||
128 | Hub subclasses (and some hub utility objects) live under this namespace. It is | |
129 | perfectly reasonable for third party distributions to add new hub subclasses in | |
130 | this namespace. | |
131 | ||
132 | =head2 Test2::IPC:: | |
133 | ||
134 | The IPC subsystem lives in this namespace. There are not many good reasons to | |
135 | add anything to this namespace, with exception of IPC drivers. | |
136 | ||
137 | =head3 Test2::IPC::Driver:: | |
138 | ||
139 | IPC drivers live in this namespace. It is fine to create new IPC drivers and to | |
140 | put them in this namespace. | |
141 | ||
142 | =head2 Test2::Util:: | |
143 | ||
144 | This namespace is for general utilities used by testing tools. Please be | |
145 | considerate when adding new modules to this namespace. | |
146 | ||
147 | =head2 Test2::API:: | |
148 | ||
149 | This is for Test2 API and related packages. | |
150 | ||
151 | =head2 Test2:: | |
152 | ||
58818a66 CG |
153 | The Test2:: namespace is intended for extensions and frameworks. Tools, |
154 | Plugins, etc should not go directly into this namespace. However extensions | |
b4514920 CG |
155 | that are used to build tools and plugins may go here. |
156 | ||
157 | In short: If the module exports anything that should be run directly by a test | |
158 | script it should probably NOT go directly into C<Test2::XXX>. | |
159 | ||
160 | =head1 SEE ALSO | |
161 | ||
162 | L<Test2::API> - Primary API functions. | |
163 | ||
164 | L<Test2::API::Context> - Detailed documentation of the context object. | |
165 | ||
166 | L<Test2::IPC> - The IPC system used for threading/fork support. | |
167 | ||
168 | L<Test2::Formatter> - Formatters such as TAP live here. | |
169 | ||
170 | L<Test2::Event> - Events live in this namespace. | |
171 | ||
172 | L<Test2::Hub> - All events eventually funnel through a hub. Custom hubs are how | |
173 | C<intercept()> and C<run_subtest()> are implemented. | |
174 | ||
022600ce SH |
175 | =head1 CONTACTING US |
176 | ||
fa951d2c CBW |
177 | Many Test2 developers and users lurk on L<irc://irc.perl.org/#perl-qa> and |
178 | L<irc://irc.perl.org/#toolchain>. We also have a slack team that can be joined | |
179 | by anyone with an C<@cpan.org> email address L<https://perl-test2.slack.com/> | |
180 | If you do not have an C<@cpan.org> email you can ask for a slack invite by | |
181 | emailing Chad Granum E<lt>exodist@cpan.orgE<gt>. | |
022600ce | 182 | |
b4514920 CG |
183 | =head1 SOURCE |
184 | ||
185 | The source code repository for Test2 can be found at | |
186 | F<http://github.com/Test-More/test-more/>. | |
187 | ||
188 | =head1 MAINTAINERS | |
189 | ||
190 | =over 4 | |
191 | ||
192 | =item Chad Granum E<lt>exodist@cpan.orgE<gt> | |
193 | ||
194 | =back | |
195 | ||
196 | =head1 AUTHORS | |
197 | ||
198 | =over 4 | |
199 | ||
200 | =item Chad Granum E<lt>exodist@cpan.orgE<gt> | |
201 | ||
202 | =back | |
203 | ||
204 | =head1 COPYRIGHT | |
205 | ||
61979647 | 206 | Copyright 2018 Chad Granum E<lt>exodist@cpan.orgE<gt>. |
b4514920 CG |
207 | |
208 | This program is free software; you can redistribute it and/or | |
209 | modify it under the same terms as Perl itself. | |
210 | ||
211 | See F<http://dev.perl.org/licenses/> | |
212 | ||
213 | =cut |