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