1Test2::Harness::Runner:U:sPerrelCooandt(r3i)buted Perl DToecsutm2e:n:tHaatrinoenss::Runner::Preload(3)
2
6 Test2::Harness::Runner::Preload - DSL for building complex stage-based
7 preload tools.
8
10 Test2::Harness allows you to preload libraries for a performance boost.
11 This module provides tools that let you go beyond that and build a more
12 complex preload. In addition you can build multiple preload stages,
13 each stage will be its own process and tests can run from a specific
14 stage. This allows for multiple different preload states from which to
15 run tests.
16
18 USING YOUR PRELOAD
19 The "-P" or "--preload" options work for custom preload modules just as
20 they do regular modules. Yath will know the difference and act
21 accordingly.
22 yath test -PMy::Preload
24 WRITING YOUR PRELOAD
26 package My::Preload;
27 use strict;
28 use warnings;
29 # This imports several useful tools, and puts the necessary meta-data in
31 # your package to identify it as a special preload.
32 use Test2::Harness::Runner::Preload;
33 # You must specify at least one stage.
35 stage Moose => sub {
36 # Preload can be called multiple times, and can load multiple modules
37 # per call. Order is preserved.
38 preload 'Moose', 'Moose::Role';
39 preload 'Scalar::Util', 'List::Util';
40 # preload can also be given a sub if you have some custom code to run
42 # at a specific point in the load order
43 preload sub {
44 # Do something before loading Try::Tiny
45 ...
46 };
47 preload 'Try::Tiny';
49 # Eager means tests from nested stages can be run in this stage as
51 # well, this is useful if the nested stage takes a long time to load as
52 # it allows yath to start running tests sooner instead of waiting for
53 # the stage to finish loading. Once the nested stage is loaded tests
54 # intended for it will start running from it instead.
55 eager();
56 # default means this stage is the one to use if the test does not
58 # specify a stage.
59 default();
60 # These are hooks that let you run arbitrary code at specific points in
62 # the process. pre_fork happens just before forking to run a test.
63 # post_fork happens just after forking for a test. pre_launch happens
64 # as late as possible before the test starts executing (post fork,
65 # after $0 and other special state are reset).
66 pre_fork sub { ... };
67 post_fork sub { ... };
68 pre_launch sub { ... };
69 # Stages can be nested, nested ones build off the previous stage, but
71 # are in a forked process to avoid contaminating the parent.
72 stage Types => sub {
73 preload 'MooseX::Types';
74 };
75 };
76 # Alternative stage that loads Moo instead of Moose
78 stage Moo => sub {
79 preload 'Moo';
80 ...
82 };
83
85 $meta = TEST2_HARNESS_PRELOAD()
86 $meta = $class->TEST2_HARNESS_PRELOAD()
87 This export provides the meta object, which is an instance of this
88 class. This method being present is how Test2::Harness
89 differentiates between a regular module and a special preload
90 library.
91 stage NAME => sub { ... }
93 This creates a new stage with the given "NAME", and then runs the
94 coderef with the new stage set as the active one upon which the
95 other function here will operate. Once the coderef returns the
96 active stage is cleared.
97 You may nest stages by calling this function again inside the
99 codeblock.
100 NOTE: stage names ARE case sensitive. This can be confusing when
102 you consider that most harness directives are all-caps. In the
103 following case the stage requested by the test and the stage
104 defined in the library are NOT the same.
105 In a test file:
107 # HARNESS-STAGE-FOO
109 In a preload library:
111 stage foo { ... }
113 Harness directives are all-caps, however the user data portion need
115 not be, this is fine:
116 # HARNESS-STAGE-foo
118 However it is very easy to make the mistake of thinking it is case
120 insensitive. It is also easy to assume the 'foo' part of the
121 harness directive must be all caps. In many cases it is smart to
122 make your stage names all-caps.
123 preload $module_name
125 preload @module_names
126 preload sub { ... }
127 This MUST be called inside a "stage()" builder coderef.
128 This adds modules to the list of libraries to preload. Order is
130 preserved. You can also add coderefs to execute arbitrary code
131 between module loads.
132 The coderef is called with no arguments, and its return is ignored.
134 eager()
136 This MUST be called inside a "stage()" builder coderef.
137 This marks the active stage as being eager. An eager stage will
139 start running tests for nested stages if it finds itself with no
140 tests of its own to run before the nested stage can finish loading.
141 The idea here is to avoid unused test slots when possible allowing
142 for tests to complete sooner.
143 default()
145 This MUST be called inside a "stage()" builder coderef.
146 This MUST be called only once across "ALL" stages in a given
148 library.
149 If multiple preload libraries are loaded then the first default set
151 (based on load order) will be the default, others will notbe
152 honored.
153 $stage_name = file_stage($test_file)
155 This is optional. If defined this callback will have a chance to
156 look at all files that are going to be run and assign them a stage.
157 This may return undef or an empty list if it does not have a stage
158 to assign.
159 If multiple preload libraries define file_stage callbacks they will
161 be called in order, the first one to return a stage name will win.
162 If no file_stage callbacks provide a stage for a file then any
164 harness directives declaring a stage will be honored. If no stage
165 is ever assigned then the test will be run int he default stage.
166 pre_fork sub { ... }
168 This MUST be called inside a "stage()" builder coderef.
169 Add a callback to be run just before the preload-stage process
171 forks to run the test. Note that any state changes here can effect
172 future tests to be run.
173 post_fork sub { ... }
175 This MUST be called inside a "stage()" builder coderef.
176 Add a callback to be run just after the preload-stage process forks
178 to run the test. This is run as early as possible, things like $0
179 may not be set properly yet.
180 pre_launch sub { ... }
182 This MUST be called inside a "stage()" builder coderef.
183 Add a callback to be run just before control of the test process is
185 turned over to the test file itself. This is run as late as
186 possible, so things like $0 should be set properly.
187
189 This class is also the meta-object used to construct a preload library.
190 The methods are left undocumented as this is an implementation detail
191 and you are not intended to directly use this object.
192
194 The source code repository for Test2-Harness can be found at
195 http://github.com/Test-More/Test2-Harness/.
196
198 Chad Granum <exodist@cpan.org>
199
201 Chad Granum <exodist@cpan.org>
202
204 Copyright 2020 Chad Granum <exodist7@gmail.com>.
205 This program is free software; you can redistribute it and/or modify it
207 under the same terms as Perl itself.
208 See http://dev.perl.org/licenses/
210perl v5.32.0 2020-07-28Test2::Harness::Runner::Preload(3)