1Test::Timer(3)        User Contributed Perl Documentation       Test::Timer(3)
2
3
4

NAME

6       Test::Timer - test module to test/assert response times
7

VERSION

9       The documentation describes version 2.12 of Test::Timer
10

FEATURES

12       •   Test subroutines to implement unit-tests to time that your code
13           executes before a specified threshold
14
15       •   Test subroutines to implement unit-tests to time that your code
16           execution exceeds a specified threshold
17
18       •   Test subroutine to implement unit-tests to time that your code
19           executes within a specified time frame
20
21       •   Supports measurements in seconds
22
23       •   Implements configurable alarm signal handler to make sure that your
24           tests do not execute forever
25

SYNOPSIS

27           use Test::Timer;
28
29           time_ok( sub { doYourStuffButBeQuickAboutIt(); }, 1, 'threshold of one second');
30
31           time_atmost( sub { doYourStuffYouHave10Seconds(); }, 10, 'threshold of 10 seconds');
32
33           time_between( sub { doYourStuffYouHave5-10Seconds(); }, 5, 10,
34               'lower threshold of 5 seconds and upper threshold of 10 seconds');
35
36           # Will succeed
37           time_nok( sub { sleep(2); }, 1, 'threshold of one second');
38
39           time_atleast( sub { sleep(2); }, 2, 'threshold of one second');
40
41           # Will fail after 5 (threshold) + 2 seconds (default alarm)
42           time_ok( sub { while(1) { sleep(1); } }, 5, 'threshold of one second');
43
44           $test::Timer::alarm = 6 #default 2 seconds
45
46           # Will fail after 5 (threshold) + 6 seconds (specified alarm)
47           time_ok( sub { while(1) { sleep(1); } }, 5, 'threshold of one second');
48

DESCRIPTION

50       Test::Timer implements a set of test primitives to test and assert test
51       times from bodies of code.
52
53       The key features are subroutines to assert or test the following:
54
55       •   that a given piece of code does not exceed a specified time limit
56
57       •   that a given piece of code takes longer than a specified time limit
58           and does not exceed another
59

EXPORT

61       Test::Timer exports:
62
63       •   time_ok
64
65       •   time_nok
66
67       •   time_atleast
68
69       •   time_atmost
70
71       •   time_between
72

SUBROUTINES/METHODS

74   time_ok
75       Takes the following parameters:
76
77       •   a reference to a block of code (anonymous sub)
78
79       •   a threshold specified as a integer indicating a number of seconds
80
81       •   a string specifying a test name
82
83           time_nok( sub { sleep(2); }, 1, 'threshold of one second');
84
85       If the execution of the code exceeds the threshold specified the test
86       fail with the following diagnostic message
87
88           Test ran 2 seconds and exceeded specified threshold of 1 seconds
89
90   time_nok
91       The is the inverted variant of time_ok, it passes if the threshold is
92       exceeded and fails if the benchmark of the code is within the specified
93       timing threshold.
94
95       The API is the same as for time_ok.
96
97           time_nok( sub { sleep(1); }, 2, 'threshold of two seconds');
98
99       If the execution of the code executes below the threshold specified the
100       test fail with the following diagnostic message
101
102           Test ran 1 seconds and did not exceed specified threshold of 2 seconds
103
104   time_atmost
105       This is syntactic sugar for time_ok
106
107           time_atmost( sub { doYourStuffButBeQuickAboutIt(); }, 1, 'threshold of one second');
108
109       If the execution of the code exceeds the threshold specified the test
110       fail with the following diagnostic message
111
112           Test ran N seconds and exceeded specified threshold of 1 seconds
113
114       N will be the actual measured execution time of the specified code
115
116   time_atleast
117           time_atleast( sub { doYourStuffAndTakeYourTimeAboutIt(); }, 1, 'threshold of 1 second');
118
119       The test succeeds if the code takes at least the number of seconds
120       specified by the timing threshold.
121
122       If the code executes faster, the test fails with the following
123       diagnostic message
124
125           Test ran 1 seconds and did not exceed specified threshold of 2 seconds
126
127       Please be aware that Test::Timer, breaks the execution with an alarm
128       specified to trigger after the specified threshold + 2 seconds
129       (default), so if you expect your execution to run longer, set the alarm
130       accordingly.
131
132           $Test::Timer::alarm = $my_alarm_in_seconds;
133
134       See also diagnostics.
135
136   time_between
137       This method is a more extensive variant of time_atmost and time_ok, you
138       can specify a lower and upper threshold, the code has to execute within
139       this interval in order for the test to succeed
140
141           time_between( sub { sleep(2); }, 5, 10,
142               'lower threshold of 5 seconds and upper threshold of 10 seconds');
143
144       If the code executes faster than the lower threshold or exceeds the
145       upper threshold, the test fails with the following diagnostic message
146
147           Test ran 2 seconds and did not execute within specified interval 5 - 10 seconds
148
149       Or
150
151           Test ran 12 seconds and did not execute within specified interval 5 - 10 seconds
152

