Test::Timer - a test module to test/assert response times
The documentation in this module describes version 0.05 of Test::Timer
use Test::Timer; time_ok( sub { doYourStuffButBeQuickAboutIt(); }, 1, 'threshold of one second'); time_atmost( sub { doYourStuffYouHave10Seconds(); }, 10, 'threshold of 10 seconds'); time_between( sub { doYourStuffYouHave5-10Seconds(); }, 5, 10, 'lower threshold of 5 seconds and upper threshold of 10 seconds'); #Will succeed time_nok( sub { sleep(2); }, 1, 'threshold of one second'); time_atleast( sub { sleep(2); }, 2, 'threshold of one second'); #Will fail after 5 (threshold) + 2 seconds (default alarm) time_ok( sub { while(1) { sleep(1); } }, 5, 'threshold of one second'); $test::Timer::alarm = 6 #default 2 seconds #Will fail after 5 (threshold) + 6 seconds (specified alarm) time_ok( sub { while(1) { sleep(1); } }, 5, 'threshold of one second');
Test::Timer implements a set of test primitives to test and assert test times from bodies of code. The code is currently at the alpha stage and might change in the future.
Test::Timer exports:
time_ok, time_nok, time_atleast, time_atmost and time_between
Takes the following parameters:
a reference to a block of code (anonymous sub)
a threshold specified as a integer indicating a number of seconds
a string specifying a test name
time_ok( sub { doYourStuffButBeQuickAboutIt(); }, 1, 'threshold of one second');
If the execution of the code exceeds the threshold the test fails
The is the inverted variant of "time_ok", it passes if the threshold is exceeded and fails if the benchmark of the code is within the specified threshold.
The API is the same as for "time_ok".
time_nok( sub { sleep(2); }, 1, 'threshold of one second');
This is syntactic sugar for "time_ok"
time_atmost( sub { doYourStuffButBeQuickAboutIt(); }, 1, 'threshold of one second');
time_atleast( sub { sleep(2); }, 1, 'threshold of one second');
The test succeeds if the code takes at least the number of seconds specified by the threshold.
Please be aware that Test::Timer, breaks the execution with an alarm specified to trigger after the specified threshold + 2 seconds, so if you expect your execution to run longer, set the alarm accordingly.
$Test::Timer::alarm = $my_alarm_in_seconds;
See also diagnostics.
This method is a more extensive variant of "time_atmost" and "time_ok", you can specify a lower and upper threshold, the code has to execute within this interval in order for the test to succeed
time_between( sub { sleep(2); }, 5, 10, 'lower threshold of 5 seconds and upper threshold of 10 seconds');
This is a method to handle the result from "_benchmark" is initiates the benchmark calling benchmark and based on whether it is within the provided interval true (1) is returned and if not false (0).
This is a simpler variant of the method above, it is the author's hope that is can be refactored out at some point, due to the similarity with "_runtest".
This is the method doing the actual benchmark, if a better method is located this is the place to do the handy work.
Currently Benchmark is used. An alternative could be Devel::Timer, but I do not know this module very well and Benchmark is core, so this is used for know.
The method takes two parameters:
a code block via a code reference
a threshold (the upper threshold, since this is added to the default alarm.
This is the method extracts the seconds from benchmarks timestring and returns it and an integer.
It takes the timestring from "_benchmark"/Benchmark and returns the seconds part.
Test::Builder required import to do some import hokus-pokus for the test methods exported from Test::Timer. Please refer to the documentation in Test::Builder
All tests either fail or succeed, but a few exceptions are implemented, these are listed below.
Test did not exceed specified threshold, this message is diagnosis for "time_atleast" and "time_nok" tests, which do not exceed their specified threshold.
Test exceeded specified threshold, this message is a diagnostic for "time_atmost" and "time_ok", if the specified threshold is surpassed.
This is the key point of the module, either your code is too slow and you should address this or your threshold is too low, in which case you can set it a bit higher and run the test again.
Test did not execute within specified interval, this is the diagnostic from "time_between", it is the diagnosis if the execution of the code is not between the specified lower and upper thresholds.
Insufficient parameters, this is the message if a specified test is not provided with the sufficent number of parameters, consult this documentation and correct accordingly.
Execution exceeded threshold and timed out, the exception is thrown if the execution of tested code exceeds even the alarm, which is default 2 seconds, but can be set by the user or is equal to the uppertreshold + 2 seconds.
The exception results in a diagnostic for the failing test. This is a failsafe to avoid that code runs forever. If you get this diagnose either your code is too slow and you should address this or it might be error prone. If this is not the case adjust the alarm setting to suit your situation.
This module requires no special configuration or environment.
Carp
Benchmark
Error
Test::Builder
Test::Builder::Module
This class holds no known incompatibilities.
This class holds no known bugs.
As listed on the TODO, the current implementations only use seconds and resolutions should be higher.
The test suite currently covers 94.5% (release 0.02)
---------------------------- ------ ------ ------ ------ ------ ------ ------ File stmt bran cond sub pod time total ---------------------------- ------ ------ ------ ------ ------ ------ ------ blib/lib/Test/Timer.pm 94.2 100.0 66.7 92.3 100.0 100.0 93.5 ...Timer/TimeoutException.pm 100.0 n/a n/a 100.0 100.0 0.0 100.0 Total 95.2 100.0 66.7 93.8 100.0 100.0 94.5 ---------------------------- ------ ------ ------ ------ ------ ------ ------
The Test::Perl::Critic test runs with severity 5 (gentle) for now, please refer to t/critic.t and t/perlcriticrc
Set TEST_POD to enable Test::Pod test in t/pod.t and Test::Pod::Coverage test in t/pod-coverage.t
Set TEST_AUTHOR to enable Test::Perl::Critic test in t/critic.t
Implement higher resolution for thresholds
Factor out "_runtest_atleast"
Add more tests to get a better feeling for the use and border cases requiring alarm etc.
Rewrite POD to emphasize "time_atleast" over "time_ok"
Test::Benchmark
Please report any bugs or feature requests to bug-test-timer at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Timer. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-test-timer at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Test::Timer
You can also look for information at:
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Test-Timer
CPAN Ratings
http://cpanratings.perl.org/d/Test-Timer
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Timer
Search CPAN
http://search.cpan.org/dist/Test-Timer
= brian d foy (BDFOY), for patch to "_run_test"
This module is very much alpha stage, so pacthes and suggestions are more that welcome, I also think there are some pitfalls and caveats I have not yet seen.
So feedback/patches is more than welcome.
Jonas B. Nielsen (jonasbn) <jonasbn@cpan.org>
<jonasbn@cpan.org>
Test::Timer and related modules are (C) by Jonas B. Nielsen, (jonasbn) 2007
Test::Timer and related modules are released under the artistic license
The distribution is licensed under the Artistic License, as specified by the Artistic file in the standard perl distribution (http://www.perl.com/language/misc/Artistic.html).
To install Test::Timer, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Test::Timer
CPAN shell
perl -MCPAN -e shell install Test::Timer
For more information on module installation, please visit the detailed CPAN module installation guide.