Table of Contents:

NAME
SYNOPSIS
DESCRIPTION
METHODS
ENVIRONMENT VARIABLES
FILES
PREREQUISITES
RESTRICTIONS / BUGS
VERSION
TODO
AUTHOR
COPYRIGHT
SEE ALSO

NAME
    HTTP::WebTest - Test remote URLs or local web files

SYNOPSIS
     This module can accept input parameters from a parameter file
     or subroutine arguments.

     TO RUN WEB TESTS DEFINED BY SUBROUTINE ARGUMENTS:

     use HTTP::WebTest;
     run_web_test(\@web_tests, \$num_fail, \$num_succeed, \%test_options)

     or

     use HTTP::WebTest;
     run_web_test(\@web_tests, \$num_fail, \$num_succeed)

     TO RUN WEB TESTS DEFINED BY A PARAMETER FILE:

     use sigtrap qw(die normal-signals); # Recommended, not necessary
     use HTTP::WebTest;
     $webtest = HTTP::WebTest->new();
     $webtest->web_test('my_web_tests.wt', \$num_fail, \$num_succeed);

     The web_test() method has an option to test a local file by
     starting Apache on a private port, copying the file to a temporary
     htdocs directory and fetching the page from Apache.  If you are
     testing with multiple parameter files, you can avoid restarting
     Apache each time by calling new() only once and recycling the object:

     use sigtrap qw(die normal-signals); # Recommended, not necessary
     use HTTP::WebTest;
     $webtest = HTTP::WebTest->new(); 
     foreach $file (@ARGV) {
        $webtest->web_test($file, \$num_fail, \$num_succeed);
     }

     TO ENABLE DEBUGGING MESSAGES (OUTPUT TO STDOUT):

     If you are calling the web_test method, use the debug parameter.
     If you are calling the run_web_test method, do this:

     use HTTP::WebTest;
     $HTTP::WebTest::Debug = 1; # Diagnostic messages
     $HTTP::WebTest::Debug = 2; # Messages and preserve temp Apache dir
     run_web_test(\@web_tests, \$num_fail, \$num_succeed)

DESCRIPTION
    This module runs tests on remote URLs or local web files containing
    Perl/HTML/JavaScript/etc. and generates a detailed test report. This
    module is designed to test the source code, not the webserver or
    Internet connectivity. (There are a variety of better solutions for
    testing server reponse times or Internet connectivity.)

    The test specifications can be read from a parameter file or input as
    method arguments. If you are testing a local file, Apache is started on
    a private/dynamic port with a configuration file in a temporary
    directory. The module displays the test results on the terminal by
    default or directs them to a file. The module optionally e-mails the
    test results. When the calling program exits, the module stops the
    local instance of Apache and deletes the temporary directory.

    Each test consists of literal strings or regular expressions that are
    either required to exist or forbidden to exist in the fetched page. You
    can also specify tests for the minimum and maximum number of bytes in
    the returned page. If you are testing a local file, the module checks
    the error log in the temporary directory before and after the file is
    fetched from Apache. If messages are written to the error log during
    the fetch, the module flags this as an error and writes the messages to
    the output test report.

    The wt script is provided for running HTTP::WebTest from the command
    line.

    Data flow for WebTest using a remote URL:

              --------------              -------------
              |            |              |           |
              | Input      |------------->|  WebTest  |
              | parameters |              |           |
              |            |              -------------
              --------------                  |   ^
                                              |   |
                                              V   |
              -------------               ------------
              |           |    request    |          |
              | Remote    |<--------------|   HTTP   |
              | webserver |-------------->|   user   |
              |           |    response   |   agent  |
              -------------               |          |
                                          ------------
                                          
    Data flow diagram for WebTest using a local web file:

              --------------           ---------------------
              |            |           |                   |
              | Input      |           |  Web page code    |
              | parameters |           |  (HTML/perl/etc.) |
              |            |           |                   |
              --------------           ---------------------
                    |                            |
                    |  ---------------------------
                    |  |
                    V  V              ------------------------
              -------------           |                      |
              |           |---------->| Temporary Apache     |
              |  WebTest  |           | directories (htdocs, |
              |           |<----------| conf, logs)          |
              -------------           |                      |
                  |  ^                ------------------------
                  |  |                        |    ^
                  V  |                        V    |
              ------------             ----------------------
              |          |   request   |                    |
              |   HTTP   |------------>| Temporary local    |
              |   user   |             | instance of Apache |
              |   agent  |<------------|                    |
              |          |   response  ----------------------
              ------------

