#########
# 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 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

##############
# 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/netlib.t

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/TEST -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/TEST -times=10 -order=2352211

rotate all tests 10 times (a, b, c, a, b, c)
% t/TEST -times=10 -order=rotate

repeat all tests 10 times (a, a, b, b, c, c)
% t/TEST -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