_____         _            ____ ____ ___       
  |_   _|__  ___| |_   _ _   / ___/ ___|_ _|  _ _ 
    | |/ _ \/ __| __| (_|_) | |  | |  _ | |  (_|_)
    | |  __/\__ \ |_   _ _  | |__| |_| || |   _ _ 
    |_|\___||___/\__| (_|_)  \____\____|___| (_|_)
                                                  
   _____      _                        _ 
  | ____|_  _| |_ ___ _ __ _ __   __ _| |
  |  _| \ \/ / __/ _ \ '__| '_ \ / _` | |
  | |___ >  <| ||  __/ |  | | | | (_| | |
  |_____/_/\_\\__\___|_|  |_| |_|\__,_|_|
                                         


This is the README for Test::CGI::External version 0.22.

Test::CGI::External is a "module" for the Perl computer programming
language, a library of computer code to install on a computer.  This
document contains four sections:

1. About - what the module does

2. Documentation - how to learn more about the module

3. Installation - how to install this module on a computer

4. Help - what to do if you get stuck

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

1. ABOUT

Test::CGI::External - run tests on an external CGI program

Test::CGI::External is a tool for mocking a CGI (common gateway
interface) environment and running basic checks of the operation of a
CGI program. For example,

    use Test::More;
    my $tester = Test::CGI::External->new ();
    $tester->set_cgi_executable ('example.cgi');
    $tester->run ({});
    done_testing ();

tests whether

* there is a program called "example.cgi",

* the program "example.cgi" is executable (except on Windows),

and when run, "example.cgi"

* produces something on standard output;

* produces a correct "Content-Type" header;

* does not print out ill-formed headers (for example, print
debugging messages on standard output);

* exits with a zero status;

* does not print any error messages.

Test::CGI::External tests for mistakes such as forgetting to install
the program, forgetting to make it executable, executing print
statements before the headers are printed, exiting without any
printing output, or printing useless error messages during running.

Test::CGI::External runs CGI programs as stand-alone programs, under a
faked CGI-like environment created by manipulating environment
variables. Thus it does not require a web server.  The tested CGI
program can be in any language, not just Perl; the "external" in
Test::CGI::External means it is meant to test external programs which
are completely independent of itself. Test::CGI::External was
originally created to check the operation of CGI programs written in
C.

Test::CGI::External is meant for the testing stage before the program
is put onto a web server. For example, if a program with stray printf
statements is uploaded to the web server and run as a CGI program, the
browser will show only a 500 Server Error message. If the program is
tested with this module before being uploaded, it will be much easier
to find the error. Another typical mistake is forgetting to make the
CGI program executable; again, this results in a
difficult-to-understand server error. This module nips these sorts of
problems in the bud by checking for careless mistakes before the
uploading.

Test::CGI::External is TAP (Test Anything Protocol)-compliant and
works with the standard Perl testing modules like "Test::More".

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

2. DOCUMENTATION

You can read the documentation for the module online at the following
websites:

    * http://search.cpan.org/perldoc?Test::CGI::External
    * http://metacpan.org/release/Test-CGI-External

(These links go to the latest version of the module.)

After installing the module, you can read the documentation on your
computer using

    perldoc Test::CGI::External

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

3. INSTALLATION

This module requires Perl version 5.6.0 or later.

To install the module from CPAN, use

    cpan Test::CGI::External

If you have the App::cpanminus installer, you may prefer

    cpanm Test::CGI::External

To install the module from the source file, Test-CGI-External-0.22.tar.gz,
follow this sequence of commands:

    tar xfz Test-CGI-External-0.22.tar.gz
    cd Test-CGI-External-0.22
    perl Makefile.PL
    make
    make install

If you want to test the module before installing it, use "make test" after
"make" and before "make install".

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

4. HELP

To get help with the module, you can email the author, Ben Bullock, at
<bkb@cpan.org>. If you think there is a problem in the module, you can
report a bug at 

<https://github.com/benkasminbullock/test-cgi-external/issues>,

or if you want to alter the source code of Test::CGI::External, try the
public repository on github at 

<https://github.com/benkasminbullock/test-cgi-external>. 

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

This README was written on Mon Mar  6 16:53:30 2017.

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