cg-eye

Introduction

cg-eye is a test harness for CGI. It may be used as an intermediate stage between running your scripts from the commandline and putting them online, and will diagnose a number of potential problems.

Whilst cg-eye is a perl script, it can be used with CGI programs regardless of what language they're written in. It runs offline, in a (highly imperfect) simulation of a live CGI environment, and prints diagnostics on your program's outputs.

The script is a quick, untested hack which will be fixed/improved when I notice bugs and omissions and when the mood takes me. Or if anyone else cares to adopt the idea, with or without this script as starting-point, please feel free to do so.

Development of a simple CGI program

1. Make sure your program runs OK from the commandline.

2. If it's anything more complicated than HelloWorld, use the offline facilities of a library such as CGI++ or CGI.pm to run tests.

3. Run the program under cg-eye offline, and take note of anything it tells you.

4. If your development machine is different from the webserver, you'll need to repeat at least the first step on the webserver itself. If your program requires data files or external programs, make sure you have enough test cases to include accessing them.

5. Check the program via HTTP using cg-eye interactive.

6. Check the program with your form(s) using cg-eye live.

7. Tell me if you find a problem you think cg-eye should have identified but didn't.

For non-trivial programs you should of course use standards appropriate to your project.

Capabilities

The main function of cg-eye is to simulate an HTTP request passed to your script. It will encode any form data you wish to pass, and CGI environment variables. If the script produces any output, cg-eye will parse it and print a report on the CGI Headers, listing warnings and errors, and summarising (in one line) the function of the output.

If an HTML document is returned it will also check for certain constructs that may not be the same in a CGI context as in plain HTML, but it is emphatically not an HTML validator or linter. It can, however, pipe the CGI output document to an HTML validator if you have one available, or save it to a file.

Limitations

If your program crashes, it had better print an error message, because you won't get anything meaningful from cg-eye.

It will catch some but not all of the errors that commonly arise when you move from commandline to live testing. For example it will catch failure to access a file because your path is wrong, but not the same failure due to wrong file permissions.

Bugs

1. Runs under your UID, not the webserver's.
2. Due to (1) the environment will be incorrect.
3. Only understands GET and POST
4. Lots. It's a quick, untested hack.

Downloading and running cg-eye

You can download cg-eye from here. You may also care to download the prototype Environment Data File (use with cg-eye's -E option; the format of Form Data is the same).

Prerequisites

1. Perl 5
2. The Getopt::Std module (included with Perl I believe)
3. The URI::Escape module.

If you are missing any of these, you can get them from CPAN.

Running

As soon as you've made it executable, just type cg-eye (no arguments), and it will display a help screen.

Related Resources

The CGI Programming FAQ lists related resources of which I am aware.

Tom Christiansen's Idiot's Guide deserves a special mention: it deals with rather more of the common problems than cg-eye can.

Two related ONLINE tools to call your CGI programs remotely and print reports are:

• Brian Foy's httpeek is the closest to cg-eye: instead of simulating Form and Environment Data, httpeek permits you to send the real thing to your script.
• Nick Kew's Header Dumper takes a real request from your browser and forwards it to your CGI program, printing a report of the request and the response.

Discussion

Comments to nick@webthing.com. If there's interest, I will open a cg-eye discussion forum at htmlhelp.com or webthing.com.