METHODS
     new($proto) 
     new()
        Create new HTTP::WebTest object.  $proto (optional) is 
        either a reference or a class (package) name.  Returns a new 
        HTTP::WebTest object.

     web_test($param_file, \$num_fail, \$num_succeed)
     web_test($param_file, \$num_fail, \$num_succeed, $save_output)
        Reads and validates input parameters, fetches one or more
        web pages, runs tests, writes results to standard output
        or a file.  Optionally e-mails test results if error found.
        If the parameters specify a test of a local web source file,
        starts Apache on a private/dynamic port and copies the file to
        a temporary htdocs directory.

        Input arguments:
        $param_file - A relative or absolute pathname to a parameter 
           file.  See the FILES section for a description of the file.  
        $save_output (optional) - Option to save program output to a file.
           The routine constructs the file name by taking the value of 
           $param_file, removing the file extension if it exists and
           appending ".out".  Error messages are always sent to standard
           error.
           = no       -> Send output to standard output
           = yes      -> Save output to file, overwrite existing file
           = preserve -> Save output to file unless file exists

        Output arguments:
        \$num_fail - The number of tests that failed.
        \$num_succeed - The number of tests that succeeded.

        Return values:
        1 -> All tests ran successfully with no failures.
        0 -> Syntax error in input parameter file, system runtime error or
             one or more of the tests failed. 

     run_web_test(\@web_tests, \$num_fail, \$num_succeed, \%test_options)
     run_web_test(\@web_tests, \$num_fail, \$num_succeed)
        Validates input parameters, fetches one or more urls, runs
        tests, writes results to standard output or a file.  Optionally
        e-mails test results.

        Input/output arguments:
        \@web_tests - An arrayref of hashrefs.  Each hashref defines 
           tests for one URL.  
     
           Some of the hash keys can override the value of the
           corresponding $test_options keys.  For example, if the
           max_bytes hash key is defined in $test_options and you want
           to disable the max_bytes test a particular URL, set the
           web_tests max_bytes hash key to a value of undef or ''.

           If one of the keys below does not exist in one of the
           web_test hashes on input, the module checks the value for
           the corresponding key in the $test_options hash.  If that
           value is defined, then the value from $test_options is used
           during the tests for that web_test hash.

           All input values and keys are preserved on output, except
           the num_fail and num_succeed keys.

           web_tests keys:
           accept_cookies - Overrides the value of the corresponding
              $test_options key FOR THIS URL ONLY.
           auth - Overrides the value of the corresponding test_options
              key FOR THIS URL ONLY.
           cookies - Arrayref of arrayrefs containing cookies to pass
              with the HTTP request.  See RFC 2965 for details
              (ftp.isi.edu/in-notes/rfc2965.txt).  Each array must have
              an even number of elements and must contain at least 10
              elements.  Each array has the form ( version name value
              path domain port path_spec secure maxage discard name1
              value1 name2 value2 ... ), with the following definitions.
              (Required elements are marked with an asterisk; elements
              that are not required can be specified using the undef
              value or ''.)

             *version: Version number of cookie spec to use, usually 0.
             *name: Name of cookie. Cannot begin with a $ character.
             *value: Value of cookie.
             *path: URL path name for which this cookie applies. Must 
                 begin with a / character.  See also path_spec.
             *domain: Domain for which cookie is valid. 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 cookie.
                 = 0 -> Secure protocols not required for transmission.
              maxage: Number of seconds until cookie expires.
              discard: Option to discard cookie when program exits.
                 Default 0.  (The cookie will be discarded regardless 
                 of the value of this element.)
                 = 1 -> Discard cookie.
                 = 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.

           ignore_case - Option to do case-insensitive string matching
                         for text_forbid and text_require arguments.
                          = 'yes'   -> Ignore case while matching strings.
                          Otherwise -> Do case-sensitive string matching.
           ignore_error_log - Option to ignore messages in Apache error
              log.  (See the error_log key in test_options argument.) 
              = 'yes' -> Do not check for messages in the error log
                         FOR THIS URL ONLY.
              Otherwise, check messages if error_log key in test_options
              argument is defined.
           max_bytes - Overrides the value of the corresponding 
              $test_options key FOR THIS URL ONLY.
           min_bytes - Overrides the value of the corresponding 
              $test_options key FOR THIS URL ONLY.
           method - The type of the HTTP request, either 'get' or 'post'.
              If undefined or key does not exist, 'get' is used.
           num_fail (Output) - The number of tests that failed.  If the 
              fetch of the URL fails, one error is counted and the tests 
              for that URL are skipped.  
           num_succeed (Output) - The number of tests that succeeded.  The
              successful fetch of the URL is not counted, only successful
              tests.  If the error_log argument is specified, the absence
              of errors in the logs is counted as a successful test.
           params - A hashref or arrayref containing name/value pairs to
              be passed as parameters to the URL.  (This element is
              used to test pages that process input from forms.) Unless
              the method key is set to post, these pairs are URI-escaped
              and appended to the requested URL.  (See 
              http://www.ietf.org/rfc/rfc2396.txt for URI escapes.)
           proxies - A hashref or arrayref containing 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 )
           regex_forbid - Overrides the value of the corresponding
              $test_options key FOR THIS URL ONLY.
           regex_require - Overrides the value of the corresponding
              $test_options key FOR THIS URL ONLY.
           send_cookies - Overrides the value of the corresponding
              $test_options key FOR THIS URL ONLY.
           show_html - Overrides the value of the corresponding
              $test_options key FOR THIS URL ONLY.
           test_name - Name associated with this url in the test report
              and error messages.
           text_forbid - Overrides the value of the corresponding
              $test_options key FOR THIS URL ONLY.
           text_require - Overrides the value of the corresponding
              $test_options key FOR THIS URL ONLY.
           url - The URL to fetch and test.  This key is REQUIRED. If
              it begins with 'www.', 'http://' is prefixed.

        Output arguments:
        \$num_fail - Total number of tests that failed.
        \$num_succeed - Total number of tests that succeeded.

        Input arguments:
        \%test_options - (Optional) A hashref defining testing options.
           All, some or none of the keys may be defined.  Some of these
           options can also be specified in the web_tests argument.  The
           allowed hash keys are: 

           accept_cookies - Option to accept cookies from the web server.
              = 'no'     -> Do not accept cookies.
              Otherwise  -> Accept cookies.
           auth - Arrayref containing a userid and password to be used
              for web page access authorization.
           error_log - The pathname of a local web server error log.
              The module counts the number of lines in the error
              log before and after each request.  If the number of
              lines increases, an error is counted and the additional
              lines are listed in the report.  (This argument should
              be used only when the local web server is running in
              single-process mode.  Otherwise, requests generated by
              other processes/users may add lines to the error log that
              are not related to the requests generated by this module.)
           fh_out - A filehandle for a file that the test report will be
              written to instead of the terminal.
           mail_addresses - Arrayref containing one or more e-mail
              addresses.
           mail - Option to e-mail output to one or more addresses.
              = 'all'     -> Send e-mail containing test results.
              = 'errors'  -> Send e-mail only if one or more tests fails.
              Otherwise   -> Do not send e-mail.
           mail_server - Fully-qualified name of of the mail server 
              (e.g., mailhost.mycompany.com). 
           max_bytes - Maximum number of bytes expected in returned
              pages.  If this value is exceeded, an error message is
              displayed.
           min_bytes - Minimum number of bytes expected in returned
              pages.  If the number of returned bytes is less than this
              value, an error message is displayed.

           (The regex_forbid and regex_require parameters contain
           one or more Perl regular expressions.  These 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 arguments.  For more
           information, type "man perlre" or see Programming Perl,
           3rd edition, Chapter 5.)

           regex_forbid - Arrayref of regular expressions that are
              forbidden to exist in the returned page.  
           regex_require - Arrayref of regular expressions that are
              required to exist in the returned page.  
           send_cookies - Option to send cookies to web server.  This
              applies to cookies received from the web server or cookies
              specified using the cookies key of the web_test argument. 
              = 'no'     -> Do not send cookies to the web server.
              Otherwise  -> Send cookies to the web server.
           show_cookies - Option to display any cookies sent or received.
              = 'yes'    -> Display cookies in report.
              Otherwise  -> Do not display.
           show_html - Option to include the returned web page in the 
              test report.
              = 'yes'    -> Display the web page in the test report.
              Otherwise  -> Do not display the web page.
           terse - Option to display shorter test report.
              = 'summary'     -> Only a one-line summary for each URL.
              = 'failed_only' -> Only tests that failed and the summary. 
              Otherwise       -> Show all tests and the summary.
           text_forbid - Arrayref of text strings that are forbidden to
              exist in the returned page.  
           text_require - Arrayref of text strings that are required to
              exist in the returned page.  

        Return values:
        1 -> All tests succeeded.
        0 -> Error in input parameters, system runtime error, or one
             or more of the tests failed.

     DESTROY() 
        Kills Apache (if started), deletes temporary directories (if 
        created).  Returns 1 if clean up tasks were successful, 0 
        otherwise.

ENVIRONMENT VARIABLES
     None.

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.31, release date 04 June 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
    wt(1), perl(1), perlre(1), perldoc Apache::ASP.

