Update debug-phantomjs example and docs

README.md

@@ -351,16 +351,18 @@ Apart from the default settings, there are a number of options that can be speci
   ```javascript
   // option snippet showing multiple options for all pages
   {
-    phantomjsOptions: ["--remote-debugger-port=8080","--remote-debugger-autorun=true"]
+    phantomjsOptions: ["--load-images=false", "--ignore-ssl-errors=true"]
   }
 
   // option snippet showing multiple options for one page only (object notation)
   {
     phantomjsOptions: {
-      "http://mysite.com/myProblemPage": ["--remote-debugger-port=8080","--remote-debugger-autorun=true"],
+      // key must exactly match the page as defined in the input (sitemap, array, robots, etc)
+      "http://mysite.com/mypage": ["--load-images=false", "--ignore-ssl-errors=true"],
     }
   }
   ```
+  An example demonstrating how to **debug** a PhantomJS script is available [here](https://github.com/localnerve/html-snapshots/tree/master/examples/debug-phantomjs). It also demonstrates per-page option usage.
 
 + `phantomjs`
   + default: A package local reference to PhantomJS.

examples/debug-phantomjs/README.md

@@ -0,0 +1,36 @@
+# Example
+
+> Demonstrate how to debug a page being snapshotted in PhantomJS
+
+> All examples assume you already have NodeJS installed on your local machine
+
+## How To Run
+1. Clone this repo
+2. Open a command prompt
+3. Change to the examples/debug-phantomjs directory
+4. Run `npm install`
+5. Run `node ./snapshot.js`
+
+## What It Does
+This example snapshots the entire website of the WPSPA example application using its sitemap to drive.
+However, it sets up PhantomJS to debug just the "hello-world" page of the application on port 9000 as seen through the default html-snapshots script.
+The html-snapshots process will see the page you are debugging timeout, but that is OK - we're holding it for debugging.
+
+NOTE: Each PhantomJS instance launched with the --remote-debugger-port option will stay alive, even after the script calls exit. You have to end the process yourself.
+
+## How to debug on port 9000
+1. Add the `phantomjsOptions` option to your html-snapshots options.
+2. Assign `"--remote-debugger-port=9000"` to the page you want to debug.
+3. Open up Chrome and navigate to http://`<ipaddress>`:9000. If you executed html-snapshots on the same machine, the `<ipaddress>` will be 127.0.0.1
+4. Click "about:blank"
+5. In the "Scripts" tab, find the "about:blank" script in the dropdown. This is the html-snapshots default PhantomJS script.
+6. Set some breakpoints.
+7. In the "Console" tab, type `__run()` and hit enter.
+8. Step through the code.
+
+For more detailed explanation, checkout the remote debugging section of the [PhantomJS troubleshooting](http://phantomjs.org/troubleshooting.html) guide.
+
+Even after the script exits, PhantomJS will stick around because it was launched in debug mode. Presumably, this is so you can continue debugging over and over if need be.
+If you want to kill it:
+1. `pgrep phantomjs` to find the PID of the phantomjs debug process
+2. kill -15 <PID>

examples/debug/package.json → examples/debug-phantomjs/package.json

@@ -4,6 +4,6 @@
   "author": "Alex Grant <alex@localnerve.com>",
   "description": "An example using html-snapshots",
   "dependencies": {
-    "html-snapshots": "https://github.com/localnerve/html-snapshots#rc-7.0"
+    "html-snapshots": "^0.7.0"
    }
 }

examples/debug-phantomjs/snapshot.js

@@ -0,0 +1,60 @@
+/*
+ * Debug PhantomJS processing of a page on a sample website
+ * 
+ * Uses sitemap.xml to snapshot a sample website, but holds one page for debugging.
+ * 
+ * Demonstrates how to walk through the html-snapshots default script.
+ * Demonstrates phantomjsOptions usage on a per-page basis.
+ * 
+ */
+var path = require("path");
+var util = require("util");
+var assert = require("assert");
+var htmlSnapshots = require("html-snapshots");
+
+// Assert if NOT an error
+function mustBeError(err) {
+  assert.throws(
+    function() {
+      assert.ifError(err);
+    },
+    function(err) {
+      return !!err;
+    }
+  );
+}
+
+// For debugging, it might make more sense to do this for a single page of interest using array input,
+//  but this also demonstrates the use of phantomjsOptions in the per-page case.
+htmlSnapshots.run({
+  input: "sitemap",
+  source: "http://enigmatic-refuge-9006.herokuapp.com/sitemap.xml",
+  outputDir: path.join(__dirname, "./tmp"),
+  outputDirClean: true,
+  selector: ".page-content",
+  timeout: 15000,
+  phantomjsOptions: {
+    // The key must exactly match the loc as defined in the sitemap.xml
+    "http://enigmatic-refuge-9006.herokuapp.com:80/hello-world": "--remote-debugger-port=9000"
+  }
+}, function(err, completed) {  
+
+  console.log("completed snapshots:");
+  console.log(util.inspect(completed));
+
+  // We expect the hello-world page will timeout because we've held it in the debugger
+  //   It will succeed if you use --remote-debugger-autorun=true
+  //   However, the PhantomJS process instances won't exit so that you can (re)debug
+  mustBeError(err);
+});
+
+// Now, go open chrome and navigate to http://127.0.0.1:9000
+//  1. click "about:blank"
+//  2. click "Scripts" tab and find "about:blank" script in dropdown - that's the phantomjs script
+//  3. Set some breakpoints
+//  4. click the "Console" tab, type `__run()`, hit enter
+//  5. Step through and observe whats going on.
+//
+// More info: http://phantomjs.org/troubleshooting.html
+//
+// You have to kill PhantomJS instances yourself if you start them with the debug option.