PRIVATE FUNCTIONS

154   _runtest
155       This is a method to handle the result from _benchmark is initiates the
156       benchmark calling benchmark and based on whether it is within the
157       provided interval true (1) is returned and if not false (0).
158
159   _benchmark
160       This is the method doing the actual benchmark, if a better method is
161       located this is the place to do the handy work.
162
163       Currently Benchmark is used. An alternative could be Devel::Timer, but
164       I do not know this module very well and Benchmark is core, so this is
165       used for now.
166
167       The method takes two parameters:
168
169       •   a code block via a code reference
170
171       •   a threshold (the upper threshold, since this is added to the
172           default alarm
173
174   import
175       Test::Builder required import to do some import hokus-pokus for the
176       test methods exported from Test::Timer. Please refer to the
177       documentation in Test::Builder
178

DIAGNOSTICS

180       All tests either fail or succeed, but a few exceptions are implemented,
181       these are listed below.
182
183       •   Test did not exceed specified threshold, this message is diagnosis
184           for time_atleast and time_nok tests, which do not exceed their
185           specified threshold
186
187       •   Test exceeded specified threshold, this message is a diagnostic for
188           time_atmost and time_ok, if the specified threshold is surpassed.
189
190           This is the key point of the module, either your code is too slow
191           and you should address this or your threshold is too low, in which
192           case you can set it a bit higher and run the test again.
193
194       •   Test did not execute within specified interval, this is the
195           diagnostic from time_between, it is the diagnosis if the execution
196           of the code is not between the specified lower and upper thresholds
197
198       •   Insufficient parameters, this is the message if a specified test is
199           not provided with the sufficient number of parameters, consult this
200           documentation and correct accordingly
201
202       •   Execution exceeded threshold and timed out, the exception is thrown
203           if the execution of tested code exceeds even the alarm, which is
204           default 2 seconds, but can be set by the user or is equal to the
205           upper threshold + 2 seconds
206
207           The exception results in a diagnostic for the failing test. This is
208           a fail-safe to avoid that code runs forever. If you get this
209           diagnose either your code is too slow and you should address this
210           or it might be error prone. If this is not the case adjust the
211           alarm setting to suit your situation.
212

CONFIGURATION AND ENVIRONMENT

214       This module requires no special configuration or environment.
215
216       Tests are sensitive and be configured using environment and
217       configuration files, please see the section on test and quality.
218

DEPENDENCIES

220       •   Carp
221
222       •   Benchmark
223
224       •   Error
225
226       •   Test::Builder
227
228       •   Test::Builder::Module
229

INCOMPATIBILITIES

231       This module holds no known incompatibilities.
232

BUGS AND LIMITATIONS

234       This module holds no known bugs.
235
236       The current implementations only use seconds and resolutions should be
237       higher, so the current implementation is limited to seconds as the
238       highest resolution.
239
240       On occasion failing tests with CPAN-testers have been observed. This
241       seem to be related to the test-suite being not taking into account that
242       some smoke-testers do not prioritize resources for the test run and
243       that additional processes/jobs are running. The test-suite have been
244       adjusted to accommodate this but these issues might reoccur.
245

TEST AND QUALITY

247       Coverage report for the release described in this documentation (see
248       VERSION).
249
250           ---------------------------- ------ ------ ------ ------ ------ ------ ------
251           File                           stmt   bran   cond    sub    pod   time  total
252           ---------------------------- ------ ------ ------ ------ ------ ------ ------
253           blib/lib/Test/Timer.pm        100.0  100.0  100.0  100.0  100.0   99.9  100.0
254           ...Timer/TimeoutException.pm  100.0    n/a    n/a  100.0  100.0    0.0  100.0
255           Total                         100.0  100.0  100.0  100.0  100.0  100.0  100.0
256           ---------------------------- ------ ------ ------ ------ ------ ------ ------
257
258       The Test::Perl::Critic test runs with severity 5 (gentle) for now,
259       please refer to t/critic.t and t/perlcriticrc.
260
261       Set TEST_POD to enable Test::Pod test in t/pod.t and
262       Test::Pod::Coverage test in t/pod-coverage.t.
263
264       Set TEST_CRITIC to enable Test::Perl::Critic test in t/critic.t
265
266   CONTINUOUS INTEGRATION
267       This distribution uses Travis for continuous integration testing, the
268       Travis reports are public available.
269

SEE ALSO

271       •   Test::Benchmark
272

ISSUE REPORTING

274       Please report any bugs or feature requests using GitHub
275
276       •   GitHub Issues <https://github.com/jonasbn/perl-test-timer/issues>
277

SUPPORT

279       You can find (this) documentation for this module with the "perldoc"
280       command.
281
282           perldoc Test::Timer
283
284       You can also look for information at:
285
286       •   Homepage <https://jonasbn.github.io/perl-test-timer/>
287
288       •   MetaCPAN <https://metacpan.org/pod/Test-Timer>
289
290       •   AnnoCPAN: Annotated CPAN documentation
291           <http://annocpan.org/dist/Test-Timer>
292
293       •   CPAN Ratings <http://cpanratings.perl.org/d/Test-Timer>
294

DEVELOPMENT

296       •   GitHub Repository <https://github.com/jonasbn/perl-test-timer>,
297           please see the guidelines for contributing
298           <https://github.com/jonasbn/perl-test-
299           timer/blob/master/CONTRIBUTING.md>.
300

AUTHOR

302       •   Jonas Brømsø (jonasbn) "<jonasbn at cpan.org>"
303

ACKNOWLEDGEMENTS

305       •   Mohammad S Anwar (MANWAR), POD corrections PRs #23
306
307       •   Erik Johansen (UNIEJO), suggestion for clearing alarm
308
309       •   Gregor Herrmann (GREGOA) from the Debian Perl Group, PR #16 fixes
310           to spelling mistakes
311
312       •   Nigel Horne (NHORNE), issue #15 suggestion for better assertion in
313           time_atleast
314
315       •   Nigel Horne (NHORNE), issue #10/#12 suggestion for improvement to
316           diagnostics
317
318       •   p-alik, PR #4 eliminating warnings during test
319
320       •   Kent Fredric (KENTNL), PR #7 addressing file permissions
321
322       •   Nick Morrott, PR #5 corrections to POD
323
324       •   Bartosz Jakubski, reporting issue #3
325
326       •   Gabor Szabo (SZABGAB), suggestion for specification of interval
327           thresholds even though this was obsoleted by the later introduced
328           time_between
329
330       •   Paul Leonerd Evans (PEVANS), suggestions for time_atleast and
331           time_atmost and the handling of $SIG{ALRM}. Also bug report for
332           addressing issue with Debian packaging resulting in release 0.10
333
334       •   brian d foy (BDFOY), for patch to _runtest
335
337       Test::Timer and related modules are (C) by Jonas Brømsø (jonasbn)
338       2007-2021
339
340       Test::Timer and related modules are released under the Artistic License
341       2.0
342
343       Used distributions are under copyright of there respective authors and
344       designated licenses
345
346       Image used on website <https://jonasbn.github.io/perl-test-timer/> is
347       under copyright by Veri Ivanova
348       <https://unsplash.com/photos/p3Pj7jOYvnM>
349
350
351
352perl v5.38.0                      2023-07-21                    Test::Timer(3)
Impressum