cg-eye

A tool for offline CGI debugging and testing

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 offline 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.

Capabilities

The main function of cg-eye offline 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 offline 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 offline.

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 offline

You can download cg-eye offline from here.

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:

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+	  cg-eye: CGI test harness (prototype), Nick Kew, 1997		+
+	   This is an experimental script: do not rely on it		+
+	     Comments and suggestions to nick@webthing.com		+
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Usage: cg-eye
	[-v]			# verbose output
	[-x]			# Extra warnings about possible problems
	[-V validator]		# Document check program (e.g. HTML validator)
	[-O output]		# File to save output document
	[-E envdata]		# Environment variables (Filename)
	[-F formdata]		# Form Data (Filename)
	[-M method]		# POST or GET (default GET)
	program_name

Environment Variables and Form Data take the form
name=value
(one name/value pair per line, no whitespace unless it's part of the value)