release/src/router/php/README.TESTING2

   1 [IMPORTANT NOTICE]
   2 ------------------
   3 This is an addendum to README.TESTING with additional information
   4 specific to server-tests.php.
   5
   6 server-tests.php is backward compatible with tests developed for
   7 the original run-tests.php script.  server-tests is *not* used by
   8 'make test'.  server-tests was developed to provide support for
   9 testing PHP under it's primary environment, HTTP, and can run the
  10 PHP tests under any of the SAPI modules that are direct executables,
  11 or 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
  32 When running tests over http, tests that require ini settings different that what
  33 the web server runs under will be skipped.  Since the test harness defines a number
  34 of ini settings by default, the web server may require special configuration to
  35 make testing work.
  36
  37 [Example Usage]
  38 ----------------
  39 Some (but not all!) examples of usage:
  40
  41 1. run tests from the php source directory
  42     php server-tests.php -p /path/to/php-cli
  43
  44 2. run tests using cgi emulation
  45     php server-tests.php -p /path/to/php-cgi
  46
  47 3. 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
  50 4. run tests over http, php sources have been aliased in web server
  51     php server-tests.php -w -u http://localhost/test
  52
  53 5. run tests using configuration file
  54     php server-tests.php -c /path/to/server-tests-config.php
  55
  56 6. 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
  60 NOTE: configuration as described in README.TESTING still works.
  61
  62 [New Test Sections]
  63 ----------------
  64 In addition to the traditional test sections
  65 (see http://qa.php.net/write-test.php), several new sections are available
  66 under server-tests.
  67
  68 --POST--
  69 This is not a new section, but not multipart posts are supported for testing
  70 file uploads, or other types of POST data.
  71
  72 --CGI--
  73 This section takes no value.  It merely provides a simple marker for tests
  74 that MUST be run as CGI, even if there is no --POST-- or --GET-- sections
  75 in the test file.
  76
  77 --DESCRIPTION--
  78 Not used for anything, just a section for documenting the test
  79
  80 --ENV--
  81 This section get's eval()'d to help build an environment for the
  82 execution of the test.  This can be used to change environment
  83 vars that are used for CGI emulation, or simply to set env vars
  84 for 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
  93 Some variables are made easily available for use in this section, they
  94 include:
  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--
 105 This section is also eval'd, and is similar in nature to --ENV--.  However,
 106 this section is used to build the url used in an HTTP request.  Valid values
 107 to 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--
 119 This section is also eval'd.  It is used to provide additional headers sent
 120 in 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--
 129 This section can be used to define what headers are required to be
 130 received back from a request, and is checked in addition to the
 131 regular expect sections.  For example:
 132
 133   --EXPECTHEADERS--
 134   Status: 404
 135
 136
 137