perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/devel/writing_tests writing_tests.pod
Date Thu, 27 Dec 2001 07:04:35 GMT
stas        01/12/26 23:04:35

  Modified:    src/docs/2.0/devel/writing_tests writing_tests.pod
  Log:
  - port README to extensively document Request Generation and Response
  Options, + runtime confguration options
  
  Revision  Changes    Path
  1.28      +213 -14   modperl-docs/src/docs/2.0/devel/writing_tests/writing_tests.pod
  
  Index: writing_tests.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/writing_tests/writing_tests.pod,v
  retrieving revision 1.27
  retrieving revision 1.28
  diff -u -r1.27 -r1.28
  --- writing_tests.pod	2001/12/27 05:08:42	1.27
  +++ writing_tests.pod	2001/12/27 07:04:35	1.28
  @@ -57,8 +57,8 @@
   it.
   
   It's important to know that there is a special verbose mode, enabled
  -with the I<-v> option, in which everything printed by the test goes to
  -C<STDOUT>. So for example if your test does this:
  +with the I<-verbose> option, in which everything printed by the test
  +goes to C<STDOUT>. So for example if your test does this:
   
     print "# testing : feature foo\n";
     print "# expected: $expected\n";
  @@ -66,7 +66,7 @@
     ok $expected eq $received;
   
   in the normal mode, you won't see any of these prints. But if you run
  -the test with I<t/TEST -v>, you will see something like this:
  +the test with I<t/TEST -verbose>, you will see something like this:
   
     # testing : feature foo
     # expected: 2
  @@ -133,11 +133,11 @@
   In case something goes wrong you should run the tests in the verbose
   mode:
   
  -  % t/TEST -v
  +  % t/TEST -verbose
   
   In this case the test may print useful information, like what values
   it expects and what values it receives, given that the test is written
  -to report these. In the silent mode (without C<-v>) these printouts
  +to report these. In the silent mode (without C<-verbose>) these printouts
   are suppressed by the test suite.
   
   When debugging problems it helps to keep the I<error_log> file open in
  @@ -196,10 +196,10 @@
   
   When you run specific tests you may want to run them in the verbose
   mode, and depending on how the test was written, you may get more
  -debug information under this mode. This mode is turned on with I<-v>
  +debug information under this mode. This mode is turned on with I<-verbose>
   option:
   
  -  % t/TEST -run -v protocol/echo
  +  % t/TEST -run -verbose protocol/echo
   
   You can run all the tests in a single directory by just passing this
   directory as an argument. You can pass more than one test or directory
  @@ -465,10 +465,185 @@
   Finally, any other options passed will be forwarded to C<t/TEST> as
   is.
   
  -=head2 Advanced Testing
  +=head2 RunTime Configuration Overriding
   
  +After the server is configured during C<make test> or with C<t/TEST
  +-config>, it's possible to explicitly override certain configuration
  +parameters. The override-able parameters are listed when executing:
   
  +  % t/TEST -help
   
  +Probably the most useful parameters are:
  +
  +=over
  +
  +=item * -preamble
  +
  +configuration directives to add at the beginning of I<httpd.conf>.
  +For example to turn the tracing on:
  +
  +  % t/TEST -preamble "PerlTrace all"
  +
  +=item * -postamble
  +
  +configuration directives to add at the end of I<httpd.conf>. For
  +example to load a certain Perl module:
  +
  +  % t/TEST -postamble "PerlModule MyDebugMode"
  +
  +=item * -user
  +
  +run as user I<nobody>:
  +
  +  % t/TEST -user nobody
  +
  +=item * -port
  +
  +run on a different port:
  +
  +  % t/TEST -port 8799
  +
  +=item * -servername
  +
  +run on a different server:
  +
  +  % t/TEST -servername test.example.com
  +
  +=item * -httpd
  +
  +configure an httpd other than the default (that apxs figures out):
  +
  +  % t/TEST -httpd ~/httpd-2.0/httpd
  +
  +=item * -apxs
  +
  +switch to another apxs:
  +
  +  % t/TEST -apxs ~/httpd-2.0-prefork/bin/apxs
  +
  +=back
  +
  +For a complete list of override-able configuration parameters see the
  +output of C<t/TEST -help>.
  +
  +=head2 Request Generation and Response Options
  +
  +We have mentioned already the most useful run-time options. Here are
  +some other options that you may find useful during testing.
  +
  +=over
  +
  +=item * -ping
  +
  +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
  +
  +This can be useful in conjunction with I<-run> option during debugging:
  +
  +  % t/TEST -ping=block -run
  +
  +normally, I<-run> will immediately quit if it detects that the server
  +is not running, but with I<-ping=block> in effect, it'll wait
  +indefinitely for the server to start up.
  +
  +=item * -head
  +
  +Issue a C<HEAD> request. For example to request I</server-info>:
  +
  +  % t/TEST -head /server-info
  +
  +=item * -get
  +
  +Request the body of a certain URL via C<GET>.
  +
  +  % t/TEST -get /server-info
  +
  +If no URL is specified C</> is used.
  +
  +ALso you can issue a C<GET> request but to get only headers as a
  +response (e.g. useful to just check C<Content-length>)
  +
  +  % t/TEST -head -get /server-info
  +
  +C<GET> URL with authentication credentials:
  +
  +  % t/TEST -get /server-info -username dougm -password domination
  +
  +(please keep the password secret!)
  +
  +=item * -post
  +
  +Generate a C<POST> request.
  +
  +Read content to C<POST> from string:
  +
  +  % t/TEST -post /TestApache::post -content 'name=dougm&company=covalent'
  +
  +Read content to C<POST> from C<STDIN>:
  +
  +  % t/TEST -post /TestApache::post -content - < foo.txt
  +
  +Generate a content body of 1024 bytes in length:
  +
  +  % t/TEST -post /TestApache::post -content x1024
  +
  +The same but print only the response headers, e.g. useful to just
  +check C<Content-length>:
  +
  +  % t/TEST -post -head /TestApache::post -content x1024
  +
  +=item * -header
  +
  +Add headers to (-get|-post|-head) request:
  +
  +  % t/TEST -get -header X-Test=10 -header X-Host=example.com /server-info
  +
  +=item * -ssl
  +
  +Run all tests through mod_ssl:
  +
  +  % t/TEST -ssl
  +
  +=item * -http11
  +
  +Run all tests with HTTP/1.1 (C<KeepAlive>) requests:
  +
  +  % t/TEST -http11
  +
  +=item * -proxy
  +
  +Run all tests through mod_proxy:
  +
  +  % t/TEST -proxy
  +
  +=item * 
  +
  +=back
  +
  +The debugging options I<-debug> and I<-breakpoint> are covered in the
  +L<Debugging> section.
  +
  +For a complete list of available switches see the output of C<t/TEST
  +-help>.
  +
  +=head2 Batch Mode
  +
  +When running in the batch mode and redirecting C<STDOUT>, this state
  +is automagically detected and the I<no color> mode is turned on, under
  +which the program generates a minimal output to make the log files
  +useful. If this doesn't work and you still get all the mess printed
  +during the interactive run, set the C<APACHE_TEST_NO_COLOR=1>
  +environment variable.
  +
  +
  +
  +
  +
   META: a lot more stuff to go here from the pods/modperl_dev.pod and
   Apache-Test/README
   
  @@ -1514,7 +1689,7 @@
   
   now we run the test:
   
  -  % ./t/TEST -run -v skip_subtest_1
  +  % ./t/TEST -run -verbose skip_subtest_1
     skip_subtest_1....1..4
     ok 1 # skip foo is missing
     ok 2 # skip foo is missing
  @@ -1558,7 +1733,7 @@
   
   and then ask to run only sub-tests 1 and 3 and to skip the rest.
   
  -  % ./t/TEST -v skip_subtest_2 1 3
  +  % ./t/TEST -verbose skip_subtest_2 1 3
     skip_subtest_2....1..4
     ok 1
     ok 2 # skip skipping this subtest
  @@ -1572,7 +1747,7 @@
   A range of sub-tests to run can be given using the Perl's range
   operand:
   
  -  % ./t/TEST -v skip_subtest_2 2..4
  +  % ./t/TEST -verbose skip_subtest_2 2..4
     skip_subtest_2....1..4
     ok 1 # skip askipping this subtest
     not ok 2
  @@ -1643,9 +1818,9 @@
   
   No debug help here, since in a non-verbose mode the debug comments
   aren't printed.  If we run the same test using the verbose mode,
  -enabled with C<-v>:
  +enabled with C<-verbose>:
   
  -  % t/TEST -v debug_comments
  +  % t/TEST -verbose debug_comments
     debug_comments....1..1
     # testing feature foo
     # expected: a good value
  @@ -1986,6 +2161,30 @@
   Perl and C debuggers, and this knowledge will save you a lot of time
   and grief in a long run.
   
  +=head2 Tracing
  +
  +Start the server under strace(1):
  +
  +  % t/TEST -debug strace
  +
  +The output goes to I<t/logs/strace.log>.
  +
  +META: complete
  +
  +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
  +
  +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
  +
  +
  +
   =head2 Under C debugger
   
   META: to be written
  @@ -1995,7 +2194,7 @@
   When the Perl code misbehaves it's the best to run it under the Perl
   debugger. Normally started as:
   
  -  % perl -d program.pl
  +  % perl -debug program.pl
   
   the flow control gets passed to the Perl debugger, which allows you to
   run the program in single steps and examine its states and variables
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message