poe-gen-tests(1)

1POE-GEN-TESTS(1)      User Contributed Perl Documentation     POE-GEN-TESTS(1)
2
3
4

NAME

6       poe-gen-tests - generate standard POE tests for third-party modules
7

SYNOPSIS

9         poe-gen-tests --dirbase t/loops \
10           --loop Glib \
11           --loop Kqueue \
12           --loop Event::Lib \
13           --loop POE::XS::Loop::Poll
14

DESCRIPTION

16       This program and the accompanying POE::Test::Loop::* modules make up
17       POE's tests for POE::Loop subclasses.  These tests are designed to run
18       identically regardless of the current event loop.  POE uses them to
19       test the event loops it bundles:
20
21         POE::Loop::Gtk
22         POE::Loop::IO_Poll (--loop IO::Poll)
23         POE::Loop::Tk
24         POE::Loop::Event
25         POE::Loop::Select
26
27       Developers of other POE::Loop modules are encouraged use this package
28       to generate over 420 comprehensive tests for their own work.
29

USAGE

31       poe-gen-tests creates test files for one or more event loops beneath
32       the directory specified in --dirbase.  For example,
33
34         poe-gen-tests --dirbase t/loops --loop Select
35
36       generates the following test files:
37
38         t/loops/select/all_errors.t
39         t/loops/select/comp_tcp.t
40         t/loops/select/comp_tcp_concurrent.t
41         t/loops/select/connect_errors.t
42         t/loops/select/k_alarms.t
43         t/loops/select/k_aliases.t
44         t/loops/select/k_detach.t
45         t/loops/select/k_selects.t
46         t/loops/select/k_sig_child.t
47         t/loops/select/k_signals.t
48         t/loops/select/k_signals_rerun.t
49         t/loops/select/sbk_signal_init.t
50         t/loops/select/ses_nfa.t
51         t/loops/select/ses_session.t
52         t/loops/select/wheel_accept.t
53         t/loops/select/wheel_curses.t
54         t/loops/select/wheel_readline.t
55         t/loops/select/wheel_readwrite.t
56         t/loops/select/wheel_run.t
57         t/loops/select/wheel_sf_ipv6.t
58         t/loops/select/wheel_sf_tcp.t
59         t/loops/select/wheel_sf_udp.t
60         t/loops/select/wheel_sf_unix.t
61         t/loops/select/wheel_tail.t
62
63       The --loop parameter is either a POE::Loop::... class name or the event
64       loop class that will complete the POE::Loop::... package name.
65
66         poe-gen-tests --dirbase t/loops --loop Event::Lib
67         poe-gen-tests --dirbase t/loops --loop POE::Loop::Event_Lib
68
69       poe-gen-tests looks for a "=for poe_tests" or "=begin poe_tests"
70       section within the POE::Loop class being tested.  If defined, this
71       section should include a single function, skip_tests(), that determines
72       whether any given test should be skipped.
73
74       Please see perlpod for syntax for "=for" and "=begin".  Also see
75       PODDITIES for notable differences between POE::Test::Loop's POD support
76       and the standard.
77
78       skip_tests() is called with one parameter, the base name of the test
79       about to be executed.  It returns false if the test should run, or a
80       message that will be displayed to the user explaining why the test will
81       be skipped.  This message is passed directly to Test::More's plan()
82       along with "skip_all".  The logic is essentially:
83
84         if (my $why = skip_tests("k_signals_rerun")) {
85           plan skip_all => $why;
86         }
87
88       skip_tests() should load any modules required by the event loop.  See
89       most of the examples below.
90
91   Example poe_tests Directives
92       POE::Loop::Event checks whether the Event module exists and can be
93       loaded, then whether specific tests can run under specific operating
94       systems.
95
96         =for poe_tests
97         sub skip_tests {
98           return "Event tests require the Event module" if (
99             do { eval "use Event"; $@ }
100           );
101           my $test_name = shift;
102           if ($test_name eq "k_signals_rerun" and $^O eq "MSWin32") {
103             return "This test crashes Perl when run with Tk on $^O";
104           }
105           if ($test_name eq "wheel_readline" and $^O eq "darwin") {
106             return "Event skips two of its own tests for the same reason";
107           }
108         }
109
110       POE::Loop::Gtk checks whether DISPLAY is set, which implies that X is
111       running.  It then checks whether Gtk is available, loadable, and safely
112       initializable before skipping specific tests.
113
114         =for poe_tests
115         sub skip_tests {
116           my $test_name = shift;
117           return "Gtk needs a DISPLAY (set one today, okay?)" unless (
118             defined $ENV{DISPLAY} and length $ENV{DISPLAY}
119           );
120           return "Gtk tests require the Gtk module" if do { eval "use Gtk"; $@ };
121           return "Gtk init failed.  Is DISPLAY valid?" unless defined Gtk->init_check;
122           if ($test_name eq "z_rt39872_sigchld_stop") {
123             return "Gdk crashes";
124           }
125           return;
126         }
127
128       POE::Loop::IO_Poll checks for system compatibility before verifying
129       that IO::Poll is available and loadable.
130
131         =for poe_tests
132         sub skip_tests {
133           return "IO::Poll is not 100% compatible with $^O" if $^O eq "MSWin32";
134           return "IO::Poll tests require the IO::Poll module" if (
135             do { eval "use IO::Poll"; $@ }
136           );
137         }
138
139       POE::Loop::Select has no specific requirements.
140
141         =for poe_tests
142         sub skip_tests { return }
143
144       POE::Loop::Tk needs an X display (except on Windows).  Tk is not safe
145       for fork(), so skip tests that require forking.  And finally, check
146       whether the Tk module is available, loadable, and runnable.
147
148         =for poe_tests
149         sub skip_tests {
150           return "Tk needs a DISPLAY (set one today, okay?)" unless (
151             (defined $ENV{DISPLAY} and length $ENV{DISPLAY}) or $^O eq "MSWin32"
152           );
153           my $test_name = shift;
154           if ($test_name eq "k_signals_rerun" and $^O eq "MSWin32") {
155             return "This test crashes Perl when run with Tk on $^O";
156           }
157           return "Tk tests require the Tk module" if do { eval "use Tk"; $@ };
158           my $m = eval { Tk::MainWindow->new() };
159           if ($@) {
160             my $why = $@;
161             $why =~ s/ at .*//;
162             return "Tk couldn't be initialized: $why";
163           }
164           return;
165         }
166

