Override generated scenarios

README.md

@@ -32,7 +32,9 @@ $ npm install --global backstop-crawl
     --limit-similar[=3]  Limits the number of similar URLs to a set number
                          Defaults to 3
                           e.g /blog/1, /blog/2, /blog/3
-    --reference-url  Allows a reference URL to be used in testing
+    --reference-url      Allows a reference URL to be used in testing
+    --template           Specify the template file to use
+                           Defaults to backstop.template.json
 
   Examples
     $ backstop-crawl http://localhost
@@ -62,6 +64,10 @@ For example:
 }
 ```
 
+After generating your `backstop.json`, you can modify scenarios and copy them into `scenarios` in your template. The next time you run `backstop crawl`, these scenarios will override generated scenarios with a matching label.
+
+Ex. One of your pages takes a little more time to load, so you need to increase the delay. Rather than increasing the delay in the `defaultScenario` (which would impact all tests) you can override just that one case by copying it into `scenarios` in your template and modifying the value for `delay`.
+
 ## License
 
 MIT © fffunction [fffunction.co](https://fffunction.co)

index.js

@@ -2,6 +2,7 @@
 
 'use strict';
 
+const fs = require('fs');
 const meow = require('meow');
 const validurl = require('valid-url').is_web_uri;
 const updateNotifier = require('update-notifier');
@@ -30,7 +31,9 @@ const cli = meow(
       --limit-similar[=3]  Limits the number of similar URLs to a set number
                            Defaults to 3
                             e.g /blog/1, /blog/2, /blog/3
-      --reference-url  Allows a reference URL to be used in testing
+      --reference-url      Allows a reference URL to be used in testing
+      --template           Specify the template file to use
+                           Defaults to backstop.template.json
 
     Examples
       $ backstop-crawl http://localhost
@@ -59,6 +62,17 @@ if (cli.flags.referenceUrl) {
     }
 }
 
+if (cli.flags.template) {
+    fs.access(cli.flags.template, fs.F_OK, (err) => {
+        if (err) {
+            console.error(
+                `> Error: "${cli.flags.template}" doesn't exist`
+            );
+            process.exit(1);
+        }
+    })
+}
+
 if (cli.input.length > 0) {
     if (validurl(cli.input[0])) {
         crawl(cli.input[0], cli.flags);

lib/crawl.js

@@ -11,19 +11,11 @@ const jsonfile = require('jsonfile');
 const cheerio = require('cheerio');
 const normalurl = require('normalize-url');
 const limitSimilar = require('./limit-similar');
+const processOverrides = require('./process-overrides');
 
 const dirname = path.dirname;
-const confPath = path.resolve(process.cwd(), 'backstop.template.json');
-const defaultConf = fs.existsSync(confPath)
-    ? JSON.parse(fs.readFileSync(confPath))
-    : require('./backstop.template.json');
-
-/**
- * Stash the default scenario from the template then delete it
- * as defaultScenario isn't a valid key for backstop.json
- */
-const defaultScenario = defaultConf.defaultScenario;
-delete defaultConf.defaultScenario;
+
+let overriddenScenarios = [];
 
 const EXT_BLACKLIST = /\.pdf|\.js|\.css|\.png|\.jpg|\.jpeg|\.gif|\.json|\.xml|\.txt$/i;
 const SPINNER_WIDTH = 2;
@@ -35,6 +27,8 @@ function crawl(url, flags) {
     const spinner = ora('Crawling...');
     let outfile = './backstop.json';
 
+    let confPath = path.resolve(process.cwd(), 'backstop.template.json');
+
     crawler.discoverResources = function(buffer) {
         const $ = cheerio.load(buffer.toString('utf8'));
 
@@ -80,6 +74,24 @@ function crawl(url, flags) {
         crawler.scanSubdomains = true;
     }
 
+    if (flags.template) {
+        confPath = flags.template;
+    }
+
+    const defaultConf = fs.existsSync(confPath)
+        ? JSON.parse(fs.readFileSync(confPath))
+        : require('./backstop.template.json');
+
+    /**
+     * Stash the default scenario from the template then delete it
+     * as defaultScenario isn't a valid key for backstop.json
+     */
+    const defaultScenario = defaultConf.defaultScenario;
+    delete defaultConf.defaultScenario;
+
+    // Grab any scenarios defined in the template.
+    overriddenScenarios = defaultConf.scenarios;
+
     // Skip this small blacklist of extensions
     crawler.addFetchCondition(
         queueItem => !queueItem.path.match(EXT_BLACKLIST)
@@ -104,11 +116,11 @@ function crawl(url, flags) {
 
             if (flags.referenceUrl) {
                 // Normalize the URL to remove duplicate slashes. See #25
-                currentScenario.referenceUrl = normalurl( 
+                currentScenario.referenceUrl = normalurl(
                     queueItem.url.replace(
                         url,
                         flags.referenceUrl
-                    ) 
+                    )
                 );
 
                 // Add a trailing slash to referenceUrl if url has a trailing slash and referenceUrl does not
@@ -138,6 +150,9 @@ function crawl(url, flags) {
             });
             urls = limitSimilar(urls, flags.limitSimilar);
         }
+
+        urls = processOverrides(urls, overriddenScenarios);
+
         defaultConf.scenarios = urls;
         const outPath = dirname(outfile);
         mkpath(outPath, mkpathErr => {
@@ -154,7 +169,7 @@ function crawl(url, flags) {
                             spinner.text = jsonfileErr;
                             spinner.fail();
                         } else {
-                            spinner.text = 'backstop.js generated';
+                            spinner.text = `${outfile} generated`;
                             spinner.succeed();
                         }
                     }

lib/process-overrides.js

@@ -0,0 +1,13 @@
+module.exports = processOverrides;
+function processOverrides(urls, scenarios) {
+
+    scenarios.forEach((scenario, scenarioKey) => {
+        urls.forEach((url, urlKey) => {
+            if (url.label === scenario.label) {
+                urls[urlKey] = scenarios[scenarioKey];
+            }
+        });
+    });
+
+    return urls;
+}