1[IMPORTANT NOTICE] 2------------------ 3This is an addendum to README.TESTING with additional information 4specific to server-tests.php. 5 6server-tests.php is backward compatible with tests developed for 7the original run-tests.php script. server-tests is *not* used by 8'make test'. server-tests was developed to provide support for 9testing PHP under it's primary environment, HTTP, and can run the 10PHP tests under any of the SAPI modules that are direct executables, 11or are accessable via HTTP. 12 13[New features] 14---------------- 15* Command line interface: 16 You can run 'php server-tests.php -h' to get all the possible options. 17* Configuration file: 18 the -c argument will allow you to use a configuration file. This is 19 handy if you are testing multiple environments and need various options 20 depending on the environment. 21 see server-tests-config.php for details. 22* CGI Emulation: 23 Will emulate a CGI environment when testing with the cgi sapi executable. 24* HTTP testing: 25 can be configured to run test scripts through an HTTP server running 26 on localhost. localhost is required since either the web server must 27 alias a directory to the php source directory, or the test scripts 28 must be copied to a directory under the web server 29 (see config options TEST_WEB_BASE_URL, TEST_BASE_PATH, and TEST_WEB_EXT) 30* New sections supported for test files (see below) 31 32When running tests over http, tests that require ini settings different that what 33the web server runs under will be skipped. Since the test harness defines a number 34of ini settings by default, the web server may require special configuration to 35make testing work. 36 37[Example Usage] 38---------------- 39Some (but not all!) examples of usage: 40 411. run tests from the php source directory 42 php server-tests.php -p /path/to/php-cli 43 442. run tests using cgi emulation 45 php server-tests.php -p /path/to/php-cgi 46 473. run tests over http, copying test files into document root 48 php server-tests.php -w -u http://localhost/test -m /path/to/htdocs/test 49 504. run tests over http, php sources have been aliased in web server 51 php server-tests.php -w -u http://localhost/test 52 535. run tests using configuration file 54 php server-tests.php -c /path/to/server-tests-config.php 55 566. run tests using configuration file, but overriding some settings: 57 (config file must be first) 58 php server-tests.php -c /path/to/server-tests-config.php -w -t 3 -d /path/to/testdir 59 60NOTE: configuration as described in README.TESTING still works. 61 62[New Test Sections] 63---------------- 64In addition to the traditional test sections 65(see http://qa.php.net/write-test.php), several new sections are available 66under server-tests. 67 68--POST-- 69This is not a new section, but not multipart posts are supported for testing 70file uploads, or other types of POST data. 71 72--CGI-- 73This section takes no value. It merely provides a simple marker for tests 74that MUST be run as CGI, even if there is no --POST-- or --GET-- sections 75in the test file. 76 77--DESCRIPTION-- 78Not used for anything, just a section for documenting the test 79 80--ENV-- 81This section get's eval()'d to help build an environment for the 82execution of the test. This can be used to change environment 83vars that are used for CGI emulation, or simply to set env vars 84for cli testing. A full example looks like: 85 86 --ENV-- 87 return <<<END 88 PATH_TRANSLATED=$filename 89 PATH_INFO=$scriptname 90 SCRIPT_NAME=$scriptname 91 END; 92 93Some variables are made easily available for use in this section, they 94include: 95 $filename full native path to file, will become PATH_TRANSLATED 96 $filepath =dirname($filename) 97 $scriptname this is what will become SCRIPT_NAME unless you override it 98 $docroot the equivelant of DOCUMENT_ROOT under Apache 99 $cwd the directory that the test is being initiated from 100 $this->conf all server-tests configuration vars 101 $this->env all environment variables that will get passed to the test 102 103 104--REQUEST-- 105This section is also eval'd, and is similar in nature to --ENV--. However, 106this section is used to build the url used in an HTTP request. Valid values 107to set in this section would include: 108 SCRIPT_NAME The inital part of the request url 109 PATH_INFO The pathinfo part of a request url 110 FRAGMENT The fragment section of a url (after #) 111 QUERY_STRING The query part of a url (after ?) 112 113 --REQUEST-- 114 return <<<END 115 PATH_INFO=/path/info 116 END; 117 118--HEADERS-- 119This section is also eval'd. It is used to provide additional headers sent 120in an HTTP request, such as content type for multipart posts, cookies, etc. 121 122 --HEADERS-- 123 return <<<END 124 Content-Type=multipart/form-data; boundary=---------------------------240723202011929 125 Content-Length=100 126 END; 127 128--EXPECTHEADERS-- 129This section can be used to define what headers are required to be 130received back from a request, and is checked in addition to the 131regular expect sections. For example: 132 133 --EXPECTHEADERS-- 134 Status: 404 135 136 137 138
