#########
# 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:
http://perl.apache.org/docs/general/testing/testing.html
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:
http://www.perl.com/pub/a/2003/05/22/testing.html
###################
# Got a question? #
###################
Post it to the test-dev 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.
For more information see: http://perl.apache.org/projects/Apache-Test/index.html
List Archives:
# www.apachelabs.org
http://www.apachelabs.org/test-dev/
# marc.theaimsgroup.com
http://marc.theaimsgroup.com/?l=apache-modperl-test-dev
# Mbox file
http://perl.apache.org/mail/test-dev/
##############
# 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