Updated README with link to good test cases

Author: donasaur

README.md

@@ -20,10 +20,10 @@ npm install http-proxy-rules --save
   // Set up proxy rules instance
   var proxyRules = new HttpProxyRules({
     rules: {
-      '.*/test': 'http://localhost:8080/cool',
-      '.*/test2/': 'http://localhost:8080/cool2/'
+      '.*/test': 'http://localhost:8080/cool', // Rule (1)
+      '.*/test2/': 'http://localhost:8080/cool2/' // Rule (2)
     },
-    default: 'http://localhost:8080'
+    default: 'http://localhost:8080' // default target
   });
 
   // Create reverse proxy instance
@@ -33,7 +33,7 @@ npm install http-proxy-rules --save
   // and proxy rules to proxy requests to different targets
   http.createServer(function(req, res) {
 
-    // a test method is exposed on the proxy rules instance
+    // a match method is exposed on the proxy rules instance
     // to test a request to see if it matches against one of the specified rules
     var target = proxyRules.match(req);
     if (target) {
@@ -47,6 +47,8 @@ npm install http-proxy-rules --save
   }).listen(6010, cb);
 ```
 
+Given the object we used to initialize the `HttpProxyRules` instance above, here are some [**examples**](test/index.tests.js#L38) of how sample url paths would be translated.
+
 ## Options
 
 You can initialize a new `http-proxy-rules` instance with the following options:
@@ -57,7 +59,7 @@ You can initialize a new `http-proxy-rules` instance with the following options:
   default: '' // (optional) if no rules matched, translate url path to specified default
 }
 ```
-The rules object contains a set of key-value pairs mapping a regex-supported url path to a target route. The target route must include the protocol (e.g., http) and the FQDN. See the [tests](test/index.tests.js) for examples of how incoming route url paths may be translated with the use of this module.
+The rules object contains a set of key-value pairs mapping a regex-supported url path to a target route. The module only tries to match the visited url path, and not the entire url, with a specified rule. The target route must include the protocol (e.g., http) and the FQDN. See the [tests](test/index.tests.js) for examples of how incoming route url paths may be translated with the use of this module.
 
 ## Other Notes
 * `(?:\\W|$)` is appended to the end of the regex-supported url path, so that if there is a key like  `.*/test` in the rules, the module matches paths `/test`, `/test/`, `/test?` but not `/testing`.

example/simple.js

@@ -8,10 +8,10 @@ module.exports = function spawnReverseProxy(cb) {
   // Set up proxy rules instance
   var proxyRules = new HttpProxyRules({
     rules: {
-      '.*/test': 'http://localhost:8080/cool',
-      '.*/test2/': 'http://localhost:8080/cool2/'
+      '.*/test': 'http://localhost:8080/cool', // Rule (1)
+      '.*/test2/': 'http://localhost:8080/cool2/' // Rule (2)
     },
-    default: 'http://localhost:8080'
+    default: 'http://localhost:8080' // default target
   });
 
   // Create reverse proxy instance
@@ -21,7 +21,7 @@ module.exports = function spawnReverseProxy(cb) {
   // and proxy rules to proxy requests to different targets
   http.createServer(function(req, res) {
 
-    // a test method is exposed on the proxy rules instance
+    // a match method is exposed on the proxy rules instance
     // to test a request to see if it matches against one of the specified rules
     var target = proxyRules.match(req);
     if (target) {

test/index.tests.js

@@ -10,7 +10,7 @@ var spawnReverseProxy = require('../example/simple'),
 describe('Proxy Routes', function () {
   var proxyServerPort = 6010;
   var targetPort = 8080;
-  var targetPrefix = '127.0.0.1:' + targetPort;
+  var targetFQDN = '127.0.0.1';
 
   before(function (done) {
     // runs before all tests in this block
@@ -35,32 +35,50 @@ describe('Proxy Routes', function () {
 
   it('should translate the url correctly', function (done) {
 
-    // Feel free to add more cases
     var urlTranslationTests = [{
+        // visited path matches rule (1).
         visitedPath: '/test',
-        newUrlTarget: targetPrefix + '/cool'
+        newUrlTarget: targetFQDN + targetPort + '/cool'
       }, {
+        // visited path matches rule (1).
+        // whatever portion is not part of the match is carried over
+        // to the new path.
+        // in this case, the '/' is carried over.
         visitedPath: '/test/',
-        newUrlTarget: targetPrefix + '/cool/'
+        newUrlTarget: targetFQDN + targetPort + '/cool/'
       }, {
+        // visited path matches rule (1).
+        // query parameters are carried over.
         visitedPath: '/test?hi=5/',
-        newUrlTarget: targetPrefix + '/cool?hi=5/'
+        newUrlTarget: targetFQDN + targetPort + '/cool?hi=5/'
       }, {
+        // visited path matches rule (2).
+        // the unmatched portion '/yo' is carried over.
         visitedPath: '/test2/yo',
-        newUrlTarget: targetPrefix + '/cool2/yo'
+        newUrlTarget: targetFQDN + targetPort + '/cool2/yo'
       }, {
+        // visited path matches rule (1).
+        // note that the key is interpreted as a regex expression and the
+        // module matches against the visited path, and not the entire url.
         visitedPath: '/fuzzyshoe/test',
-        newUrlTarget: targetPrefix + '/cool'
+        newUrlTarget: targetFQDN + targetPort + '/cool'
       }, {
+        // visited path matches rule (1).
+        // the unmatched portion '/seven' is carried over.
         visitedPath: '/test/seven',
-        newUrlTarget: targetPrefix + '/cool/seven'
+        newUrlTarget: targetFQDN + targetPort + '/cool/seven'
       }, {
-        // should match /test but not /testalmost
+        // no rule matched, so the module uses the specified default target.
+        // the entire visited path is carried over.
+        // see the `Other Notes` section of README to see why specifying
+        // the rule `.*/test` does not match `/testalmost`.
         visitedPath: '/testalmost',
-        newUrlTarget: targetPrefix + '/testalmost'
+        newUrlTarget: targetFQDN + targetPort + '/testalmost'
       }, {
+        // no rule matched, so the module uses the specified default target.
+        // the entire visited path is carried over.
         visitedPath: '/testalmost/5',
-        newUrlTarget: targetPrefix + '/testalmost/5'
+        newUrlTarget: targetFQDN + targetPort + '/testalmost/5'
       }
     ];
 
@@ -73,7 +91,7 @@ describe('Proxy Routes', function () {
       }, function processResp(err, res, body) {
 
         expect(res.statusCode).to.equal(200);
-        expect(targetPrefix + body.translatedPath).to.equal(comparisonObj.newUrlTarget);
+        expect(targetFQDN + targetPort + body.translatedPath).to.equal(comparisonObj.newUrlTarget);
         cb();
       });
     }, done);