1Apache::TestRun(3) User Contributed Perl Documentation Apache::TestRun(3)
2
6 Apache::TestRun - Run the test suite
7
10 The "Apache::TestRun" package controls the configuration and running of
11 the test suite.
12
14 Several methods are sub-classable, if the default behavior should be
15 changed.
16 "bug_report"
18 The "bug_report()" method is executed when "t/TEST" was executed with
20 the "-bugreport" option, and "make test" (or "t/TEST") fail. Normally
21 this is callback which you can use to tell the user how to deal with
22 the problem, e.g. suggesting to read some document or email some
23 details to someone who can take care of it. By default nothing is exe‐
24 cuted.
25 The "-bugreport" option is needed so this feature won't become annoying
27 to developers themselves. It's automatically added to the "run_tests"
28 target in Makefile. So if you repeateadly have to test your code, just
29 don't use "make test" but run "t/TEST" directly. Here is an example of
30 a custom "t/TEST"
31 My::TestRun->new->run(@ARGV);
33 package My::TestRun;
35 use base 'Apache::TestRun';
36 sub bug_report {
38 my $self = shift;
39 print <<EOI;
41 +--------------------------------------------------------+
42 ⎪ Please file a bug report: http://perl.apache.org/bugs/ ⎪
43 +--------------------------------------------------------+
44 EOI
45 }
46 "pre_configure"
48 The "pre_configure()" method is executed before the configuration for
50 "Apache::Test" is generated. So if you need to adjust the setup before
51 httpd.conf and other files are autogenerated, this is the right place
52 to do so.
53 For example if you don't want to inherit a LoadModule directive for
55 mod_apreq.so but to make sure that the local version is used, you can
56 sub-class "Apache::TestRun" and override this method in t/TEST.PL:
57 package My::TestRun;
59 use base 'Apache::TestRun';
60 use Apache::TestConfig;
61 __PACKAGE__->new->run(@ARGV);
62 sub pre_configure {
64 my $self = shift;
65 # Don't load an installed mod_apreq
66 Apache::TestConfig::autoconfig_skip_module_add('mod_apreq.c');
67 $self->SUPER::pre_configure();
69 }
70 Notice that the extension is .c, and not .so.
72 Don't forget to run the super class' c<pre_configure()> method.
74 "new_test_config"
76 META: to be completed
78
80 When "Apache::Test" is first installed or used, it will save the values
81 of "httpd", "apxs", "port", "user", and "group", if set, to a configu‐
82 ration file "Apache::TestConfigData". This information will then be
83 used in setting these options for subsequent uses of "Apache-Test"
84 unless temprorarily overridden, either by setting the appropriate envi‐
85 ronment variable ("APACHE_TEST_HTTPD", "APACHE_TEST_APXS",
86 "APACHE_TEST_PORT", "APACHE_TEST_USER", and "APACHE_TEST_GROUP") or by
87 giving the relevant option ("-httpd", "-apxs", "-port", "-user", and
88 "-group") when the "TEST" script is run.
89 To avoid either using previous persistent configurations or saving cur‐
91 rent configurations, set the "APACHE_TEST_NO_STICKY_PREFERENCES" envi‐
92 ronment variable to a true value.
93 Finally it's possible to permanently override the previously saved
95 options by passing "-save".
96 Here is the algorithm of how and when options are saved for the first
98 time and when they are used. We will use a few variables to simplify
99 the pseudo-code/pseudo-chart flow:
100 $config_exists - custom configuration has already been saved, to get
102 this setting run "custom_config_exists()", which tests whether either
103 "apxs" or "httpd" values are set. It doesn't check for other values,
104 since all we need is "apxs" or "httpd" to get the test suite running.
105 custom_config_exists() checks in the following order lib/Apache/Test‐
106 ConfigData.pm (if during Apache-Test build) ,
107 ~/.apache-test/Apache/TestConfigData.pm and Apache/TestConfigData.pm in
108 the perl's libraries.
109 $config_overriden - that means that we have either "apxs" or "httpd"
111 values provided by user, via env vars or command line options.
112 1 Building Apache-Test or modperl-2.0 (or any other project that bun‐
114 dles Apache-Test).
115 1) perl Apache-Test/Makefile.PL
116 (for bundles top-level Makefile.PL will run this as well)
117 if $config_exists
119 do nothing
120 else
121 create lib/Apache/TestConfigData.pm w/ empty config: {}
122 2) make
124 3) make test
126 if $config_exists
128 if $config_overriden
129 override saved options (for those that were overriden)
130 else
131 use saved options
132 else
133 if $config_overriden
134 save them in lib/Apache/TestConfigData.pm
135 (which will be installed on 'make install')
136 else
137 - run interactive prompt for C<httpd> and optionally for C<apxs>
138 - save the custom config in lib/Apache/TestConfigData.pm
139 - restart the currently run program
140 modperl-2.0 is a special case in (3). it always overrides 'httpd'
142 and 'apxs' settings. Other settings like 'port', can be used from
143 the saved config.
144 4) make install
146 if $config_exists only in lib/Apache/TestConfigData.pm
148 it will be installed system-wide
149 else
150 nothing changes (since lib/Apache/TestConfigData.pm won't exist)
151 2 Testing 3rd party modules (after Apache-Test was installed)
153 Notice that the following situation is quite possible:
154 cd Apache-Test
156 perl Makefile.PL && make install
157 so that Apache-Test was installed but no custom configuration saved
159 (since its "make test" wasn't run). In which case the interactive
160 configuration should kick in (unless config options were passed)
161 and in any case saved once configured.
162 $custom_config_path - perl's Apache/TestConfigData.pm (at the same
164 location as Apache/TestConfig.pm) if that area is writable by that
165 user (e.g. perl's lib is not owned by 'root'). If not, in
166 ~/.apache-test/Apache/TestConfigData.pm.
167 1) perl Apache-Test/Makefile.PL
169 2) make
170 3) make test
171 if $config_exists
173 if $config_overriden
174 override saved options (for those that were overriden)
175 else
176 use saved options
177 else
178 if $config_overriden
179 save them in $custom_config_path
180 else
181 - run interactive prompt for C<httpd> and optionally for C<apxs>
182 - save the custom config in $custom_config_path
183 - restart the currently run program
184 4) make install
186 Saving Custom Configuration Options
188 If you want to override the existing custom configurations options to
190 "Apache::TestConfigData", use the "-save" flag when running "TEST".
191 If you are running "Apache::Test" as a user who does not have permis‐
193 sion to alter the system "Apache::TestConfigData", you can place your
194 own private configuration file TestConfigData.pm under
195 "$ENV{HOME}/.apache-test/Apache/", which "Apache::Test" will use, if
196 present. An example of such a configuration file is
197 # file $ENV{HOME}/.apache-test/Apache/TestConfigData.pm
199 package Apache::TestConfigData;
200 use strict;
201 use warnings;
202 use vars qw($vars);
203 $vars = {
205 'group' => 'me',
206 'user' => 'myself',
207 'port' => '8529',
208 'httpd' => '/usr/local/apache/bin/httpd',
209 };
211 1;
212perl v5.8.8 2006-11-19 Apache::TestRun(3)