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:33:03 GMT
stas        01/12/26 23:33:03

  Modified:    src/docs/2.0/devel/writing_tests writing_tests.pod
  Log:
  - cleanups and re-shuffles
  
  Revision  Changes    Path
  1.29      +123 -123  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.28
  retrieving revision 1.29
  diff -u -r1.28 -r1.29
  --- writing_tests.pod	2001/12/27 07:04:35	1.28
  +++ writing_tests.pod	2001/12/27 07:33:03	1.29
  @@ -99,7 +99,7 @@
   If you install mod_perl 2.x, you get C<Apache::Test> installed as
   well.
   
  -=head1 How to Run Tests
  +=head1 Running Tests
   
   It's much easier to copy-cat things, than creating from scratch.  It's
   much easier to develop tests, when you have some existing system that
  @@ -329,7 +329,7 @@
   
   =back
   
  -=head2 Resolving Sequence Problems
  +=head3 Resolving Sequence Problems
   
   When this kind of testing is used and a failure is detected there are
   two problems:
  @@ -356,7 +356,7 @@
   
   =back
   
  -=head2 Apache::TestSmoke Solution
  +=head3 Apache::TestSmoke Solution
   
   C<Apache::TestSmoke> attempts to solve both problems. When it's run,
   at the end of each iteration it reports the minimal sequence of tests
  @@ -366,8 +366,8 @@
   You should create a small script to drive C<Apache::TestSmoke>,
   usually I<t/SMOKE.PL>. If you don't have it already, create it:
   
  -  t/SMOKE.PL
  -  ----------
  +  file:t/SMOKE.PL
  +  ---------------
     #!perl
     
     use strict;
  @@ -640,21 +640,17 @@
   during the interactive run, set the C<APACHE_TEST_NO_COLOR=1>
   environment variable.
   
  +=head1 Setting Up Testing Environment
   
  -
  -
  -
  -META: a lot more stuff to go here from the pods/modperl_dev.pod and
  -Apache-Test/README
  -
  -=head1 How to Setup Testing Environment
  -
   We will assume that you setup your testing environment even before you
  -have started developing the module, which is a very smart thing to do.
  +have started coding the project, which is a very smart thing to do.
   Of course it'll take you more time upfront, but it'll will save you a
  -lot of time as you develop and debug your code. The L<extreme
  -programming methodology|/item_extreme_programming_methodology> says
  -that tests should be written before starting the code development.
  +lot of time during the project developing and debugging stages. The
  +L<extreme programming
  +methodology|/item_extreme_programming_methodology> says that tests
  +should be written before starting the code development.
  +
  +=head2 Basic Testing Environment
   
   So the first thing is to create a package and all the helper files, so
   later on we can distribute it on CPAN. We are going to develop an
  @@ -872,7 +868,7 @@
              "basic test",
             );
   
  -Now create the README file.
  +Now create the I<README> file.
   
     % touch README
   
  @@ -890,13 +886,13 @@
                  ...
                  );
   
  -in this case C<README> will be created from the documenation POD
  +in this case I<README> will be created from the documenation POD
   sections in I<lib/Apache/Amazing.pm>, but the file has to exists for
   I<make dist> to succeed.
   
  -and finally we adjust or create the C<MANIFEST> file, so we can
  +and finally we adjust or create the I<MANIFEST> file, so we can
   prepare a complete distribution. Therefore we list all the files that
  -should enter the distribution including the C<MANIFEST> file itself:
  +should enter the distribution including the I<MANIFEST> file itself:
   
     file:MANIFEST
     -------------
  @@ -938,6 +934,95 @@
   how amazingly it works and how amazingly it can be deployed by other
   users.
   
  +
  +=head2 Extending Configuration Setup
  +
  +Sometimes you need to add extra I<httpd.conf> configuration and perl
  +startup specific to your project that uses C<Apache::Test>. This can
  +be accomplished by creating the desired files with an extension I<.in>
  +in the I<t/conf/> directory and running:
  +
  +  panic% t/TEST -config
  +
  +which for each file with the extension I<.in> will create a new file,
  +without this extension, convert any template placeholders into real
  +values and link it from the main I<httpd.conf>. The latter happens
  +only if the file have the following extensions:
  +
  +=over
  +
  +=item * .conf.in
  +
  +will add to I<t/conf/httpd.conf>:
  +
  +  Include foo.conf
  +
  +=item * .pl.in
  +
  +will add to I<t/conf/httpd.conf>:
  +
  +  PerlRequire foo.pl
  +
  +=item * other
  +
  +other files with I<.in> extension will be processed as well, but not
  +linked from I<httpd.conf>.
  +
  +=back
  +
  +As mentioned before the converted files are created, any special token
  +in them are getting replaced with the appropriate values. For example
  +the token C<@ServerRoot@> will be replaced with the value defined by
  +the C<ServerRoot> directive, so you can write a file that does the
  +following:
  +
  +  file:my-extra.conf.in
  +  ---------------------
  +  PerlSwitches -Mlib=@ServerRoot@/../lib
  +
  +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
  +  ---------------------
  +  PerlSwitches -Mlib=~/modperl-2.0/t/../lib
  +
  +The valid tokens are defined in C<%Apache::TestConfig::Usage> and also
  +can be seen in the output of C<t/TEST -help>'s I<configuration
  +options> section. The tokens are case insensitive.
  +
  +=head2 Special Configuration Files
  +
  +Some of the files in the I<t/conf> directory have a special meaning,
  +since the C<Apache::Test> framework uses them for the minimal
  +configuration setup. But they can be overriden:
  +
  +=over
  +
  +=item *
  +
  +if the file I<t/conf/httpd.conf.in> exists, it will be used instead of
  +the default template (in I<Apache/TestConfig.pm>).
  +
  +=item *
  +
  +if the file I<t/conf/extra.conf.in> exists, it will be used to
  +generate I<t/conf/extra.conf> with C<@variable@> substitutions.
  +
  +=item *
  +
  +if the file I<t/conf/extra.conf> exists, it will be included by
  +I<httpd.conf>.
  +
  +=item *
  +
  +if the file I<t/conf/modperl_extra.pl> exists, it will be included by
  +I<httpd.conf> as a mod_perl file (PerlRequire).
  +
  +=back
  +
  +
  +
   =head1 Apache::Test Framework's Architecture
   
   In the previous section we have written a basic test, which doesn't do
  @@ -1048,8 +1133,8 @@
   generate requests and check the response. So a typical test will look
   like this:
   
  -  t/apache/cool.t
  -  -----------
  +  file:t/apache/cool.t
  +  --------------------
     use strict;
     use warnings FATAL => 'all';
   
  @@ -1079,8 +1164,8 @@
   
   And the corresponding response part:
   
  -  t/response/TestApache/cool.pm:
  -  --------------------------
  +  file:t/response/TestApache/cool.pm
  +  ----------------------------------
     package TestApache::cool;
     
     use strict;
  @@ -1301,8 +1386,8 @@
   Here is an example from C<ModPerl::Registry> closure tests. Using the
   counter closure problem under C<ModPerl::Registry>:
   
  -  cgi-bin/closure.pl
  -  ------------------
  +  file:cgi-bin/closure.pl
  +  -----------------------
     #!perl -w
     print "Content-type: text/plain\r\n\r\n";
     
  @@ -1321,8 +1406,8 @@
   makes sure that its two subsequent requests hit the same server
   instance:
   
  -  closure.t
  -  ---------
  +  file:closure.t
  +  --------------
     ...
     my $url = "/same_interp/cgi-bin/closure.pl";
     my $same_interp = Apache::TestRequest::same_interp_tie($url);
  @@ -1369,7 +1454,7 @@
   its unique id matches. As you understand this technique would be very
   inefficient in production with many server instances.
   
  -=head1 How to Write Tests
  +=head1 Writing Tests
   
   All the communications between tests and C<Test::Harness> which
   executes them is done via STDOUT. I.e. whatever tests want to report
  @@ -1538,8 +1623,8 @@
   
   If all files in a directory I<t/foo> should be skipped, create:
   
  -  t/foo/all.t:
  -  ------------
  +  file:t/foo/all.t
  +  ----------------
     print "1..0\n";
   
   Alternatively you can specify which tests should be skipped from a
  @@ -1549,8 +1634,8 @@
   
   For example if in mod_perl 2.0 test suite we create the following file:
   
  -  t/SKIP:
  -  -------
  +  file:t/SKIP
  +  -----------
     # skip all files in protocol
     protocol
     
  @@ -1722,8 +1807,8 @@
   ok(), the rest will be skipped.  If no sub-tests are specified, sok()
   works just like ok().  For example, you can write this test:
   
  -  skip_subtest_2.t
  -  --------------
  +  file:skip_subtest_2.t
  +  ---------------------
     use Apache::Test;
     plan tests => 4;
     sok {1};
  @@ -1797,8 +1882,8 @@
   does, what is the expected value and what's the received value. This
   is a good example of debug friendly sub-test:
   
  -  debug_comments.t
  -  ----------------
  +  file:debug_comments.t
  +  ---------------------
     use Apache::Test;
     use Apache::TestUtil;
     plan tests => 1;
  @@ -2035,91 +2120,6 @@
   
   META: to be completed
   
  -=head2 Extending Startup Configuration for httpd and Perl
  -
  -Sometimes you need to add extra I<httpd.conf> configuration and perl
  -startup specific to your project that uses C<Apache::Test>. This can
  -be accomplished by creating the desired files with an extension I<.in>
  -in the I<t/conf/> directory and running:
  -
  -  panic% t/TEST -config
  -
  -which for each file with the extension I<.in> will create a new file,
  -without this extension, convert any template placeholders into real
  -values and link it from the main I<httpd.conf>. The latter happens
  -only if the file have the following extensions:
  -
  -=over
  -
  -=item * .conf.in
  -
  -will add to I<t/conf/httpd.conf>:
  -
  -  Include foo.conf
  -
  -=item * .pl.in
  -
  -will add to I<t/conf/httpd.conf>:
  -
  -  PerlRequire foo.pl
  -
  -=item * other
  -
  -other files with I<.in> extension will be processed as well, but not
  -linked from I<httpd.conf>.
  -
  -=back
  -
  -As mentioned before the converted files are created, any special token
  -in them are getting replaced with the appropriate values. For example
  -the token C<@ServerRoot@> will be replaced with the value defined by
  -the C<ServerRoot> directive, so you can write a file that does the
  -following:
  -
  -  my-extra.conf.in
  -  ----------------
  -  PerlSwitches -Mlib=@ServerRoot@/../lib
  -
  -and assuming that the I<ServerRoot> is I<~/modperl-2.0/t/>, when
  -I<my-extra.conf> will be created, it'll look like:
  -
  -  my-extra.conf.in
  -  ----------------
  -  PerlSwitches -Mlib=~/modperl-2.0/t/../lib
  -
  -The valid tokens are defined in C<%Apache::TestConfig::Usage> and also
  -can be seen in the output of C<t/TEST -help>'s I<configuration
  -options> section. The tokens are case insensitive.
  -
  -=head2 Special Configuration Files
  -
  -Some of the files in the I<t/conf> directory have a special meaning,
  -since the C<Apache::Test> framework uses them for the minimal
  -configuration setup. But they can be overriden:
  -
  -=over
  -
  -=item *
  -
  -if the file I<t/conf/httpd.conf.in> exists, it will be used instead of
  -the default template (in I<Apache/TestConfig.pm>).
  -
  -=item *
  -
  -if the file I<t/conf/extra.conf.in> exists, it will be used to
  -generate I<t/conf/extra.conf> with C<@variable@> substitutions.
  -
  -=item *
  -
  -if the file I<t/conf/extra.conf> exists, it will be included by
  -I<httpd.conf>.
  -
  -=item *
  -
  -if the file I<t/conf/modperl_extra.pl> exists, it will be included by
  -I<httpd.conf> as a mod_perl file (PerlRequire)
  -
  -=back
   
   =head2 Threaded versus Non-threaded Perl Test's Compatibility
   
  
  
  

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