stas 2002/12/13 02:46:20
Modified: src/docs/general/testing testing.pod
Log:
Document the following configuration issues:
- Virtual Hosts
- Running Pre-Configuration Code
- Controlling the Configuration Order (a new feature!)
Revision Changes Path
1.3 +155 -3 modperl-docs/src/docs/general/testing/testing.pod
Index: testing.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/general/testing/testing.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- testing.pod 2 Dec 2002 16:16:18 -0000 1.2
+++ testing.pod 13 Dec 2002 10:46:20 -0000 1.3
@@ -2429,11 +2429,163 @@
to a minimum and let Perl do the rest of the job for us.
+=head3 Virtual Hosts
+
+C<Apache::Test> automatically assigns an unused port for the virtual
+host configuration. Just make sure that you use the package name in
+the place where you usually specify a I<hostname:port> value. For
+example for the following package:
+
+ #file:MyApacheTest/Foo.pm
+ #------------------------
+ package MyApacheTest::Foo;
+ ...
+ 1;
+ __END__
+ <VirtualHost MyApacheTest::Foo>
+ <Location /test_foo>
+ ....
+ </Location>
+ </VirtualHost>
+
+After running:
+
+ % t/TEST -conf
+
+Check the autogenerated I<t/conf/httpd.conf> and you will find what
+port was assigned. Of course it can change when more tests which
+require a special virtual host are used.
+
+Now in the request script, you can figure out what port that virtual
+host was assigned, using the package name. For example:
+
+ #file:test_foo.t
+ #---------------
+ use Apache::TestRequest;
+
+ my $module = "MyApacheTest::Foo;";
+ my $config = Apache::Test::config();
+ Apache::TestRequest::module($module);
+ my $hostport = Apache::TestRequest::hostport($config);
+
+ print GET_BODY "http://$hostport/test_foo";;
+
+=head3 Running Pre-Configuration Code
+
+Sometimes you need to setup things for the test. This usually includes
+creating directories and files, and populating the latter with some
+data, which will be used at request time. Instead of performing that
+operation in the client script every time a test is run, it's usually
+better to do it once when the server is configured. If you wish to run
+such a code, all you have to do is to add a special subroutine
+C<APACHE_TEST_CONFIGURE> in the response package (assuming that that
+response package exists). When server is configured (C<t/TEST -conf>)
+it scans all the response packages for that subroutine and if found
+runs it.
+
+C<APACHE_TEST_CONFIGURE> accepts two arguments: the package name of
+the file this subroutine is defined in and the C<Apache::TestConfig>
+configuration object.
+
+Here is an example of a package that uses such a subroutine:
+
+ package TestDirective::perlmodule;
+
+ use strict;
+ use warnings FATAL => 'all';
+
+ use Apache::Test ();
+
+ use Apache::RequestRec ();
+ use Apache::RequestIO ();
+ use File::Spec::Functions qw(catfile);
+
+ use Apache::Const -compile => 'OK';
+
+ sub handler {
+ my $r = shift;
+
+ $r->content_type('text/plain');
+ $r->puts($ApacheTest::PerlModuleTest::MAGIC || '');
+
+ Apache::OK;
+ }
+
+ sub APACHE_TEST_CONFIGURE {
+ my ($class, $self) = @_;
+
+ my $vars = $self->{vars};
+ my $target_dir = catfile $vars->{documentroot}, 'testdirective';
+
+ my $magic = __PACKAGE__;
+ my $content = <<EOF;
+ package ApacheTest::PerlModuleTest;
+ \$ApacheTest::PerlModuleTest::MAGIC = '$magic';
+ 1;
+ EOF
+ my $file = catfile $target_dir,
+ 'perlmodule-vh', 'ApacheTest', 'PerlModuleTest.pm';
+ $self->writefile($file, $content, 1);
+ }
+ 1;
+
+In this example's function a directory is created. Then a file with
+some perl code as a content is created.
+
+
+=head3 Controling the Configuration Order
+
+Sometimes it's important in which order the configuration section of
+each response package is inserted. C<Apache::Test> controls the
+insertion order using a special token C<APACHE_TEST_CONFIG_ORDER>. To
+decide on the configuration insertion order, C<Apache::Test> scans all
+response packages and tries to match the following pattern:
+
+ /APACHE_TEST_CONFIG_ORDER\s+([+-]?\d+)/
+
+So you can assign any integer number (positive or negative). If the
+match fails, it's assumed that the token's value is 0. Next a simple
+numerical search is performed and those configuration sections with
+lower token value are inserted first.
+
+It's not specified how sections with the same token value are
+ordered. This usually depends on the order the files were read from
+the disk, which may vary from machine to machine and shouldn't be
+relied upon.
+
+As already mentioned by default all configuration sections have a
+token whose value is 0, meaning that their ordering is
+unimportant. Now if you want to make sure that some section is
+inserted first, assign to it a negative number, e.g.:
+
+ # APACHE_TEST_CONFIG_ORDER -150
+
+Now if a new test is added and it has to be the first, add to this new
+test a token with a negative value whose absolute value is higher than
+C<-150>, e.g.:
+
+ # APACHE_TEST_CONFIG_ORDER -151
+
+or
+
+ # APACHE_TEST_CONFIG_ORDER -500
+
+Decide how big the gaps should be by thinking ahead. This is similar
+to the Basic language line numbering ;) In any case, you can always
+adjust other tests' token if you need to squeeze a number between two
+consequent integers.
+
+If on the other hand you want to ensure that some test is configured
+last, use the highest positive number, e.g.:
+
+ # APACHE_TEST_CONFIG_ORDER 100
+
+If some other test needs to be configured just before the one we just
+inserted, assign a token with a lower value, e.g.:
+
+ # APACHE_TEST_CONFIG_ORDER 99
-META: Virtual host?
-META: a special -configure time method in response part:
-APACHE_TEST_CONFIGURE
=head2 Threaded versus Non-threaded Perl Test's Compatibility
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
