1Test::Stream::Manual::TUosoelrinCgo(n3t)ributed Perl DocTuemsetn:t:aSttiroenam::Manual::Tooling(3)
2
6 Test::Stream::Manual::Tooling - How to write test tools using the
7 Test::Stream infrastructure.
8
10 This manual page explains the process of building a test tool using
11 Test::Stream.
12
14 If you wantd to write a module that implemented the ok() function, this
15 is all you need to write:
16 package Test::Stream::Plugin::MyOk;
18 use strict;
19 use warnings;
20 use Test::Stream::Context qw/context/;
22 use Test::Stream::Exporter;
24 default_exports qw/ok/;
25 no Test::Stream::Exporter;
26 sub ok($;$) {
28 my ($bool, $name) = @_; # Get args
29 my $ctx = context(); # Obtain a context
31 $ctx->ok($bool, $name); # Issue an OK event
33 $ctx->release; # Release the context
35 return $bool; # Return the true/false
37 }
38 1;
40 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 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 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 Return the true/false
69 Typically testing tools will return a true or false indicating if
70 the test has passed or failed.
71
73 This covers more advanced topics for tool builders.
74 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 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 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 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 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 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 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 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 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 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 CAPABILITIES
138 Test::Stream::Capabilities can be used to guage the active systems fork
139 and/or thread support levels.
140 UTILITIES
142 The Test::Stream::Util package exports many useful functions for test
143 authors.
144 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 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
155 The source code repository for Test::Stream can be found at
156 http://github.com/Test-More/Test-Stream/.
157
159 Chad Granum <exodist@cpan.org>
160
162 Chad Granum <exodist@cpan.org>
163
165 Copyright 2015 Chad Granum <exodist7@gmail.com>.
166 This program is free software; you can redistribute it and/or modify it
168 under the same terms as Perl itself.
169 See http://dev.perl.org/licenses/
171perl v5.36.0 2023-01-20 Test::Stream::Manual::Tooling(3)