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