#########
# About #
#########
Apache::Test is a test toolkit for testing an Apache server with any
configuration. It works with Apache 1.3 and Apache 2.0/2.2/2.4 and any
of its modules, including mod_perl 1.0 and 2.0. It was originally developed
for testing mod_perl 2.0.
#################
# Documentation #
#################
For an extensive documentation see the tutorial:
and the documentation of the specific Apache::Test modules, which can
be read using 'perldoc', for example:
% perldoc Apache::TestUtil
and the 'Testing mod_perl 2.0' article:
###################
# Got a question? #
###################
Post it to the test-dev <at> httpd.apache.org list. The list is
moderated, so unless you are subscribed to it it may take some time
for your post to make it to the list.
List Archives:
# www.apachelabs.org
# marc.theaimsgroup.com
# Mbox file
##############
# Cheat List #
##############
see Makefile.PL for howto enable 'make test'
see t/TEST as an example test harness
see t/*.t for example tests
if the file t/conf/httpd.conf.in exists, it will be used instead of
the default template (in Apache/TestConfig.pm);
if the file t/conf/extra.conf.in exists, it will be used to generate
t/conf/extra.conf with @variable@ substitutions
if the file t/conf/extra.conf exists, it will be included by
httpd.conf
if the file t/conf/modperl_extra.pl exists, it will be included by
httpd.conf as a mod_perl file (PerlRequire)
##################
# Handy examples #
##################
some examples of what i find handy:
see TEST -help for more options
test verbosely
% t/TEST -verbose
start the server
% t/TEST -start
run just this test (if server is running, will not be re-started)
% t/TEST t/apr/table
run just the apr tests
% t/TEST t/apr
run all tests without start/stop of server (e.g. server was started with -d)
% t/TEST -run
stop the server
% t/TEST -stop
ping the server to see whether it runs
% t/TEST -ping
ping the server and wait until the server starts, report waiting time
% t/TEST -ping=block
reconfigure the server, do not run tests
% t/TEST -configure
run as user nobody:
% t/TEST -User nobody
run on a different port:
% t/TEST -Port 8799
let the program pick the next available port (useful when running a
few test sessions on parallel)
% t/TEST -Port select
run on a different server:
% t/TEST -servername example.com
configure an httpd other than the default (that apxs figures out)
% t/TEST -httpd ~/ap/httpd-2.0/httpd
configure a DSO mod_perl object other than the default (that stored in
Apache::BuildConfig)
% t/TEST -libmodperl ~/ap/httpd-2.0/modules/mod_perl-5.8.0.so
or one that can be found relative to LIBEXECDIR
% t/TEST -libmodperl mod_perl-5.6.1.so
switch to another apxs
% t/TEST -apxs ~/ap/httpd-2.0-prefork/bin/apxs
turn on tracing
% t/TEST -preamble "PerlTrace all"
GET url
% t/TEST -get /server-info
HEAD url
% t/TEST -head /server-info
HEAD (no url defaults to /)
% t/TEST -head
GET url with authentication credentials
% t/TEST -get /server-info -username dougm -password foo
POST url (read content from string)
% t/TEST -post /TestApache::post -content 'name=dougm&company=covalent'
POST url (read content from stdin)
% t/TEST -post /TestApache::post -content - < foo.txt
POST url (generate a body of data 1024 bytes in length)
% t/TEST -post /TestApache::post -content x1024
POST url (only print headers, e.g. useful to just check Content-length)
% t/TEST -post -head /TestApache::post -content x100000
GET url (only print headers, e.g. useful to just check Content-length)
% t/TEST -get -head /foo
start server under gdb
% t/TEST -debug
start server under strace (outputs to t/logs/strace.log)
% t/TEST -d strace
run .t test under the perl debugger
% t/TEST -d perl t/modules/access.t
run .t test under the perl debugger (nonstop mode, output to t/logs/perldb.out)
% t/TEST -d perl=nostop t/modules/access.t
control how much noise Apache::Test should produce. to print all the
debug messages:
% t/TEST -trace=debug
to print only warnings and higher trace levels:
% t/TEST -trace=warning
the available modes are:
emerg alert crit error warning notice info debug
turn on -v and LWP trace (1 is the default) mode in Apache::TestRequest
% t/TEST -d lwp t/modules/access.t
turn on -v and LWP trace mode (level 2) in Apache::TestRequest
% t/TEST -d lwp=2 t/modules/access.t
run all tests through mod_ssl
% t/TEST -ssl
run all tests with HTTP/1.1 (keep alive) requests
% t/TEST -http11 -ssl
run all tests with HTTP/1.1 (keep alive) requests through mod_ssl
% t/TEST -http11
run all tests through mod_proxy
% t/TEST -proxy
##################
# Stress testing #
##################
run all tests 10 times in a random order (the seed is autogenerated
and reported)
% t/SMOKE -times=10 -order=random
run all tests 10 times in a random order using the seed obtained from
the previous random run (e.g. 2352211):
% t/SMOKE -times=10 -order=2352211
repeat all tests 10 times (a, b, c, a, b, c)
% t/SMOKE -times=10 -order=repeat
When certain tests fail when running with -times option, you want to
find out the minimal sequence of tests that lead to the
failure. Apache::TestSmoke helps to ease this task, simply run:
% t/SMOKE
which tries various sequences of tests and at the end reports the
shortest sequences found that lead to the same failure.
for more options do:
% t/SMOKE -help