The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

 wt - test one or more web pages, either remotely or locally 

SYNOPSIS

 wt [ -v ] param_file ... 

DESCRIPTION

 This program tests local web source files using a local instance
 of Apache and/or tests remote URLs.  It reads the input test
 specification from one or more parameter files, starts Apache (if
 one of the tests is for a local file), runs the tests and shuts 
 down the local instance of Apache.

OPTIONS, OPERANDS

 -v - Print version number of HTTP:WebTest module and exit.
 param_file - Text file containing test specification parameters.
    Type "perldoc HTTP::WebTest" to view a description of the
    file format.  Multiple parameter files can be specified on the
    command line.

EXAMPLES

 To test using all files ending in .wt in current directory:
 wt *.wt

 To show the version number of the HTTP::WebTest module:
 wt -v

EXIT STATUS

 0 -> All tests ran successfully.
 1 -> One or more tests failed, there was an error in the input 
      parameter file, or there was a system runtime error.

ENVIRONMENT VARIABLES

 WEBTEST_LIB - If defined, this directory is added to the @INC array 
    that is used to search for modules.

FILES

 The web_test() method requires (1) one or more input parameter
 files, and (2) if the file_path parameter is specified, a directory
 tree that contains the subdirectories and files described in the
 APACHE DIRECTORY AND FILES section below.
 

 PARAMETER FILE
 
 The input parameters are specified in a text file. You must pass
 the name of the file as an argument to the web_test() method.
 If you are running dozens of tests, you may want to divide them
 into several parameter files.  This will organize the tests
 and reduce the size of the output and e-mail messages.  However,
 cookies passed to or received from the web server(s) are not shared
 between tests in different parameter files.

 Parameters - Overview
 =====================
 There are over 30 parameters, but the only required parameters
 are test_name, end_test, and either url or file_path.  Also, if
 you specify the file_path parameter, you will have to specify the
 apache_exec parameter.

 Each parameter is either a test block parameter, a global parameter,
 or both.  TEST BLOCK PARAMETERS are parameters specified between
 a test_name parameter and an end_test directive.  Test block
 parameters apply only to the tests for the file_path or url
 specified in that test block.  You can specify one or many test
 blocks in a parameter file.  GLOBAL PARAMETERS are parameters
 specified outside of a test block.  Global parameters apply to
 every test block in the parameter file.

 You can specify certain parameters as BOTH GLOBAL PARAMETERS AND
 TEST BLOCK PARAMETERS.  These include the parameters accept_cookies,
 auth, ignore_case, ignore_error_log, regex_forbid, regex_require,
 send_cookies, text_forbid and text_require.  If you specify one of
 these within a test block, that value is used instead of the value
 of the corresponding global parameter for that test block only.
 If you specify some, but not all, of these parameters in a test
 block, the global parameter values are used for the unspecified
 test block parameters.

 Parameters - Short descriptions
 ===============================
 Parameters that are always required are marked with an asterisk.  
 Parameters that are usually required are marked with a plus sign.

  accept_cookies: Option to accept cookies sent by web server.
  apache_dir: Name of directory containing Apache files.
 +apache_exec: Path name of Apache executable.
  apache_loglevel: Apache logging level. 
  apache_max_wait: Maximum seconds to wait for Apache to start.
  apache_options: Additional Apache command line options.
  auth: Two-element list containing userid and password to be passed
     to web server for page access authorization.
  cookie: List specifying a cookie to send to the web server.
  debug: Option to output verbose diagnostic messages.
 *end_test: Signifies the end of a test block.
 +file_path: Two-element list containing name of web file to test and
     subdirectory path relative to the htdocs directory to copy it to.
  ignore_case: Option to do case-insensitive matching with text_forbid
     and text_require parameters.
  ignore_error_log: Option to ignore errors found in Apache error log.
  include_file_path: List containing files to copy and subdirectory 
     path relative to the Apache ServerRoot directory to copy them to.
  mail: Option to send e-mail containing results of tests.
  mail_addresses: List of e-mail addresses to send reports to.
  mail_server: Name of mail server.
  method: HTTP request method; either get or post.
  max_bytes: Maximum number of bytes expected in returned page.
  min_bytes: Minimum number of bytes expected in returned page.
  params: List of parameter name/value pairs to be passed to server.
  proxies: List of service name / proxy URL pairs to use for requests.
  regex_forbid: List of strings/regexs that must NOT occur in page.
  regex_require: List of strings/regexs that MUST occur in page.
  save_output: Option to redirect the program output to a file.
  send_cookies: Option to send cookies to the web server.
  show_cookies: Option to list cookies sent or received.
  show_html: Option to display the HTML source with the output.
 *test_name: Name of test.
  text_forbid: List of strings that must NOT occur in page.
  text_require: List of strings that MUST occur in page.
 +url: URL to test.
  terse: Option to display shorter test report.

 Parameter file format
 =====================
 The program ignores:
    * lines consisting of nothing but white space (blanks or tabs)
    * lines beginning with a number sign ("#")
    * lines beginning with white space (blanks or tabs) followed by
      a number sign

 The order of the parameters in the parameter file is arbitrary, 
 with the following exceptions:
    * Test block parameters MUST occur between a test_name parameter
      and an end_test directive.
    * Global parameters must NOT occur between a test_name parameter
      and an end_test directive.  (This requirement does not apply to
      parameters that are both global and test block parameters.)
    * The parameter save_output, if specified, should be the first
      parameter in the file.  (This is not required.)

 Parameters are either scalar (single-valued) or lists (single or 
 multi-valued).  

 You can specify scalar parameters using forms such as: 
 name = value 
 name =
        value
 name = 'value' 

 You can specify list parameters using forms such as:
 name = ( first value  
          second value )
 name = ( first value => second value
          third value => fourth value
        )
 name = ( first value => second value )
 name = ( 
          'first value'
          'second value' )
 name = ( 
          first value
          second value 
          third value => 'fourth value'
        )
 name = 
    ( first value
      'second value' )
 name = ( 
          'first value'
          'second value' 
        )
 (The equals sign must be followed by a space, tab or newline; all 
 other spaces are optional.)

 PARAMETER VALUES BEGINNING AND ENDING WITH A SINGLE QUOTE WILL HAVE
 THE SINGLE QUOTES REMOVED.  For example, 'foobar' is parsed as a
 value of foobar and ''foobar'' is parsed as a value of 'foobar'.  
 To specify a null (placeholder) value, use ''.

 You MUST enclose the parameter value in single quotes if you want 
 to specify:
    * A value beginning with a left parenthesis
    * A value ending with a right parenthesis
    * A value beginning with leading white space (blanks or tabs)
    * A value ending with trailing white space (blanks or tabs)
    * A value beginning and ending with single quotes

 Examples of parameter files
 ===========================
 The parameters below specify tests of a local file and a remote
 URL.  The tests specified by the text_forbid parameter apply to 
 both the "RayCosoft home page" and the "Yahoo home page" tests.  
 Hence, if either returned page contains one of the case-
 insensitive strings in text_forbid, the test fails.  If any test 
 fails, an e-mail will be sent to tester@unixscripts.com.

 apache_exec = /usr/sbin/apache 
 ignore_case = yes
 mail = errors
 mail_addresses = ( tester@unixscripts.com )
 mail_server = mailhost.unixscripts.com
 text_forbid = ( Premature end of script headers
                 an error occurred while processing this directive
               )
 
 test_name = 'RayCosoft home page (static)' 
    file_path = ( raycosoft_home.html => . )
    text_require = (     
       <a href="/dept/peopledev/new_employee/"><font color="#0033cc">
       <a href="https://www.raycosoft.com/"><font color=
                   )
 end_test
 
 test_name = Yahoo home page
    url = www.yahoo.com
    text_require = ( <a href=r/qt>Quotations</a>...<br> )
    min_bytes = 13000
    max_bytes = 19000
 end_test

 The parameters below specify a test of a local file containing Perl
 code using the Apache::ASP module.  The includes.htm file requires
 five include files and two Perl modules, which are copied using
 the include_file_path parameter.

 apache_exec = /usr/sbin/apache
 ignore_case = yes
 include_file_path = ( footer.inc => htdocs/apps/myapp/inc 
                       header.inc => htdocs/apps/myapp/inc 
                       head.inc   => htdocs/apps/myapp/inc 
                       go.script  => htdocs/shared/includes
                       go.include => htdocs/shared/includes
                       ../utils/DBconn.pm  => lib/perl/utils
                       ../utils/Window.pm  => lib/perl/utils
                     )

 test_name = includes.htm
     file_path = ( includes.htm => apps/myapp )
     min_bytes = 33000
     max_bytes = 35000
     text_require = ( input type=hidden name=control value= )
     text_forbid  = ( Premature end of script headers
                      an error occurred while processing this directive
                    )
 end_test
 
 Parameters - Detailed descriptions
 ==================================
 PARAMETER: accept_cookies TYPE: global and/or test block parameter  
 DEFAULT: yes  ALLOWED VALUES: no yes  OPTIONAL PARAMETER.
 DESCRIPTION: Option to accept and save cookies sent by the web
 server.  These cookies exist only while the program is executing
 and do not affect subsequent runs.  These cookies do not affect your
 browser or any software other than the test program.  These cookies
 are only accessible to other tests in the same parameter file.

 You can specify this parameter globally or within a test block.
 If you specify it as both a global and a test block parameter, the
 value in the test block applies only to that test block.  See also
 the send_cookies parameter.

 PARAMETER: apache_dir  TYPE: global parameter
 DEFAULT: /usr/local/etc/http-webtest  
 DESCRIPTION: Absolute or relative path name of directory containing
 Apache files.  See the APACHE DIRECTORY AND FILES section below.
 This parameter is ignored unless the file_path parameter is specified.

 PARAMETER: apache_exec  TYPE: global parameter  
 NO DEFAULT.  REQUIRED if the file_path parameter is specified.
 DESCRIPTION: Path name of Apache executable.  This command must be
 in your $PATH or the path name must start with '/'.  This parameter
 is ignored unless the file_path parameter is specified.

 PARAMETER: apache_loglevel  TYPE: global parameter  
 DEFAULT: warn  OPTIONAL PARAMETER.
 ALLOWED VALUES: debug info notice warn error crit alert emerg 
 DESCRIPTION: Apache logging level.  If you use a level less than
 warn (i.e., debug, info, or notice), the program may generate
 irrelevant errors.  This parameter is ignored unless the file_path
 parameter is specified.  See also the ignore_error_log parameter.

 PARAMETER: apache_max_wait  TYPE: global parameter
 DEFAULT: 64  ALLOWED VALUES: Any integer > 9 and < 601  OPTIONAL 
 PARAMETER.
 DESCRIPTION: Maximum number of seconds to wait for Apache to start.
 The program starts Apache, waits 4 seconds and fetches a test page.
 If this fails, it doubles the wait interval, restarts Apache,
 waits and fetches a test page.  This process repeats until the
 test page is fetched successfully or the wait interval becomes
 greater than apache_max_wait.  This parameter is ignored unless
 the file_path parameter is specified.

 PARAMETER: apache_options  TYPE: global parameter 
 DEFAULT: -X  ALLOWED VALUES: See Apache man page.  OPTIONAL PARAMETER.
 DESCRIPTION: Additional Apache command line options.  Many of the
 options cause Apache to exit immediately after starting, so the
 web page tests will not run.  This parameter is ignored unless
 the file_path parameter is specified.

 PARAMETER: auth  TYPE: global and/or test block parameter
 No default.  ALLOWED VALUES: A one or two element list.  OPTIONAL
 PARAMETER.
 DESCRIPTION: Userid and password, in that order, to be passed to the
 web server if needed for authorization.  If you specify only one
 element, it is used as the userid and the program will prompt you
 interactively for the password.  If you specify values of 'prompt'
 and 'userid_password' in that order, the program will prompt you for
 both the userid and password.  If you specify values of 'prompt'
 and 'password' in that order, the program will prompt you for
 the password and use the userid of the user running the program.
 (This last option is probably not what you want, unless your Unix
 userid and web page userid are the same.)

 You can specify this parameter globally or within a test block.
 If you specify it as both a global and a test block parameter,
 the value in the test block applies only to that test block.

 PARAMETER: cookie  TYPE: test block parameter  
 NO DEFAULT.  ALLOWED VALUES: A list with an even number of elements
 and at least 10 elements.  The cookie parameter is ignored if the
 send_cookies parameter is set to no.  OPTIONAL PARAMETER.  Multiple
 cookie parameters may be specified.
 DESCRIPTION: List that specifies a cookie to send to the web server.
 See RFC 2965 for details (ftp.isi.edu/in-notes/rfc2965.txt).
 You may specify multiple cookies within each test block by
 specifying multiple instances of the cookie parameter.  The cookie
 parameter has the form:

 ( version 
   name 
   value 
   path 
   domain 
   port 
   path_spec 
   secure 
   maxage 
   discard 
   name1
   value1
   name2
   value2
   ...
 )

 Any element not marked below as REQUIRED may be defaulted by 
 specifying a null value of ''  

 version: Version number of cookie spec to use, usually 0. (REQUIRED)
 name: Name of cookie. (REQUIRED)  Cannot begin with a $ character.
 value: Value of cookie. (REQUIRED)
 path: URL path name for which this cookie applies. (REQUIRED)  Must 
    begin with a / character.  See also path_spec. 
 domain: Domain for which cookie is valid. (REQUIRED)  Should begin 
    with a period.  Must either contain two periods or be equal
    to .local
 port: List of allowed port numbers that the cookie may be returned 
    to.  If not specified, cookie can be returned to any port.  
    Must be specified using the format N or N,N ..., where N is one 
    or more digits. 
 path_spec: Ignored if version is less than 1.  Option to ignore the
    value of path.  Default value is 0.
    = 1 -> Use the value of path.
    = 0 -> Ignore the specified value of path.
 secure: Option to require secure protocols for cookie transmission.
    Default value is 0.
    = 1 -> Use only secure protocols to transmit this cookie. 
    = 0 -> Secure protocols are not required for transmission.
 maxage: Number of seconds until cookie expires.
 discard: Option to discard cookie when the program finishes.  
    Default 0.  (The cookie will be discarded regardless of the value
    of this element.)
    = 1 -> Discard cookie when the program finishes.
    = 0 -> Don't discard cookie.
 name/value: Zero, one or several name/value pairs may be specified.
    The name parameters are words such as Comment or 
    CommentURL and the value parameters are strings that 
    may contain embedded blanks. 

 See RFC 2965 for details (ftp.isi.edu/in-notes/rfc2965.txt).

 An example cookie would look like:
 ( 0 
   WebTest cookie #1 
   expires&2592000&type&consumer 
   /
   .unixscripts.com  
   ''
   0 
   0 
   200 
   1 
 )
 
 PARAMETER: debug  TYPE: global parameter
 DEFAULT: no  ALLOWED VALUES: no yes preserve  OPTIONAL PARAMETER.
 DESCRIPTION: This parameter is primarily for use by programmers
 modifying and testing the program code.  The "yes" value makes
 the program display verbose diagnostic messages.  (If you want
 diagnostics on the parameter processing, this parameter should
 preceed all other parameters.)  The "preserve" value makes the
 program display verbose diagnostic messages and prevents the
 program from deleting the temporary Apache directory, which is 
 named "/tmp/webtest_x_y", where x and y are arbitrary positive
 integers. 

 DIRECTIVE: end_test  TYPE: test block directive
 NO VALUE (i.e. specify end_test with no equals sign or value).
 There MUST be one end_test directive for each test_name parameter.
 Directive is REQUIRED.
 DESCRIPTION: Signifies the end of a test block.

 PARAMETER: file_path  TYPE: test block parameter 
 NO DEFAULT.  ALLOWED VALUES: Second list element cannot begin with
 '../' or contain '/../'.  You MUST specify file_path or url, but
 not both, in each test block.
 DESCRIPTION: Two-element list.  First element is the file to test,
 either an absolute or a relative pathname.  Second element is the
 subdirectory pathname, relative to the Apache htdocs directory, to
 copy the file to.  The copied file will have the same basename as
 the first element and the relative pathname of the second element.
 To copy the file directly to the htdocs directory, use a pathname of
 . or './.'.  

 For example:
 file_path = ( /home/tester/testfile.html => mydepartment/myproject )
 will copy the file to ./htdocs/mydepartment/myproject/testfile.html.

 PARAMETER: ignore_case  TYPE: global and/or test block parameter
 DEFAULT: no  ALLOWED VALUES: no yes  OPTIONAL PARAMETER.
 DESCRIPTION: Option to do case-insensitive matching for text_forbid
 and text_require parameters.  This does not affect the regex_forbid
 or regex_require parameters.

 PARAMETER: ignore_error_log  TYPE: global and/or test block 
 parameter  DEFAULT: no  ALLOWED VALUES: no yes  OPTIONAL PARAMETER.
 DESCRIPTION: Option to ignore any errors found in the Apache error
 log.  The default behavior is to flag an error if the fetch causes
 any errors to be added to the error log and echo the errors to
 the program output. This parameter is ignored unless the file_path
 parameter is specified.  See also the apache_loglevel parameter.
 See also the Restrictions / Bugs section.

 PARAMETER: include_file_path  TYPE: global parameter
 NO DEFAULT.  ALLOWED VALUES: Even-numbered list elements cannot 
 begin with '../' or contain '/../'.  OPTIONAL PARAMETER.  You can
 specify more than one instance of this paramter.
 DESCRIPTION: List with an even number of elements.  Odd-numbered
 elements are files to copy to the the temporary Apache directory
 before running the tests.  These files can be specified using
 either an absolute or a relative pathname.  Even-numbered elements
 are the subdirectory pathname, relative to the Apache ServerRoot
 directory, to copy the corresponding file to.  The copied file
 will have the same basename as the odd-numbered element and the
 relative pathname of the corresponding even-numbered element.
 To copy the file directly to the ServerRoot directory, use a
 pathname of . or './.'.

 For example:
 include_file_path = (/home/tester/inc/header.inc => htdocs/includes)
 will copy the file to htdocs/includes/header.inc.

 This parameter is also useful for adding Perl modules that are
 needed by the web page specified by the file_path parameter.  For
 example:
 include_file_path = ( ../apps/myapp/DBconn.pm => lib/perl/apps ) 
 will copy the Perl module DBconn.pm to a directory that is in the 
 Perl @INC array.

 An alternative to using the include_file_path parameter is to
 manually copy the files into the desired subdirectory in the
 directory specified by the apache_dir parameter.

 PARAMETER: mail  TYPE: global parameter  
 DEFAULT: no  ALLOWED VALUES: no errors all  OPTIONAL PARAMETER.
 DESCRIPTION: Option to e-mail reports to the addresses in
 the mail_addresses parameter using the server specified by the
 mail_server parameter.  If set to no, no e-mail is sent.  If set to
 errors and one or more of the tests in the parameter file fails,
 an e-mail is sent that contains the results of all tests in the
 parameter file.  If set to all, an e-mail is sent containing the
 results of all tests in the parameter file, regardless of success
 or failure.

 PARAMETER: mail_addresses  TYPE: global parameter  
 NO DEFAULT.  REQUIRED unless mail = no.
 DESCRIPTION: List of e-mail addresses to send mail to.  This
 parameter has two uses.  If the mail parameter is set to "errors"
 or "all", the program sends mail containing the program output
 to these addresses.  If the Apache executable specified by the
 apache_exec parameter has the Apache::ASP Perl module configured,
 server errors generated while compiling or running Apache::ASP
 scripts will be e-mailed to the first address in the mail_addresses
 list.

 PARAMETER: mail_server  TYPE: global parameter  
 NO DEFAULT.  REQUIRED unless mail = no.
 DESCRIPTION: Name of mail server.  

 PARAMETER: method  TYPE: test block parameter
 DEFAULT: get  ALLOWED VALUES: get post  OPTIONAL PARAMETER.
 DESCRIPTION: HTTP method for the request(s).  See RFC 2616 
 (HTTP/1.1 protocol).

 PARAMETER: max_bytes  TYPE: test block parameter
 NO DEFAULT   ALLOWED VALUES: Any integer greater that zero and
 greater than min_bytes (if min_bytes is specified).  OPTIONAL
 PARAMETER.
 DESCRIPTION: Maximum number of bytes expected in returned page.  
 If this value is exceeded, an error message is displayed.

 PARAMETER: min_bytes  TYPE: test block parameter
 NO DEFAULT   ALLOWED VALUES: Any integer less than max_bytes (if 
 max_bytes is specified).  OPTIONAL PARAMETER.
 DESCRIPTION: Minimum number of bytes expected in returned page.  
 If the number of returned bytes is less than this value, an error 
 message is displayed.

 PARAMETER: params  TYPE: test block parameter
 NO DEFAULT.  ALLOWED VALUES: A list with an even number of 
 elements.  OPTIONAL PARAMETER.
 DESCRIPTION: A set of parameter name/value pairs to be passed
 with the request.  (This parameter is used to test pages that
 process forms.)  Unless the method parameter is set to 'post',
 these pairs are URI-escaped and appended to the requested URL.
 For example,
 url = http://www.hotmail.com/cgi-bin/hmhome
 params = ( curmbox 
            F001 A005 
            from
            HotMail ) 
 generates the request:
 http://www.hotmail.com/cgi-bin/hmhome?curmbox=F001%20A005&from=HotMail
 The names and values will be URI-escaped as defined by RFC 2396.
 (See http://www.ietf.org/rfc/rfc2396.txt.) 

 PARAMETER: proxies  TYPE: global parameter
 NO DEFAULT.  ALLOWED VALUES: A list with an even number of 
 elements.  OPTIONAL PARAMETER.
 DESCRIPTION: A set of service name / proxy URL pairs that specify
 proxy servers to use for requests.  For example: 
 proxies = ( http => http://http_proxy.mycompany.com
             ftp  => http://ftp_proxy.mycompany.com )

 -------------------------------------------------------------------

 The regex_forbid and regex_require parameters contain one or more
 Perl regular expressions.  The regex_forbid and regex_require
 parameter values are compared to the fetched page contents as the
 right hand side of a "=~" operator.  If you want to search for a
 literal string, use the text_forbid and text_require parameters.
 For more information, type "man perlre" or see Programming Perl,
 3rd edition, Chapter 5.

 You can specify these parameters globally or within a test block.
 If you specify one as both a global and a test block parameter, the
 value in the test block applies only to that test block.  

 PARAMETER: regex_forbid  TYPE: global and/or test block parameter  
 NO DEFAULT.  OPTIONAL PARAMETER.  
 DESCRIPTION: List of one or more regular expressions that must
 NOT exist on the web page.  See also the text_forbid parameter.

 PARAMETER: regex_require  TYPE: global and/or test block parameter  
 NO DEFAULT.  OPTIONAL PARAMETER.
 DESCRIPTION: List of one or more regular expressions that MUST
 exist on the web page.  See also the text_require parameter.

 -------------------------------------------------------------------

 PARAMETER: save_output  TYPE: global parameter
 DEFAULT: no  ALLOWED VALUES: no yes preserve  OPTIONAL PARAMETER.
 DESCRIPTION: Option to redirect the program output to a file.
 (Error messages still go to the terminal.)  The program constructs
 the file name by taking the name of this parameter file, removing
 the file extension if it exists and appending ".out".  If there is
 an existing file with that name, the program overwrites the file if
 save_output is set to 'yes'.  If save_output is set to 'preserve'
 and the file already exists, output is sent to the terminal.
 This parameter should precede all other parameters in the parameter
 file. (This order is not required.)

 PARAMETER: send_cookies TYPE: global and/or test block parameter  
 DEFAULT: yes  ALLOWED VALUES: no yes  OPTIONAL PARAMETER.
 DESCRIPTION: Option to send cookies to the web server.  This applies
 to cookies passed by the web server(s) during the test session and
 to cookies created using the cookies parameter.  This does NOT
 give the web server(s) access to cookies created with a browser
 or any user agent software other than this program.  The cookies
 created while this program is running are only accessible to other
 tests in the same parameter file.

 You can specify this parameter globally or within a test block.
 If you specify it as both a global and a test block parameter, the
 value in the test block applies only to that test block.  See also
 the accept_cookies parameter.

 PARAMETER: show_cookies TYPE: global parameter  
 DEFAULT: no  ALLOWED VALUES: no yes  OPTIONAL PARAMETER.
 DESCRIPTION: Option to list cookies sent to or received from the web
 server.  Each cookie will be preceded with the string "Set-Cookie3:"
 and the cookie elements will be separated by semicolons.

 PARAMETER: show_html  TYPE: global parameter  
 DEFAULT: no  ALLOWED VALUES: no yes  OPTIONAL PARAMETER.
 DESCRIPTION: Option to display the HTML source with the output.
 You can specify this parameter globally or within a test block.
 If you specify it as both a global and a test block parameter,
 the value in the test block applies only to that test block.
 
 If, and only if, you specify the file_path parameter, the program
 starts a local instance of Apache, copies the file to its htdocs
 directory, fetches the file from Apache and runs the specified
 tests.

 PARAMETER: terse  TYPE: global parameter  
 DEFAULT: no  ALLOWED VALUES: no failed_only summary  OPTIONAL
 PARAMETER.
 DESCRIPTION: Option to display short test report.  If you set
 it to 'summary', the program displays only a one-line summary of
 the tests for each URL/file.  If you set terse to 'failed_only',
 the program only displays the results of tests that failed and
 the summary.  If you set terse to 'no', the program displays all
 the test results and the summary.

 PARAMETER: test_name  TYPE: test block parameter  
 NO DEFAULT.  Parameter is REQUIRED.
 DESCRIPTION: Name of this test.  This MUST be the first parameter
 in the block for each test.  You may specify multiple test blocks
 within a parameter file.  There MUST be one end_test directive
 for each test_name parameter.

 PARAMETER: text_forbid  TYPE: global and/or test block parameter  
 NO DEFAULT.  OPTIONAL PARAMETER.  
 DESCRIPTION: List of one or more text strings that must NOT exist
 on the web page.  See also the ignore_case and regex_forbid 
 parameters.

 PARAMETER: text_require  TYPE: global and/or test block parameter  
 NO DEFAULT.  OPTIONAL PARAMETER.
 DESCRIPTION: List of one or more text strings that MUST exist on
 the web page.  See also the ignore_case and regex_require
 parameters. 

 PARAMETER: url  TYPE: test block parameter  
 NO DEFAULT.  You MUST specify file_path or url, but not both, in
 each test block.
 DESCRIPTION: URL to test, if value starts with "www.", "http://"
 will be prefixed.  A parameter file can contain some test blocks
 that specify file_path and some that specify url.


 APACHE DIRECTORY AND FILES
 
 The apache_dir parameter must be set to the name of a directory
 that contains the subdirectories "conf", "logs" and "htdocs".
 The conf subdirectory must contain a file named "httpd.conf-dist".
 The htdocs subdirectory must contain a subdirectory named webtest
 that contains a file named "is_apache_responding.html".  If your
 installation of Apache has the Perl module Apache::ASP configured,
 the apache_dir directory must also contain a subdirectory named
 "asp_tmp".

 The file httpd.conf-dist must contain all the usual Apache
 configuration parameters.  Also, the httpd.conf-dist file must
 contain the following lines INSTEAD OF the lines containing the
 corresponding parameters (i.e., Port, Listen, ServerRoot, etc.):

 Port Please_do_not_modify_PORT
 Listen Please_do_not_modify_PORT
 ServerRoot Please_do_not_modify_SERVER_ROOT
 ErrorLog Please_do_not_modify_SERVER_ROOT/logs/error.log
 LogLevel Please_do_not_modify_LOG_LEVEL
 CustomLog Please_do_not_modify_SERVER_ROOT/logs/access.log common
 PidFile Please_do_not_modify_SERVER_ROOT/apache.pid
 LockFile Please_do_not_modify_SERVER_ROOT/apache.lock
 ServerName Please_do_not_modify_HOST_NAME
 SSLMutex  file:Please_do_not_modify_SERVER_ROOT/ssl_mutex
 SSLLog      Please_do_not_modify_SERVER_ROOT/logs/ssl_engine_log
 DocumentRoot Please_do_not_modify_SERVER_ROOT/htdocs

 At runtime these tags are replaced with the values needed by the
 Apache server that the program starts.  See the Apache documentation
 for details (http://www.apache.org/docs/mod/directives.html).

 Also, if your installation of Apache has the Perl module
 Apache::ASP configured, you must use the following lines instead
 of the lines containing the corresponding parameters (i.e.,
 PERLSETVAR_GLOBAL, PERLSETVAR_MAILHOST, PERLSETVAR_MAILERRORSTO):

 Please_do_not_modify_PERLSETVAR_GLOBAL
 Please_do_not_modify_PERLSETVAR_MAILHOST
 Please_do_not_modify_PERLSETVAR_MAILERRORSTO

 These lines are usually placed in the FileMatch block of the
 VirtualHost block for the PerlHandler Apache::ASP.  At runtime
 these tags are replaced with the the directive PerlSetVar followed
 by the name of the parameter (Global, MailHost, MailErrorsTo)
 and a parameter value derived from other input parameters.  See 
 the Apache::ASP documentation for details 
 (http://www.apache-asp.org/config.html).

 The subdirectory htdocs must contain a subdirectory named webtest
 that contains a file named "is_apache_responding.html".  This file
 must contain valid HTML and must contain the string
 Please_do_not_modify_TEST_TAG somewhere in the file.  (This file is
 used to verify that Apache has started successfully.)

PREREQUISITES

 Perl version 5.000 or higher is required. The following Perl modules
 are also required.  (These are all part of the base distribution of
 version 5.005_03 and higher.)

 Cwd
 File::Basename
 File::Copy
 File::Find
 File::Path
 HTTP::Cookies
 HTTP::Request::Common
 HTTP::Response
 LWP::UserAgent
 Net::Domain
 Net::SMTP
 Sys::Hostname
 Term::ReadKey
 URI::URL 

RESTRICTIONS / BUGS

This module only works on Unix (e.g., Solaris, Linux, AIX, etc.). The module's HTTP requests time out after 3 minutes (the default value for LWP::UserAgent). If the file_path parameter is specified, Apache must be installed. If the file_path parameter is specified, the directory /tmp cannot be NFS-mounted, since Apache's lockfile and the SSL mutex file must be stored on a local disk.

VERSION

This document describes version 0.01, release date 13 January 2001.

TODO

Add option to validate HTML syntax using HTML::Validator. Add option to check links (see http://world.std.com/~swmcd/steven/perl/pm/lc/linkcheck.html).

AUTHOR

 Richard Anderson <Richard.Anderson@unixscripts.com>

COPYRIGHT

Copyright (c) 2000 Richard Anderson. All rights reserved. This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License.

SEE ALSO

perl(1), perlre(1), perldoc Apache::ASP.