INSTALL SCRIPT INTEGRATION

168       The POE::Loop tests started out as part of the POE distribution.  All
169       the recommendations and examples that follow are written and tested
170       against ExtUtils::MakeMaker because that's what POE uses.  Please
171       adjust these recipes according to your taste and preference.
172
173   Calling the Test Generator
174       Tests need to be generated prior to the user or CPAN shell running
175       "make test".  A tidy way to do this might be to create a new Makefile
176       target and include that as a dependency for "make test".  POE takes a
177       simpler approach, calling the script from its Makefile.PL:
178
179         system(
180           $^X, "poe-gen-tests", "--dirbase", "t/30_loops",
181           "--loop", "Event", "--loop", "Gtk", "--loop", "IO::Poll",
182           "--loop", "Select", "--loop", "Tk",
183         ) and die $!;
184
185       The previous approach generates tests at install time, so it's not
186       necessary to include the generated files in the MANIFEST.  Test
187       directories should also be excluded from the MANIFEST.  poe-gen-tests
188       will create the necessary paths.
189
190       It's also possible to generate the tests prior to "make dist".  The
191       distribution's MANIFEST must include the generated files in this case.
192
193       Most people will not need to add the generated tests to their
194       repositories.
195

Running the Tests

197       By default, ExtUtils::MakeMaker generates Makefiles that only run tests
198       matching t/*.t.  However authors are allowed to specify other test
199       locations.  Add the following parameter to WriteMakefile() so that the
200       tests generated above will be executed:
201
202         tests => {
203           TESTS => "t/*.t t/30_loops/*/*.t",
204         }
205

CLEANING UP

