Readme for WebParrot
Uses node.js v0.6.6 (http://nodejs.org/#download)
Web parrot is designed to facilitate repeatable client side testing by emulating
 your server. It does so by listening to your http traffic then replaying 
 what it has heard.

For example, I try to access www.example.org. 
The first time I do so the parrot acts like a normal proxy and just relays
 the page. The next time I access the www.example.org the parrot acts like
 the server, reading the request and sending the response it heard earlier.

To run WebParrot use node.js to run WebParrot.js
"node WebParrot.js [-v 0|1|2|3] [-m translucent|transparent|opaque] [-p port] [-h] 
 [-strip]"
Next set your browser to use your machine as a proxy. By default WebParrot
uses port 9090.
Be sure to clear your browser's cache before using (see cache issues below).





WebParrot has three modes:
translucent: In this mode any unknown request will be sent to the server while any
  known request will be parroted.
transparent: In this mode all requests are sent to the server and the parrot acts 
  like a normal proxy, however all responses will be recorded.
opaque: In this mode no requests will be sent to the server, any unknown requests
  will receive a blank page. Do not start the parrot in opaque mode.



Verbosity:
0 is quiet mode, no messages except that it started correctly.
1 is changes mode, only changes to the settings (done via the admin page) will be logged.
2 is requests mode, only messages about known and unknown requests will be logged. (implies 1)
3 is all mode, logs a message for every piece of every request and response received.

Proxy port: WebParrot can run the proxy on any port, to specify a port use the -p 
 argument
 
Help: The -h argument shows help about the other arguments.

Stripping: The -strip argument will remove all 'if-none-match' and 'if-modified-since' headers
 from all requests through the parrot. This means that the server will never respond with a
 status code '304 not modified' and effectively solves all issues related to the local cache.

Admin page:
WebParrot also launches a http server in addition to the proxy server. This server
 can be reached at <proxy URL>:<proxyPort>. This is by default localhost:9090. 
 Note that all traffic to the proxy port will be ignored by the parrot.

Demo page: 
 WebParrot hosts a page for testing and demonstration. This page is hosted at 
 <proxy URL:<proxy Port>/demo. Note that the demo is a special case which will 
 be cached and parroted unlike other traffic to the proxy port.

Request hashing:
 In order to differentiate requests with the same URL but a different body all 
 request bodies are hashed using MD5. This hash will appear at the end of the
 entry in the list and is 0 for all gets.

Local Cache issues:
If you are trying to view a page you have viewed before your browser may send 
 a cache check instead of a normal GET. If the page has no changed then the 
 server will response by saying that the cached page is correct. This response
 will be recorded by the parrot. Thus you may try to reload from the parrot
 only to get a '304 not modified'. There are three ways to avoid this issue:
   1. Clear local cache before using
   2. Tell the parrot to ignore the request.
   3. Strip the headers of the requests using the -strip argument (see stripping above)


Locking and ignoring:
Requests can be set to be locked and/or ignored. Locking a request makes it so
 that the response will not change, even if a new response is seen. (only makes
 sense in transparent mode or response is set to ignored). Ignoring a request
 makes it so that the request is always treated as unknown. Thus in translucent
 mode the server will always receive the request and in opaque mode a 404 will
 always be delivered (thus locking only makes sense in translucent mode).

Refreshing server Cache:
 WebParrot can check if there is an update to the cache and update the cache
 without having you reload the page in your browser. Select a url from the list
 and click either the 'Check Cache' or 'Replace Cache' buttons. An entry in the 
 list ending with a 'X' has unknown cache status. An entry in the list ending 
 with a 'o' has an update and an entry in the list ending with a '*' has no 
 update. 
 
    Note that at this time the cache only uses the ETag part of the http
    header to determine if there is an update or not. I intend to add a strong
    validation that checks byte by byte.
 
    Also note that the cache refreshing only works for 'GET' requests, it will ignore
    any other methods.

Preview:
   You can preview a cached page by selecting its entry in the list and pressing
   'Display'. At this time only rendering the response works however I intend to
   allow viewing the source of the response and the headers of the request.


Custom Admin pages:
WebParrot also launches a http server in addition to the proxy server. By default
 this serves '/admin'. However it will load any javascript files in index.js in 
 the public folder via nodejs's require. To add your own admin page do the following.
 1. Add a new js file to the public folder.
 2. Add this js file to index.js.
 3. In your js file 'require(../ParrotAPI)'.
 4. From ParrotAPI get app, which is an express web server.
 5. Add your page using 'app.get('page', callback). Where callback is a function
   that will deliver the page.


Copyright Andrew Barton andrewbbarton@gmail.com,  2012
http://www.opensource.org/licenses/MIT, see LICENSE