============================= GETTING STARTED WITH THE DEMO ============================= NOTE: This demo requires that you already have Apache with mod_php (as a static module or shared library) and Apache-Test installed. Instructions for installing these prerequisites are provided in the INSTALL document. ================ RUNNING THE DEMO ================ To simply run the tests, first unpack the tarball. $ tar -xzvf perl-php-test.tar.gz $ cd perl-php-test Next point the tests to a suitable Apache + mod_php installation. If you are using a statically compiled mod_php, try $ perl Makefile.PL -httpd /usr/local/apache/bin/httpd If you are using a dynamically compiled mod_php, or you know that your httpd binary has mod_so enabled, you can try this instead $ perl Makefile.PL -apxs /usr/local/apache/bin/apxs If you forget either of these steps, simply answer the interactive dialogue that you will be presented with and everything should run smoothly. At this point, you are ready to run the tests. $ make test You should be met with a dialogue that looks something like this: /perl/perl-5.8.5/bin/perl -Iblib/arch -Iblib/lib \ t/TEST -clean APACHE_TEST_GROUP= APACHE_TEST_HTTPD= APACHE_TEST_PORT= APACHE_TEST_USER= APACHE_TEST_APXS= \ /perl/perl-5.8.5/bin/perl -Iblib/arch -Iblib/lib \ t/TEST -bugreport -verbose=0 /usr/local/apache/bin/httpd -d /src/test/perl-php-test/t -f /src/test/perl-php-test/t/conf/httpd.conf -D APACHE1 -D PERL_USEITHREADS using Apache/1.3.32 waiting 60 seconds for server to start: .. waiting 60 seconds for server to start: ok (waited 1 secs) server localhost.localdomain:8529 started t/01login.........................ok t/02logout........................ok t/03admin.........................ok t/functions/01add_user............ok t/functions/02delete_user.........FAILED test 4 Failed 1/4 tests, 75.00% okay t/functions/03check_login.........ok t/functions/04encrypt_password....ok t/functions/05check_admin.........ok Failed Test Stat Wstat Total Fail Failed List of Failed ------------------------------------------------------------------------------- t/functions/02delete_user.t 4 1 25.00% 4 Failed 1/8 test scripts, 87.50% okay. 1/36 subtests failed, 97.22% okay. [warning] server localhost.localdomain:8529 shutdown [ error] error running tests (please examine t/logs/error_log) make: *** [run_tests] Error 1 There are a few things you might want to make note of here, particularly these bits (which are explained later in this document); o /perl/perl-5.8.5/bin/perl - the full path to the perl used when 'perl Makefile.PL' was invoked o t/TEST -clean - each 'make test' run does a full cleanup and reconfiguration o t/TEST -bugreport -verbose - t/TEST is the actual script that executes the test files. it accepts many options, some of which are shown o /usr/local/apache/bin/httpd - the path to my httpd binary, as determined via -apxs or -httpd options to 'perl Makefile.PL', or via the interactive configuration, or via the APACHE_TEST_APXS or APACHE_TEST_HTTPD environment variables shown above it o -d ../perl-php-test/t - the ServerRoot o -f ../t/conf/httpd.conf - the configuration file, which has been autogenerated for you, and which includes the contents of t/conf/extra.conf.in o -D APACHE1 - signifies that the apache running is Apache 1.3.XX and that you can separate out 1.3 or 2.0 directives using in your extra.conf.in if required o localhost.localdomain:8529 - the server is running on port 8529 on localhost ============== ADDITIONAL FUN ============== Additionally, you can run each test individually by specifying the name of the test in the TEST_FILES environment variable $ make test TEST_FILES=t/functions/02delete_user.t To run the tests in verbose mode, use the TEST_VERBOSE variable, such as $ make test TEST_VERBOSE=1 or even $ make test TEST_VERBOSE=1 TEST_FILES=t/functions/02delete_user.t Issuing the latter should yield a more detailed dialogue similar to t/functions/02delete_user....1..4 ok 1 - no user fails ok 2 - cannot delete non-existent user ok 3 - added user to delete not ok 4 - deleted user successfully # Failed test (t/response/TestFunctions/02delete_user.php at line 25) # Looks like you failed 1 tests of 4. Once you run 'make test' once you will probably find it more comfortable to use the TEST script in the t/ directory to navigate your tests. Here are some examples. To run a single test, such as the above TEST_FILES example, try $ t/TEST t/functions/02delete_user.t For verbose mode simply add the -v flag $ t/TEST t/functions/02delete_user.t -v Note that order is not important - this works as well $ t/TEST -v t/functions/02delete_user.t You can even start the Apache server and leave it running $ t/TEST -start then hit against the server from a browser. Note the port number in the above dialogue - "server localhost.localdomain:8529 started" - indicating that you would want to hit http://localhost:8529/. For a full list of options you can pass to t/TEST, just ask for help $ t/TEST -help Finally, if things get bargled up (which they do from time to time) you may want to purge all of Apache-Test's saved settings via $ t/TEST -clean and then reconfigure via $ t/TEST -conf If that doesn't work, just nuke everything like this $ make realclean $ rm -rf ~/.apache-test and start again. ================ THE GORY DETAILS ================ t/conf/extra.conf.in is your configuration file, and it holds Apache configuration directives the same way an httpd.conf would. The demo application lives in t/htdocs. Apache-Test has created a pristine, self-contained environment for you, including overriding your php.ini settings with those in t/conf/php.ini. The t/ directory contains the actual test scripts, some of which we wrote and some of which are autogenerated by Apache-Test. The following scripts t/01login.t t/02logout.t t/03admin.t are scripts which act as a client (browser) and test behavior on that level. The following scripts t/functions/01add_user.t t/functions/02delete_user.t t/functions/03check_login.t t/functions/04encrypt_password.t t/functions/05check_admin.t were automatically generated by Apache-Test. The trigger for the autogeneration of these scripts is the presence of the following files t/response/TestFunctions/01add_user.php t/response/TestFunctions/02delete_user.php t/response/TestFunctions/03check_login.php t/response/TestFunctions/04encrypt_password.php t/response/TestFunctions/05check_admin.php each of which contains server-side tests, sending test output directly to the test harness. These PHP scripts, and the test scripts that are subsequently autogenerated, are the heart of what makes Apache-Test a good (perhaps the best) environment for testing PHP, so you will want to take a look at these scripts in detail. The included script test-more.php is (also) autogenerated, and can be found in t/conf/test-more.php. The script t/functions/all.t is also autogenerated, and tells Apache-Test to skip all tests in t/functions unless mod_php is available. ================= FURTHER EDUCATION ================= More information on Apache-Test in general can be found here http://www.perl.com/pub/a/2003/05/22/testing.html http://perl.apache.org/docs/general/testing/testing.html Unfortunately, details on the PHP specific hooks are rather sparse at the moment. For starters you can see the Apache::TestRunPHP manpage $ man Apache::TestRunPHP or the slides from our ApacheCon2004 talk http://www.modperlcookbook.org/~geoff/slides/ApacheCon/2004/testing-php-with-perl.pdf ======= CREDITS ======= You have Chris Shiflett and Geoff Young to thank for this tarball and the ApacheCon2004 presentation, and for initiating this project in general. Chris wrote and maintains the test-more.php library. Geoff wrote and maintains the PHP magic within Apache-Test. Apache-Test proper is part of the httpd-test project at the Apache Software Foundation and is a community effort. However, it was written and is currently maintained primarily by the mod_perl core development team. So, in the end, all this goodness is brought to you by mod_perl. You're welcome :)