1Test::Stream::Manual::TUosoelrinCgo(n3t)ributed Perl DocTuemsetn:t:aSttiroenam::Manual::Tooling(3)
2
3
4

NAME

6       Test::Stream::Manual::Tooling - How to write test tools using the
7       Test::Stream infrastructure.
8

DESCRIPTION

10       This manual page explains the process of building a test tool using
11       Test::Stream.
12

QUICK START

14       If you wantd to write a module that implemented the ok() function, this
15       is all you need to write:
16
17           package Test::Stream::Plugin::MyOk;
18           use strict;
19           use warnings;
20
21           use Test::Stream::Context qw/context/;
22
23           use Test::Stream::Exporter;
24           default_exports qw/ok/;
25           no Test::Stream::Exporter;
26
27           sub ok($;$) {
28               my ($bool, $name) = @_;    # Get args
29
30               my $ctx = context();       # Obtain a context
31
32               $ctx->ok($bool, $name);    # Issue an OK event
33
34               $ctx->release;             # Release the context
35
36               return $bool;              # Return the true/false
37           }
38
39           1;
40
41   EXPLANATION
42       Obtaining a context
43           This is the MOST critical thing you need to do in any testing tool.
44           You should do this as soon as possible. The Test::Stream::Context
45           object ties everything together. Obtaining a context object locks
46           in the file and line number to which errors should be reported. It
47           also finds the current hub to which all events should be sent.
48           Finally the context object is the primary interface used to
49           generate events. In short the context object is the tool builders
50           1-stop shop.
51
52       Issue an Ok event
53           The core event types, "ok", "note", "diag", "bail", and "plan" have
54           shortcut functions on the context object. These shortcut functions
55           construct the event, and send it to the hub for processing. Other
56           event types can be generated as well using the
57           "$ctx->build_event(...)" or "$ctx->send_event(...)" methods. See
58           the Test::Stream::Context object documentation for additional
59           details.
60
61       Release the context
62           When your tool is finished it is very important that you release
63           the context.  Failing to release the context would result in a leak
64           condition. In most cases the context will detect this condition and
65           take measures to correct it, along with issuing a very verbose
66           warning.
67
68       Return the true/false
69           Typically testing tools will return a true or false indicating if
70           the test has passed or failed.
71

ADVANCED

73       This covers more advanced topics for tool builders.
74
75   EVENTS
76       Most testing tools generate events. The most common event generated is
77       the Test::Stream::Event::Ok event. In addition it is possible for tools
78       to create their own event types.
79
80   CONTEXT
81       The Test::Stream::Context object ties everything together. Obtaining a
82       context object locks in the file and line number to which errors should
83       be reported. It also finds the current hub to which all events should
84       be sent. Finally the context object is the primary interface used to
85       generate events. In short the context object is the tool builders
86       1-stop shop.
87
88       There is only ever one canonical context instance per active hub. If
89       two tools try to obtain a context in the same stack they will both get
90       the same one, the first one to request it generates it, the second gets
91       the existing instance. In both cases the tool MUST release it when
92       done. Tools should never send contexts to other tools, and they should
93       never accept them as arguments. Tools that get broken up into multiple
94       functions may pass the context to their component subs.
95
96   DEBUGINFO
97       Test::Stream::DebugInfo objects are stored inside the context object,
98       its job is to store filename and line number for errors. It can also be
99       used to issue warnings and throw exceptions. Every event generated
100       needs to have a DebugInfo object, typically cloned from the one in the
101       context object.
102
103   HUBS
104       Test::Stream::Hub objects are responsible for 2 things, the first is
105       tracking state. Hubs have an instance of an Test::Stream::State object.
106       When an event is processed by a hub the state will be updated
107       accordingly.
108
109       The second job of a hub is to make sure events get to the right place.
110       Typically this means processing the event through any 'filters', then
111       handing them off to the formatter, then finally running them through
112       'listeners'.
113
114       When IPC is active the hub will use the IPC driver (See
115       Test::Stream::IPC) to send events to the correct process or thread.
116
117   HUB STACK
118       There is a single canonical Test::Stream::Stack instance tracked by the
119       Test::Stream::Sync package. When a context is obtained it will
120       reference whatever hub is on the top of the stack at the time it is
121       created. Typically all events will be sent to the topmost hub.
122
123   SYNC
124       The Test::Stream::Sync package is the place where all shared state is
125       tracked. Part of Test::Streams design is reducing shared state to the
126       bare minimum. This class is kept as small as possible while still
127       achieving the necessary functionality. The sync package tracks IPC
128       drivers, formatter, the hub stack, and some global hooks.
129
130   EXPORTER
131       Test::Stream::Exporter is an export tool built-in to Test::Stream.
132       Test::Stream requires export functionality well beyond what Exporter.pm
133       is able to provide. In addition a plugin that does not need special
134       import functionality can simply use Test::Stream::Exporter to work as a
135       plugin.
136
137   CAPABILITIES
138       Test::Stream::Capabilities can be used to guage the active systems fork
139       and/or thread support levels.
140
141   UTILITIES
142       The Test::Stream::Util package exports many useful functions for test
143       authors.
144
145   PLUGINS
146       Plugins can either use Test::Stream::Export or they can use
147       Test::Stream::Plugin and implement the load_ts_plugin() method.
148
149   BUNDLES
150       Bundles are used to combine several plugins into a single module that
151       can be used to load them all at once. This is the better alternative to
152       the Test::Builder practice of having tools load eachother.
153

SOURCE

155       The source code repository for Test::Stream can be found at
156       http://github.com/Test-More/Test-Stream/.
157

MAINTAINERS

159       Chad Granum <exodist@cpan.org>
160

AUTHORS

162       Chad Granum <exodist@cpan.org>
163
165       Copyright 2015 Chad Granum <exodist7@gmail.com>.
166
167       This program is free software; you can redistribute it and/or modify it
168       under the same terms as Perl itself.
169
170       See http://dev.perl.org/licenses/
171
172
173
174perl v5.36.0                      2023-01-20  Test::Stream::Manual::Tooling(3)
Impressum