On Aug 24, 2004, at 3:09 PM, Randy Kobes wrote:
Yes, F<> is understood (I've been using it for the Win32 sections). There's a neat feature in the html conversion - if there's a (physical) file "foo", F<foo> will become a link to "foo".
Ah, yeah, that's slick. Thanks Randy.
So I made it as far as "Stress Testing", but then just filled in Apache::TestMB information in the rest of the document. Hopefully I can get to editing the remainder for grammar, punctuation, etc. sometime soon.
Let me know if this looks good to you guys and I'll commit it.
Regards,
David
Index: src/docs/general/testing/testing.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/general/testing/testing.pod,v retrieving revision 1.34 diff -u -r1.34 testing.pod --- src/docs/general/testing/testing.pod 16 Jul 2004 21:46:11 -0000 1.34 +++ src/docs/general/testing/testing.pod 24 Aug 2004 21:54:31 -0000 @@ -6,12 +6,12 @@
The title is self-explanatory :)
-The C<Apache::Test> framework was designed for creating test suits for -products running on Apache httpd webserver (not necessarily +The C<Apache::Test> framework was designed for creating test suites for +products running on the Apache httpd webserver (not necessarily mod_perl). Originally designed for the mod_perl Apache module, it was extended to be used for any Apache module.
-This chapter is talking about the C<Apache::Test> framework, and in +This chapter discusses the C<Apache::Test> framework, and in particular explains how to:
=over
@@ -27,29 +27,30 @@
For other C<Apache::Test> resources, see the L<References|/"References">
section at the end of this document.
-=head1 Basics of Perl Modules Testing +=head1 Basics of Perl Module Testing
The tests themselves are written in Perl. The framework provides an -extensive functionality which makes the tests writing a simple and +extensive functionality which makes writing tests a simple and therefore enjoyable process.
-If you have ever written or looked at the tests most Perl modules come
-with, C<Apache::Test> uses the same concept. The script I<t/TEST> is
-running all the files ending with I<.t> it finds in the I<t/>
-directory. When executed a typical test prints the following:
+If you have ever written or looked at the tests that come with most Perl
+modules, you'll recognize that C<Apache::Test> uses the same
+concepts. The script I<t/TEST> executes runs all the files ending with
+I<.t> that it finds in the I<t/> directory. When executed, a typical test
+prints the following:
1..3 # going to run 3 tests ok 1 # the first test has passed ok 2 # the second test has passed not ok 3 # the third test has failed
-Every C<ok> or C<not ok> is followed by the number which tells which -sub-test has succeeded or failed. +Every C<ok> or C<not ok> is followed by a number that identifies which +sub-test has passed or failed.
-I<t/TEST> uses the C<Test::Harness> module which intercepts the -C<STDOUT> stream, parses it and at the end of the tests print the -results of the tests running: how many tests and sub-tests were run, -how many succeeded, skipped or failed. +I<t/TEST> uses the C<Test::Harness> module, which intercepts the +C<STDOUT> stream, parses it and at the end of the tests, prints the +results of the tests: how many tests and sub-tests were run and +how many passed, failed, or were skipped.
Some tests may be skipped by printing:
@@ -57,13 +58,13 @@
Usually a test may be skipped when some feature is optional and/or
prerequisites are not installed on the system, but this is not
-critical for the usefulness of the test. Once you test that you cannot
-proceed with the tests and it's not a must pass test, you just skip
-it.
-
-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
+critical for the usefulness of the test. Once you determine that
+you cannot proceed with the tests, and it is not a requirement that
+the tests pass, you can just skip them.
+
+By default, C<print> statements in the test script are filtered out by
+C<Test::Harness>. If you want the test to print what it does (for example,
+to debug a test) use the C<-verbose> option. So for example if
your test does this:
print "# testing : feature foo\n"; @@ -72,25 +73,50 @@ 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 -verbose>, you will see something like this: +the test with C<t/TEST -verbose>, you will see something like this:
# testing : feature foo # expected: 2 # received: 2 ok 2
-When you develop the test you should always put the debug statements
-there, and once the test works for you do not comment out or delete
-these debug statements. This is because if some user reports a failure
-in some test, you can ask him to run the failing test in the verbose
-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.
+When you develop the test you should always insert the debug statements,
+and once the test works for you, do not comment out or delete these
+debug statements. It's a good idea to leave them in because if some user
+reports a failure in some test, you can ask him to run the failing test
+in the verbose mode and send you the report. It'll be much easier to
+understand the problem if you get these debug printings from the user.
+
+A simpler approach is to use the C<Test::More> module in your test
+scripts. This module offers many useful test functions, including
+C<diag>, a function that automatically escapes and passes strings to
+C<print> to bypass C<Test::Harnes>:
+
+ use Test::More;
+ diag "testing : feature foo\n";
+ diag "expected: $expected\n";
+ diag "received: $received\n";
+ ok $expected eq $received;
+
+In fact, for an example such as this, you can just use Test::More's
+C<is> function, which will output the necessary diagnostics in the event
+of a test failure:
+
+ is $received, $expected;
+
+For which the output for a test failure would be something like:
+
+not ok 1
+# Failed test (-e at line 1)
+# got: '1'
+# expected: '2'
-In the section L<Writing Tests|/"Writing_Tests"> several helper functions which make
-the tests writing easier are discussed.
+The L<Writing Tests|/"Writing_Tests"> section documents several helper
+functions that make simplify the writing of tests.
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. +manpage. Also see the C<Test> and C<Test::More> manpages for +documentation of Perl's test suite.
=head1 Prerequisites
@@ -102,19 +128,18 @@ % perl Makefile.PL % make && make test && make install
-If you install mod_perl 2.0, you get C<Apache::Test> installed as -well. +If you install mod_perl 2.0, C<Apache::Test> will be installed with it.
=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
-you can test, see how it works and build your own testing environment
-in a similar fashion. Therefore let's first look at how the existing
-test enviroments work.
+It's much easier to copy existing examples than to create something from
+scratch. It's also simpler to develop tests when you have some existing
+system that to test, so that you can see how it works and build your own
+testing environment in a similar fashion. So let's first look at how the
+existing test enviroments work.
You can look at the modperl-2.0's or httpd-test's (I<perl-framework>) -testing environments which both use C<Apache::Test> for their test +testing environments, both of which use C<Apache::Test> for their test suites.
=head2 Testing Options @@ -123,7 +148,7 @@
% t/TEST -help
-to get the list of options you can use during testing. Most options +to get a list of options you can use during testing. Most options are covered further in this document.
=head2 Basic Testing @@ -135,31 +160,31 @@ % make
Now we can do the testing. You can run the tests in two ways. The -first one is usual: +first one is the usual:
% 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 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: +But this approach adds quite an overhead, since it has to check that +everything is up to date (the usual C<make> source change control). +Therefore, you have to run it only once after C<make>; for re-running +the tests, it's faster to run them directly via:
% t/TEST
-When C<make test> or C<t/TEST> are run, all tests found in the I<t> +When C<make test> or C<t/TEST> is run, all tests found in the I<t> directory (files ending with I<.t> are recognized as tests) will be run.
=head2 Individual Testing
-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: +To run a single test, simply specify it at the command line. For +example, to run the test file I<t/protocol/echo.t>, execute:
% t/TEST 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, but you can -have these as well. Therefore the following are all valid commands: +Notice that the I<t/> prefix and the I<.t> extension for the test +filenames are optional when you specify them explicitly. Therefore the +following are all valid commands:
% t/TEST protocol/echo.t % t/TEST t/protocol/echo @@ -170,13 +195,13 @@ 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 +mode and, depending on how the tests were written, you may get more +debugging information under this mode. Verbose mode is turned on with I<-verbose> option:
% t/TEST -verbose protocol/echo
-You can run groups of tests at once. This command: +You can run groups of tests at once, too. This command:
% ./t/TEST modules protocol/echo
@@ -186,10 +211,10 @@
=head2 Repetitive Testing
-By default when you run the test without I<-run-tests> option, the +By default, when you run tests without the 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: +during a debugging process you need to re-run tests without the need to +restart the server, you can start it once:
% t/TEST -start-httpd
@@ -203,39 +228,39 @@
% t/TEST -stop-httpd
-When the server is started you can modify I<.t> files and rerun the -tests without restarting the server. However if you modify response +When the server is running, you can modify I<.t> files and rerun the +tests without restarting it. But if you modify response handlers, you must restart the server for changes to take an -effect. However the changes are done in the perl code only, it's -possible to orrange for Apache::Test to L<handle the code reload +effect. However, if the changes are only to perl code, it's +possible to arrange for Apache::Test to L<handle the code reload without restarting the server|/Using_Apache__Test_to_Speed_up_Project_Development>.
The I<-start-httpd> option always stops the server first if any is running.
-Normally when I<t/TEST> is run without specifying the tests to run, +Normally, when I<t/TEST> is run without specifying the tests to run, the tests will be sorted alphabetically. If tests are explicitly -passed as arguments to I<t/TEST> they will be run in a specified +passed as arguments to I<t/TEST> they will be run in the specified order.
=head2 Parallel Testing
Sometimes you need to run more than one C<Apache::Test> framework instances at the same time. In this case you have to use different -ports for each instance. You can specify explicitly which port to use, -using the I<-port> configuration option. For example to run the server -on port 34343: +ports for each instance. You can specify explicitly which port to use +using the I<-port> configuration option. For example, to run the server +on port 34343, do this:
% t/TEST -start-httpd -port=34343
-or by setting an evironment variable C<APACHE_TEST_PORT> to the -desired value before starting the server. +You can also affect the port by setting the C<APACHE_TEST_PORT> +evironment variable to the desired value before starting the server.
Specifying the port explicitly may not be the most convenient option if you happen to run many instances of the C<Apache::Test> framework. -The I<-port=select> option comes to help. This option will -automatically pick for the next available port. For example if you +The I<-port=select> option helps such situations. This option will +automatically select the next available port. For example if you run:
% t/TEST -start-httpd -port=select @@ -243,48 +268,46 @@ and there is already one server from a different test suite which uses the default port 8529, the new server will try to use a higher port.
-There is one problem that remains to be resolved though. It's possible
+There is one problem that remains to be resolved, though. It's possible
that two or more servers running I<-port=select> will still decide to
use the same port, because when the server is configured it only tests
-whether the port is available but doesn't call bind()
-immediately. Thefore there is a race condition here, which needs to be
-resolved. Currently the workaround is to start the instances of the
-C<Apache::Test> framework with a slight delay between each other.
-Depending on the speed of you machine, 4-5 seconds can be a good
-choice. that's approximately the time it takes to configure and start
-the server on a quite slow machine.
+whether the port is available but doesn't call bind() immediately. This
+race condition needs to be resolved. Currently the workaround is to
+start the instances of the C<Apache::Test> framework with a slight delay
+between them. Depending on the speed of your machine, 4-5 seconds can be
+a good choice, as this is the approximate the time it takes to configure
+and start the server on a quite slow machine.
=head2 Verbose Mode
-In case something goes wrong you should run the tests in the verbose -mode: +In case something goes wrong you should run the tests in verbose mode:
% t/TEST -verbose
-In this case the test may print useful information, like what values
+In verbose mode, 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.
+to report these. In silent mode (without C<-verbose>), these printouts
+are filtered out by C<Test::Harness>. When running in I<verbose>, mode
+usually it's a good idea to run only problematic tests in order 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 +When debugging tests, it often 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.
+-clean> is run, I<t/logs/error_log> gets deleted; therefore, you'll have
+to run the tail(1) command again once the server starts.
=head2 Colored Trace Mode
If your terminal supports colored text you may want to set the -environment variable C<APACHE_TEST_COLOR> to 1 to enable the colored -tracing when running in the non-batch mode, which makes it easier to -tell the reported errors and warnings, from the rest of the +environment variable C<APACHE_TEST_COLOR> to 1 to enable any colored +tracing when running in the non-batch mode. Colored tracing mode can +make it easier to discriminate errors and warnings from other notifications.
=head2 Controlling the Apache::Test's Signal to Noise Ratio @@ -296,14 +319,14 @@
emerg alert crit error warning notice info debug
-where I<emerg> is the for the most important messages and I<debug> for -the least important ones. +where I<emerg> is the for the most important messages and I<debug> is +for the least important ones.
-Currently the default level is I<info>, therefore any messages which -fall into the I<info> category and above (I<notice>, I<warning>, etc). -This tracing level is unrelated to the Apache's C<LogLevel> mechanism, -which Apache-Test sets to C<debug> in F<t/conf/httpd.conf> and you can -override it F<t/conf/extra.conf.in>. +Currently, the default level is I<info>; therefore, any messages which +fall into the I<info> category and above (I<notice>, I<warning>, etc) +will be output. This tracing level is unrelated to Apache's C<LogLevel> +mechanism, which Apache-Test sets to C<debug> in F<t/conf/httpd.conf> +and which you can override F<t/conf/extra.conf.in>.
Let's assume you have the following code snippet:
@@ -315,11 +338,11 @@
% t/TEST -trace=warning ...
-now only the warning message +now only the warning message
careful, perl on the premises
-will be printed. If you want to see the I<debug> messages you can +will be printed. If you want to see I<debug> messages, you can change the default level using I<-trace> option:
% t/TEST -trace=debug ... @@ -330,29 +353,30 @@ to a file. Refer to the C<Apache::TestTrace> manpage for more information.
-Finally you can use methods: C<emerg()>, C<alert()>, C<crit()>,
-C<error()>, C<warning()>, C<notice()>, C<info()> and C<debug()> in
-your client and server side code. This if useful for example if you
-have some debug tracing that you don't want to be printed during the
-normal C<make test>. However if some users have a problem you can ask
-them to run the test suite with the trace level of 'debug' and voila
-they can send you the extra debug output. Moreveor all these functions
-use C<Data::Dumper> to dump arguments which are references to perl
-structures. So for example your code may look like:
+Finally, you can use the C<emerg()>, C<alert()>, C<crit()>, C<error()>,
+C<warning()>, C<notice()>, C<info()> and C<debug()> methods in your
+client and server side code. These methods are useful when, for example,
+you have some debug tracing that you don't want to be printed during the
+normal C<make test> or C<.Build test>. However, if some users have a
+problem you can ask them to run the test suite with the trace level set
+to 'debug' and, voila, they can send you the extra debug output.
+Moreveor, all of these functions use C<Data::Dumper> to dump arguments
+that are references to perl structures. So for example your code may
+look like:
use Apache::TestTrace;
...
my $data = { foo => bar };
debug "my data", $data;-and only when run with C<-trace=debug> it'll output. +and only when run with C<-trace=debug> it'll output:
my data
$VAR1 = {
'foo' => 'bar'
};-Normally it will not print anything. +Normally it will print nothing.
@@ -792,7 +816,7 @@ =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 +later we can distribute it on CPAN. We are going to develop an C<Apache::Amazing> module as an example.
% h2xs -AXn Apache::Amazing @@ -806,8 +830,8 @@ C<h2xs> is a nifty utility that gets installed together with Perl and helps us to create some of the files we will need later.
-However we are going to use a little bit different files layout,
-therefore we are going to move things around a bit.
+However, we are going to use a slightly different file layout; therefore we
+are going to move things around a bit.
We want our module to live in the I<Apache-Amazing> directory, so we do: @@ -819,7 +843,7 @@
% cd Apache-Amazing
-We don't need the I<test.pl>. as we are going to create a whole +We don't need the I<test.pl>, as we are going to create a whole testing environment:
% rm test.pl @@ -832,22 +856,22 @@ % mkdir lib/Apache % mv Amazing.pm lib/Apache
-Now we adjust the I<lib/Apache/Amazing.pm> to look like this: +Now we adjust I<lib/Apache/Amazing.pm> to look like this:
#file:lib/Apache/Amazing.pm
#--------------------------
package Apache::Amazing;
-
+
use strict;
use warnings;
-
+
use Apache::RequestRec ();
use Apache::RequestIO ();
-
+
$Apache::Amazing::VERSION = '0.01';
-
+
use Apache::Const -compile => 'OK';
-
+
sub handler {
my $r = shift;
$r->content_type('text/plain');
@@ -858,21 +882,51 @@
__END__
... pod documentation goes here...-The only thing it does is setting the I<text/plain> header and +The only thing our modules does is set the I<text/plain> header and responding with I<"Amazing!">.
-Next adjust or create the I<Makefile.PL> file:
+Next, you have a choice to make. Perl modules typically use one of two
+build systems: C<ExtUtils::MakeMaker> or C<Module::Build>.
+
+C<ExtUtils::MakeMaker> is the traditional Perl module build system, and
+comes preinstalled with Perl. It generates a tradiational F<Makefile> to
+handle the build process. The code to generate the F<Makefile> resides
+in F<Makefile.PL>.
+
+C<Module::Build> is a new build system, available from CPAN, and
+scheduled to be added to the core Perl distribution in version 5.10,
+with the goal of eventually replacing
+C<ExtUtils::MakeMaker>. C<Module::Build> uses pure Perl code to manage
+the build process, making it much easier to override its behavior to
+perform special build tasks. It is also more portable, since it relies
+on Perl itself, rather than the C<make> utility.
+
+So the decision you need to make is which system to use. Most modules on
+CPAN use C<ExtUtils::MakeMaker>, and for most simple modules it is more
+than adequate. But more and more modules are moving to C<Module::Build>
+so as to take advantage of its new features. C<Module::Build> is the
+future of Perl build systems, but C<ExtUtils::MakeMaker> is likely to be
+around for some time to come.
+
+Fortunately, C<Apache::Test> makes it easy to use either build system.
+
+=over 4
+
+=item C<ExtUtils::MakeMaker>
+
+If you decide to use C<ExtUtils::MakeMaker>, adjust or create the
+I<Makefile.PL> file to use C<Apache::TestMM>:
#file:Makefile.PL
#----------------
require 5.6.1;
-
+
use ExtUtils::MakeMaker;
-
+
use lib qw(../blib/lib lib );
-
+
use Apache::TestMM qw(test clean); #enable 'make test'
-
+
# prerequisites
my %require =
(
@@ -897,18 +951,55 @@
) : ()
),
);
-
+
sub clean_files {
return [EMAIL PROTECTED];
}-C<Apache::TestMM> will do a lot of thing for us, such as building a -complete Makefile with proper I<'test'> and I<'clean'> targets, +C<Apache::TestMM> does a lot of thing for us, such as building a +complete F<Makefile> with proper I<'test'> and I<'clean'> targets, automatically converting I<.PL> and I<conf/*.in> files and more.
-As you see we specify a prerequisites hash with I<Apache::Test> in it,
-so if the package gets distributed on CPAN, C<CPAN.pm> shell will know
-to fetch and install this required package.
+As you can see, we specify a prerequisites hash that includes
+I<Apache::Test>, so if the package gets distributed on CPAN, the
+C<CPAN.pm> and C<CPANPLUS> shells will know to fetch and install this
+required package.
+
+=item C<Module::Build>
+
+If you decide to use C<Module::Build>, the process is even simpler. Just
+delete the F<Makefile.PL> file and create F<Build.PL> instead. It should
+look somethiing like this:
+
+ use Module::Build:
+
+ my $build_pkg = eval { require Apache::TestMB }
+ ? 'Apache::TestMB' : 'Module::Build';
+
+ my $build = $build_pkg->new(
+ module_name => 'Apache::Amazing',
+ license => 'perl',
+ build_requires => { Apache::Test => '1.12' },
+ create_makefile_pl => 'passthrough',
+ );
+ $build->create_build_script;
+
+Note that the first thing this script does is check to be sure that
+C<Apache::TestMB> is installed. If it is not, and your module is
+installed with the C<CPAN.pm> or C<CPANPLUS> shells, it will be
+installed before continuing. This is because we've specified that
+C<Apache::Test> 1.12 (the first version of C<Apache::Test> to include
+C<Apache::TestMB>) is required to build the module (in this case,
+because its tests require it). We've also specified what license the
+module is distributed under, and that a passthrough F<Makefile.PL>
+should be generated. This last parameter helps those who don't have
+C<Module::Build> installed, as it allows them to use an
+C<ExtUtils::MakeMaker>-style F<Makefile.PL> script to build, test, and
+install the module (although what the passthrough script actually does
+is install C<Module::Build> from CPAN and pass build commands through to
+our C<Build.PL> script).
+
+=back
Next we create the test suite, which will reside in the I<t> directory: @@ -921,19 +1012,19 @@ #file:t/TEST.PL #-------------- #!perl - + use strict; use warnings FATAL => 'all'; - + use lib qw(lib); - + use Apache::TestRunPerl (); - + Apache::TestRunPerl->new->run(@ARGV);
-Assuming that C<Apache::Test> is already installed on your system and -Perl can find it. If not you should tell Perl where to find it. For -example you could add: +This script assumes that C<Apache::Test> is already installed on your +system and that Perl can find it. If not, you should tell Perl where to +find it. For example you could add:
use lib qw(Apache-Test/lib);
@@ -944,21 +1035,27 @@ but C<#!perl>. When I<t/TEST> is created the correct path will be placed there automatically.
+B<Note:> If you use C<Apache::TestMB> in a F<Build.PL> script, the
+creation of the F<t/TEST.PL> script is optional. You only need to create
+it if you need it to do something special that the above example does
+not.
+
Next we need to prepare extra Apache configuration bits, which will
reside in I<t/conf>:
% mkdir t/conf
-We create the I<t/conf/extra.conf.in> file which will be automatically
+We create the I<t/conf/extra.conf.in> file, which will be automatically
converted into I<t/conf/extra.conf> before the server starts. If the
-file has any placeholders like C<@documentroot@>, these will be
-replaced with the real values specific for the used server. In our
-case we put the following configuration bits into this file:
+file has any placeholders like C<@documentroot@>, these will be replaced
+with the real values specific for the Apache server used for the
+tests. In our case, we put the following configuration bits into this
+file:
#file:t/conf/extra.conf.in
#-------------------------
# this file will be Include-d by @ServerRoot@/httpd.conf
-
+
# where Apache::Amazing can be found
PerlSwitches [EMAIL PROTECTED]@/../lib
# preload the module
@@ -968,9 +1065,10 @@
PerlResponseHandler Apache::Amazing
</Location>-As you can see we just add a simple E<lt>LocationE<gt> container and +As you can see, we just add a simple E<lt>LocationE<gt> container and tell Apache that the namespace I</test/amazing> should be handled by -C<Apache::Amazing> module running as a mod_perl handler. Notice that: +the C<Apache::Amazing> module running as a mod_perl handler. Notice +that:
SetHandler modperl
@@ -987,19 +1085,19 @@
#-----------
use strict;
use warnings FATAL => 'all';
-
+
use Apache::Amazing;
use Apache::Test;
use Apache::TestUtil;
use Apache::TestRequest 'GET_BODY';
-
+
plan tests => 2;
-
+
ok 1; # simple load test
-
+
my $url = '/test/amazing';
my $data = GET_BODY $url;
-
+
ok t_cmp(
"Amazing!",
$data,
@@ -1024,11 +1122,21 @@
#...
);-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. +Or for C<Module::Build> to generate the F<README> with:
-and finally we adjust or create the I<MANIFEST> file, so we can + #file:Build.PL + #------------- + my $build = $build_pkg->new( + #... + create_readme => 1, + #... + ); + +In these cases, I<README> will be created from the documenation POD +sections in I<lib/Apache/Amazing.pm>, but the file must exist for +I<make dist> or C<./Build.PL dist> to succeed. + +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 I<MANIFEST> file itself:
@@ -1038,14 +1146,19 @@ t/TEST.PL t/basic.t t/conf/extra.conf.in - Makefile.PL + Makefile.PL # and/or Build.PL Changes README MANIFEST
+You can automate the creation or updating of the F<MANIFEST> file using +C<make manifest> with F<Makefile.PL> or C<./Build manifest> with +F<Build.PL>. + That's it. Now we can build the package. But we need to know the location of the C<apxs> utility from the installed httpd server. We -pass its path as an option to I<Makefile.PL>: +pass its path as an option to I<Makefile.PL> or F<Build.PL>. To build, +test, and install the module with F<Makefile.PL>, do this:
% perl Makefile.PL -apxs ~/httpd/prefork/bin/apxs % make @@ -1063,16 +1176,28 @@
% make dist
-will create the package which can be immediately uploaded to CPAN. In
-this example the generated source package with all the required files
-will be called: I<Apache-Amazing-0.01.tar.gz>.
+This build command will create the package which can be immediately
+uploaded to CPAN. In this example, the generated source package with all
+the required files will be called: I<Apache-Amazing-0.01.tar.gz>.
+
+The same process can be accomplished with F<Buiild.PL> like so:
+
+ # perl Build.PL -apxs ~/httpd/prefork/bin/apxs
+ % ./Build
+ % ./Build test
+
+ basic...........ok
+ All tests successful.
+ Files=1, Tests=2, 1 wallclock secs ( 0.52 cusr + 0.02 csys = 0.54 CPU)
+
+ % ./Build install
+ % ./Build dist
The only thing that we haven't done and hope that you will do is to write the POD sections for the C<Apache::Amazing> module, explaining 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 @@ -1176,6 +1301,10 @@
% perl Makefile.PL -httpd_conf /path/to/httpd.conf
+or with F<Build.PL>: + + % perl Build.PL -httpd_conf /path/to/httpd.conf + or during the configuration:
% t/TEST -conf -httpd_conf /path/to/httpd.conf @@ -1300,8 +1429,9 @@
The configuration part for this test will be autogenerated by the
C<Apache::Test> framework and added to the autogenerated file
-I<t/conf/httpd.conf> when C<make test> or C<t/TEST -configure> is
-run. In our case the following configuration section will be added:
+I<t/conf/httpd.conf> when C<make test> or C<./Build test> or C<t/TEST
+-configure> is run. In our case the following configuration section will
+be added:
<Location /TestApache__write>
SetHandler modperl
@@ -3058,22 +3188,22 @@
choice but to restart the server before you want to test the modified
code.-First of all, your perl modules need to reside under the I<lib>
+First of all, your Perl modules need to reside under the I<lib>
directory, the same way they reside in I<blib/lib>. In the section
-L<Basic Testing
-Environment|/Basic_Testing_Environment> we've already arranged for that.
-If I<Amazing.pm> resides in the top-level directory, it's not possible
-to perform C<'require Apache::Amazing'>. Only after running C<make>,
-the file will be moved to I<blib/lib/Apache/Amazing.pm>, which is when
-we can load it. But you don't want to run C<make> every time you
-change the file. It's both annoying and error-prone, since at times
-you'd do some change, try to verify it and it will appear to be wrong,
-and you will try to understand why, whereas in reality you just forgot
-to run C<make> and the server was testing against the old unmodified
-version in C<blib/lib>. Of you course if you always run C<make test>
-it'll always do the right thing, but it's not the most effecient way
-to undertake when you want to test a specific test and you do it every
-few seconds.
+L<Basic Testing Environment|/Basic_Testing_Environment>, we've already
+arranged for that. If I<Amazing.pm> resides in the top-level directory,
+it's not possible to perform C<'require Apache::Amazing'>. Only after
+running C<make> or C<./Build> wil the file be moved to
+I<blib/lib/Apache/Amazing.pm>, which is when we can load it. But you
+don't want to run C<make> or C<./Build> every time you change the
+file. It's both annoying and error-prone, since at times you'd make a
+change, try to verify it, and it will appear to be wrong for no obvious
+reason. What will really have happend is that you just forgot to run
+C<make> or C<./Build> and the server was testing against the old
+unmodified version in C<blib/lib>. Of course, if you always run C<make
+test> or C<./Build test>, it'll always do the right thing, but it's not
+the most effecient approach to undertake when you want to test a
+specific test and you do it every few seconds.
The following scenario will make you a much happier Perl developer.
@@ -3090,8 +3220,8 @@ I<t/conf/modperl_inc.pl>. This technique is convenient since you don't need to modify your code to include that directory.
-Second, we need to configure mod_perl to use C<Apache::Reload> to -automatically reload the module when it's changed, by adding following +Second, we need to configure mod_perl to use C<Apache::Reload>--to +automatically reload the module when it's changed--by adding following configuration directives to I<t/conf/extra.conf.in>:
PerlModule Apache::Reload @@ -3099,7 +3229,7 @@ PerlSetVar ReloadAll Off PerlSetVar ReloadModules "Apache::Amazing"
-(For more information about C<Apache::Reload>, depending on the used +(For more information about C<Apache::Reload>, depending on the mod_perl generation, refer to L<the mod_perl 1.0 documentation|docs::1.0::guide::porting/Using_Apache__Reload> or L<the C<Apache::Reload> manpage for mod_perl
smime.p7s
Description: S/MIME cryptographic signature
