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 11:11:13 GMT
stas        01/12/27 03:11:13

  Modified:    src/docs/2.0/devel/writing_tests writing_tests.pod
  Log:
  - completing the porting of 'make test' docs from modperl_dev.pod
  
  Revision  Changes    Path
  1.30      +170 -89   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.29
  retrieving revision 1.30
  diff -u -r1.29 -r1.30
  --- writing_tests.pod	2001/12/27 07:33:03	1.29
  +++ writing_tests.pod	2001/12/27 11:11:13	1.30
  @@ -56,10 +56,13 @@
   proceed with the tests and it's not a must pass test, you just skip
   it.
   
  -It's important to know that there is a special verbose mode, enabled
  -with the I<-verbose> option, in which everything printed by the test
  -goes to C<STDOUT>. So for example if your test does this:
  +=head2 Verbose Testing
   
  +By default print() statements in the test script are filtered out by
  +C<Test::Harness>.  if you want the test to print what it does (if you
  +decide to debug some test) use C<-verbose> option. So for example if
  +your test does this:
  +
     print "# testing : feature foo\n";
     print "# expected: $expected\n";
     print "# received: $received\n";
  @@ -80,8 +83,8 @@
   mode and send you back the report. It'll be much easier to understand
   what the problem is if you get these debug printings from the user.
   
  -In the section L<"How to Write Tests"> we discuss a few helper
  -functions which make the tests writing easier.
  +In the section L<"Writing Tests"> several helper functions which make
  +the tests writing easier are discussed.
   
   For more details about the C<Test::Harness> module please refer to its
   manpage. Also see the C<Test> manpage about Perl's test suite.
  @@ -111,10 +114,19 @@
   testing environments which both use C<Apache::Test> for their test
   suites.
   
  +=head2 Testing Options
  +
  +Run:
  +
  +  % t/TEST -help
  +
  +to get the list of options you can use during testing. They are
  +covered in the rest of this document.
  +
   =head2 Basic Testing
   
  -Running tests is just like for any CPAN Perl module; first we create
  -the I<Makefile> and build everything with I<make>:
  +Running tests is just like for any CPAN Perl module; first we generate
  +the I<Makefile> file and build everything with I<make>:
   
     % perl Makefile.PL [options]
     % make
  @@ -125,44 +137,64 @@
     % make test
   
   but it adds quite an overhead, since it has to check that everything
  -is up to date (the usual C<make> source change control). Therefore
  -faster to run the tests directly via:
  +is up to date (the usual C<make> source change control). Therefore you
  +have to run it only once after C<make> and for re-running the tests
  +it's faster to run the tests directly via:
   
     % t/TEST
   
  -In case something goes wrong you should run the tests in the verbose
  -mode:
  +When C<make test> or C<t/TEST> are run, all tests found in the I<t>
  +directory (files ending with I<.t> are recognized as tests) will be
  +run.
   
  -  % t/TEST -verbose
  +=head2 Individual Testing
   
  -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<-verbose>) these printouts
  -are suppressed by the test suite.
  +To run a single test, simple specify it at the command line. For
  +example to run the test file I<t/protocol/echo.t>, execute:
   
  -When debugging problems it helps to keep the I<error_log> file open in
  -another console, and see the debug output in the real time via
  -tail(1):
  +  % t/TEST protocol/echo
   
  -  % tail -f t/logs/error_log
  +Notice that you don't have to add the I<t/> prefix and I<.t> extension
  +for the test filenames if you specify them explicitly, but you can
  +have these as well. Therefore the following are all valid commands:
   
  -Of course this file gets created only when the server starts, so you
  -cannot run tail(1) on it before the server starts.
  +  % t/TEST   protocol/echo.t
  +  % t/TEST t/protocol/echo
  +  % t/TEST t/protocol/echo.t
  +
  +The server will be stopped if it was already running and a new one
  +will be started before running the I<t/protocol/echo.t> test. At the
  +end of the test the server will be shut down.
  +
  +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<-verbose> option:
  +
  +  % t/TEST -verbose protocol/echo
  +
  +You can run groups of tests at once. This command:
  +
  +  % ./t/TEST modules protocol/echo
  +
  +will run all the tests in I<t/modules/> directory, followed by
  +I<t/protocol/echo.t> test.
   
  -[F] Later on we will talk about I<-clean> option, for now just
  -remember that if you use it I<t/logs/error_log> is deleted, therefore
  -you have to run the tail(1) command again, when the server is
  -started. [/F]
  -
  -If you have to run the same tests repeatedly, in most cases you don't
  -want to wait for the server to start every time. You can start it
  -once:
   
  +=head2 Repetitive Testing
  +
  +By default when you run the test without I<-run-tests> option, the
  +server will be started before the testing and stopped at the end. If
  +during a debugging process you need to re-run tests without a need to
  +restart the server, you can start the server once:
  +
     % t/TEST -start-httpd
  +
  +and then run the test(s) with I<-run-tests> option many times:
   
  -and then run tests without restarting the server using I<-run> option:
  +  % t/TEST -run-tests
   
  -  % t/TEST -run
  +without waiting for the server to restart.
   
   When you are done with tests, stop the server with:
   
  @@ -182,45 +214,16 @@
     PerlSetVar ReloadModules "TestDirective::*"
   
   and restart the server.
  -
  -If none of the tests are specified at the command line all tests found
  -in the I<t> directory (files ending with I<.t> are recongnized as
  -tests) will be run. To run specific tests, they should be explicitly
  -specified. For example to run the test file I<t/protocol/echo.t> we
  -execute:
  -
  -  % t/TEST -run protocol/echo
  -
  -notice that you don't have to add the I<t/> prefix and I<.t> extension
  -for the test filenames if you specify them explicitly.
  -
  -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<-verbose>
  -option:
  -
  -  % 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
  -name at the same time. Thefore assuming that the directory
  -I<t/protocol> includes only two files: I<echo.t> and I<eliza.t>--the
  -following two commands are equivalent:
   
  -  % t/TEST -run protocol/echo protocol/eliza
  -  % t/TEST -run protocol
  +The I<-start-httpd> option always stops the server first if any is
  +running. In case you have a server runnning on the same port, (for
  +example if you develop the a few tests at the same time in different
  +trees), you should run the server on a different port. C<Apache::Test>
  +will try to automatically pick a free port, but you can explicitly
  +tell on which port to run, using the I<-port> configuration option:
   
  -The command:
  +META: -port=select is not yet committed!
   
  -  % t/TEST -start-httpd
  -
  -always stops the server first if any is running. In case you have a
  -server runnning on the same port, (for example if you develop the a
  -few tests at the same time in different trees), you should run the
  -server on a different port. C<Apache::Test> will try to automatically
  -pick a free port, but you can explicitly tell on which port to run,
  -using the I<-port> configuration option:
  -
     % t/TEST -start-httpd -port 8799
   
   or by setting an evironment variable C<APACHE_PORT> to the desired
  @@ -231,6 +234,31 @@
   passed as arguments to I<t/TEST> they will be run in a specified
   order.
   
  +=head2 Verbose Testing
  +
  +In case something goes wrong you should run the tests in the verbose
  +mode:
  +
  +  % 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<-verbose>) these
  +printouts are filtered out by C<Test::Harness>. When running in the
  +I<verbose> mode usually it's a good idea to run only problematic tests
  +to minimize the size of the generated output.
  +
  +When debugging problems it helps to keep the I<error_log> file open in
  +another console, and see the debug output in the real time via
  +tail(1):
  +
  +  % tail -f t/logs/error_log
  +
  +Of course this file gets created only when the server starts, so you
  +cannot run tail(1) on it before the server starts. Every time C<t/TEST
  +-clean> is run, I<t/logs/error_log> gets deleted, therefore you have
  +to run the tail(1) command again, when the server is started.
  +
   =head2 Stress Testing
   
   =head3 The Problem
  @@ -543,11 +571,11 @@
   
     % t/TEST -ping=block
   
  -This can be useful in conjunction with I<-run> option during debugging:
  +This can be useful in conjunction with I<-run-tests> option during debugging:
   
  -  % t/TEST -ping=block -run
  +  % t/TEST -ping=block -run-tests
   
  -normally, I<-run> will immediately quit if it detects that the server
  +normally, I<-run-tests> 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.
   
  @@ -983,8 +1011,8 @@
   and assuming that the I<ServerRoot> is I<~/modperl-2.0/t/>, when
   I<my-extra.conf> will be created, it'll look like:
   
  -  file:my-extra.conf.in
  -  ---------------------
  +  file:my-extra.conf
  +  ------------------
     PerlSwitches -Mlib=~/modperl-2.0/t/../lib
   
   The valid tokens are defined in C<%Apache::TestConfig::Usage> and also
  @@ -1774,7 +1802,7 @@
   
   now we run the test:
   
  -  % ./t/TEST -run -verbose skip_subtest_1
  +  % ./t/TEST -run-tests -verbose skip_subtest_1
     skip_subtest_1....1..4
     ok 1 # skip foo is missing
     ok 2 # skip foo is missing
  @@ -2161,34 +2189,55 @@
   Perl and C debuggers, and this knowledge will save you a lot of time
   and grief in a long run.
   
  -=head2 Tracing
  +=head2 Under C debugger
   
  -Start the server under strace(1):
  +mod_perl-2.0 provides built in 'make test' debug facility. So in case
  +you get a core dump during make test, or just for fun, run in one shell:
   
  -  % t/TEST -debug strace
  +  % t/TEST -debug
   
  -The output goes to I<t/logs/strace.log>.
  +in another shell:
   
  -META: complete
  +  % t/TEST -run-tests
   
  -run .t test under the perl debugger
  -% t/TEST -d perl t/modules/access.t
  +then the I<-debug> shell will have a C<(gdb)> prompt, type C<where>
  +for stacktrace:
   
  -run .t test under the perl debugger (nonstop mode, output to t/logs/perldb.out)
  -% t/TEST -d perl=nostop t/modules/access.t
  +  (gdb) where
   
  -turn on -v and LWP trace (1 is the default) mode in Apache::TestRequest
  -% t/TEST -d lwp t/modules/access.t
  +You can change the default debugger by supplying the name of the
  +debugger as an argument to I<-debug>. E.g. to run the server under
  +C<ddd>:
   
  -turn on -v and LWP trace mode (level 2) in Apache::TestRequest
  -% t/TEST -d lwp=2 t/modules/access.t
  +  % ./t/TEST -debug=ddd
   
  +META: list supported debuggers
   
  +If you debug mod_perl internals you can set the breakpoints using the
  +I<-breakpoint> option, which can be repeated as many times as
  +needed. When you set at least one breakpoint, the server will start
  +running till it meets the I<ap_run_pre_config> breakpoint. At this
  +point we can set the breakpoint for the mod_perl code, something we
  +cannot do earlier if mod_perl was built as DSO. For example:
   
  -=head2 Under C debugger
  +  % ./t/TEST -debug -breakpoint=modperl_cmd_switches \
  +     -breakpoint=modperl_cmd_options
  +
  +will set the I<modperl_cmd_switches> and I<modperl_cmd_options>
  +breakpoints and run the debugger.
  +
  +If you want to tell the debugger to jump to the start of the mod_perl
  +code you may run:
  +
  +  % ./t/TEST -debug -breakpoint=modperl_hook_init
  +
  +In fact I<-breakpoint> automatically turns on the debug mode, so you
  +can run:
  +
  +  % ./t/TEST -breakpoint=modperl_hook_init
   
  -META: to be written
   
  +
   =head2 Under Perl debugger
   
   When the Perl code misbehaves it's the best to run it under the Perl
  @@ -2209,6 +2258,38 @@
   go:
   
   META: to be completed
  +
  +run .t test under the perl debugger
  +% t/TEST -debug perl t/modules/access.t
  +
  +run .t test under the perl debugger (nonstop mode, output to t/logs/perldb.out)
  +% t/TEST -debug perl=nostop t/modules/access.t
  +
  +turn on -v and LWP trace (1 is the default) mode in Apache::TestRequest
  +% t/TEST -debug lwp t/modules/access.t
  +
  +turn on -v and LWP trace mode (level 2) in Apache::TestRequest
  +% t/TEST -debug lwp=2 t/modules/access.t
  +
  +
  +=head2 Tracing
  +
  +To get Start the server under strace(1):
  +
  +  % t/TEST -debug strace
  +
  +The output goes to I<t/logs/strace.log>.
  +
  +Now in a second terminal run:
  +
  +  % t/TEST -run-tests
  +
  +Beware that I<t/logs/strace.log> is going to be very big.
  +
  +META: can we provide strace(1) opts if we want to see only certain
  +syscalls?
  +
  +
   
   
   =head1 Writing Tests Methodology
  
  
  

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