Apache::TestRun - Run the test suite
The Apache::TestRun package controls the configuration and running
of the test suite.
Several methods are sub-classable, if the default behavior should be changed.
bug_report
The bug_report() method is executed when t/TEST was executed
with the -bugreport option, and make test (or t/TEST)
fail. Normally this is callback which you can use to tell the user how
to deal with the problem, e.g. suggesting to read some document or
email some details to someone who can take care of it. By default
nothing is executed.
The -bugreport option is needed so this feature won't become
annoying to developers themselves. It's automatically added to the
run_tests target in Makefile. So if you repeateadly have to test
your code, just don't use make test but run t/TEST
directly. Here is an example of a custom t/TEST
My::TestRun->new->run(@ARGV);
package My::TestRun;
use base 'Apache::TestRun';
sub bug_report {
my $self = shift;
print <<EOI;
+--------------------------------------------------------+
| Please file a bug report: http://perl.apache.org/bugs/ |
+--------------------------------------------------------+
EOI
}
pre_configure
The pre_configure() method is executed before the configuration for
Apache::Test is generated. So if you need to adjust the setup
before httpd.conf and other files are autogenerated, this is the
right place to do so.
For example if you don't want to inherit a LoadModule directive for
mod_apreq.so but to make sure that the local version is used, you
can sub-class Apache::TestRun and override this method in
t/TEST.PL:
package My::TestRun;
use base 'Apache::TestRun';
use Apache::TestConfig;
__PACKAGE__->new->run(@ARGV);
sub pre_configure {
my $self = shift;
# Don't load an installed mod_apreq
Apache::TestConfig::autoconfig_skip_module_add('mod_apreq.c');
$self->SUPER::pre_configure();
}
Notice that the extension is .c, and not .so.
Don't forget to run the super class' c<pre_configure()> method.
new_test_config
META: to be completed
When Apache::Test is first installed or used, it will save the
values of httpd, apxs, port, user, and group, if set,
to a configuration file Apache::TestConfigData. This information
will then be used in setting these options for subsequent uses of
Apache-Test unless temprorarily overridden, either by setting the
appropriate environment variable (APACHE_TEST_HTTPD,
APACHE_TEST_APXS, APACHE_TEST_PORT, APACHE_TEST_USER, and
APACHE_TEST_GROUP) or by giving the relevant option (-httpd,
-apxs, -port, -user, and -group) when the TEST script
is run.
To avoid either using previous persistent configurations or saving
current configurations, set the APACHE_TEST_NO_STICKY_PREFERENCES
environment variable to a true value.
Finally it's possible to permanently override the previously saved
options by passing -save.
Here is the algorithm of how and when options are saved for the first time and when they are used. We will use a few variables to simplify the pseudo-code/pseudo-chart flow:
$config_exists - custom configuration has already been saved, to
get this setting run custom_config_exists(), which tests whether
either apxs or httpd values are set. It doesn't check for other
values, since all we need is apxs or httpd to get the test suite
running. custom_config_exists() checks in the following order
lib/Apache/TestConfigData.pm (if during Apache-Test build) ,
~/.apache-test/Apache/TestConfigData.pm and
Apache/TestConfigData.pm in the perl's libraries.
$config_overriden - that means that we have either apxs or
httpd values provided by user, via env vars or command line options.
1) perl Apache-Test/Makefile.PL
(for bundles top-level Makefile.PL will run this as well)
if $config_exists
do nothing
else
create lib/Apache/TestConfigData.pm w/ empty config: {}
2) make
3) make test
if $config_exists
if $config_overriden
override saved options (for those that were overriden)
else
use saved options
else
if $config_overriden
save them in lib/Apache/TestConfigData.pm
(which will be installed on 'make install')
else
- run interactive prompt for C<httpd> and optionally for C<apxs>
- save the custom config in lib/Apache/TestConfigData.pm
- restart the currently run program
modperl-2.0 is a special case in (3). it always overrides 'httpd'
and 'apxs' settings. Other settings like 'port', can be used from
the saved config.
4) make install
if $config_exists only in lib/Apache/TestConfigData.pm
it will be installed system-wide
else
nothing changes (since lib/Apache/TestConfigData.pm won't exist)
Notice that the following situation is quite possible:
cd Apache-Test perl Makefile.PL && make install
so that Apache-Test was installed but no custom configuration saved
(since its make test wasn't run). In which case the interactive
configuration should kick in (unless config options were passed) and
in any case saved once configured.
$custom_config_path - perl's Apache/TestConfigData.pm (at the
same location as Apache/TestConfig.pm) if that area is writable by
that user (e.g. perl's lib is not owned by 'root'). If not, in
~/.apache-test/Apache/TestConfigData.pm.
1) perl Apache-Test/Makefile.PL
2) make
3) make test
if $config_exists
if $config_overriden
override saved options (for those that were overriden)
else
use saved options
else
if $config_overriden
save them in $custom_config_path
else
- run interactive prompt for C<httpd> and optionally for C<apxs>
- save the custom config in $custom_config_path
- restart the currently run program
4) make install
If you want to override the existing custom configurations options to
Apache::TestConfigData, use the -save flag when running TEST.
If you are running Apache::Test as a user who does not have
permission to alter the system Apache::TestConfigData, you can
place your own private configuration file TestConfigData.pm under
$ENV{HOME}/.apache-test/Apache/, which Apache::Test will use, if
present. An example of such a configuration file is
# file $ENV{HOME}/.apache-test/Apache/TestConfigData.pm
package Apache::TestConfigData;
use strict;
use warnings;
use vars qw($vars);
$vars = {
'group' => 'me',
'user' => 'myself',
'port' => '8529',
'httpd' => '/usr/local/apache/bin/httpd',
};
1;