207       Makefiles will not clean up files that aren't present in the MANIFEST.
208       This includes tests generated at install time.  If this bothers you,
209       you'll need to add directives to include the generated tests in the
210       "clean" and "distclean" targets.
211
212         clean => {
213           FILES => "t/30_loops/*/* t/30_loops/*",
214         }
215
216       This assumes the "t/30_loops" directory contains only generated tests.
217       It's recommended that generated and hand-coded tests not coexist in the
218       same directory.
219
220       It seems like a good idea to delete the deeper directories and files
221       before their parents.
222

Skipping Network Tests

224       Some generated tests require a network to be present and accessible.
225       Those tests will be skipped unless the file "run_network_tests" is
226       present in the main distribution directory.  You can include that file
227       in your distribution's tarball, but it's better create it at install
228       time after asking the user.  Here's how POE does it.  Naturally you're
229       free to do it some other way.
230
231         # Switch to default behavior if STDIN isn't a tty.
232
233         unless (-t STDIN) {
234           warn(
235             "\n",
236             "=============================================\n\n",
237             "STDIN is not a terminal.  Assuming --default.\n\n",
238             "=============================================\n\n",
239           );
240           push @ARGV, "--default";
241         }
242
243         # Remind the user she can use --default.
244
245         unless (grep /^--default$/, @ARGV) {
246           warn(
247             "\n",
248             "================================================\n\n",
249             "Prompts may be bypassed with the --default flag.\n\n",
250             "================================================\n\n",
251           );
252         }
253
254         # Should we run the network tests?
255
256         my $prompt = (
257           "Some of POE's tests require a functional network.\n" .
258           "You can skip these tests if you'd like.\n\n" .
259           "Would you like to skip the network tests?"
260         );
261
262         my $ret = "n";
263         if (grep /^--default$/, @ARGV) {
264           print $prompt, " [$ret] $ret\n\n";
265         }
266         else {
267           $ret = prompt($prompt, "n");
268         }
269
270         my $marker = 'run_network_tests';
271         unlink $marker;
272         unless ($ret =~ /^Y$/i) {
273           open(TOUCH,"+>$marker") and close TOUCH;
274         }
275
276         print "\n";
277

Skipping Other Tests

279       POE's loop tests will enable or disable tests based on the event loop's
280       capabilities.  Distributions and event loops may set these variables to
281       signal which tests are okay to run.
282
283   POE_LOOP_USES_POLL
284       Some platforms do not support poll() on certain kinds of filehandles.
285       Event loops that use poll() should set this environment variable to a
286       true value.  It will cause the tests to skip this troublesome
287       combination.
288
289   PODDITIES
290       Previous versions of POE::Test::Loops documented "=for poe_tests"
291       sections terminated by =cut and containing blank lines.  This is
292       incorrect POD syntax, and it's the reason the skip_tests() functions
293       showed up in perldoc and on search.cpan.org.  The following syntax is
294       wrong and should not have been used.  I'm so sorry.
295
296         =for poe_tests
297
298         sub skip_tests { ... }
299
300         =cut
301
302       The proper syntax is to terminate "=for poe_tests" with a blank line:
303
304         =for poe_tests
305         sub skip_tests {
306           ...
307         }
308
309       Multi-line tests containing blank lines can be specified using POD's
310       "=begin poe_tests" terminated by "=end poe_tests".
311
312         =begin poe_tests
313
314         sub skip_tests {
315           ...
316         }
317
318         =end poe_tests
319
320       All three syntaxes above are supported as of POE::Test::Loops version
321       1.034.  The incorrect =for syntax is deprecated and will be removed in
322       some future release.
323

AUTHOR & COPYRIGHT

337       Rocco Caputo <rcaputo@cpan.org>.  Benjamin Smith <bsmith@cpan.org>.
338       Countless other people.
339
340       These tests are Copyright 1998-2013 by Rocco Caputo, Benjamin Smith,
341       and countless contributors.  All rights are reserved.  These tests are
342       free software; you may redistribute them and/or modify them under the
343       same terms as Perl itself.
344
345       Thanks to Martijn van Beers for beta testing and suggestions.
346
347
348
349perl v5.38.0                      2023-07-21                  POE-GEN-TESTS(1)