feat: Allow specifying test commands in separate modules

Author: prantlf

Gruntfile.js

@@ -226,7 +226,8 @@ module.exports = function (grunt) {
                 });
             }
           }
-        ]
+        ],
+        scenarios: 'test/scenarios/*.js'
       },
       'no-input': {
         options: {

README.md

@@ -203,7 +203,17 @@ If the sub-task contains a property `commands`, this property is supposed to poi
 }
 ```
 
-You can use sub-tasks and commands to create test scenarios and execute them separately, or all of them.
+If the sub-task contains a property `scenarios`, this property is supposed to point to a JavaScript module path or to an array of JavaScript module paths, which would export the array of commands. Relative paths will be resolved to the current (process) directory. It allows to keep the Gruntfile legible and supply the test instructions from other files:
+
+```js
+'html-dom-snapshot': {
+  all: {
+    scenarios: 'scenarios/*.js'
+  }
+}
+```
+
+You can use sub-tasks, `commands` and `scenarios` to structure your code and execute the tests separately, or all of them in one browser window.
 
 ### Instructions
 
@@ -481,7 +491,7 @@ The module for the address book implementation would look like this:
 
 ```js
 module.exports = {
-  options: {...},
+  options: {...}, // optional task-specific options
   commands: [
     {
       url: 'https://localhost/addressbook'
@@ -492,6 +502,29 @@ module.exports = {
 }
 ```
 
+The same tests will be run in a single browser window, if the Gruntfile contains just a single sub-task and the tests are specified by scenario files:
+
+```js
+'html-dom-snapshot': {
+  all: {
+    scenarios: 'test/scenarios/*.js'
+  }
+}
+```
+
+The directory "test/scenarios" would contain files  "addressbook.js", "calendar.js", "inbox.js" and "tasks.js", which would specify only the array of commands; not the entire sub-task objects. For example, the address book implementation:
+
+```js
+module.exports = {
+  {
+    options: {...}, // optional command-specific options
+    url: 'https://localhost/addressbook'
+    wait: '#addressbook.complete'
+  },
+  ...
+]
+```
+
 ### Loading
 
 Load the plugin in `Gruntfile.js`:
@@ -531,8 +564,8 @@ grunt.initConfig({
   },
 
   'html-dom-snapshot': { // Takes new snapshots.
-    'index': {
-      url: 'https://localhost:8881'
+    all: {
+      ...
     }
   },
 
@@ -606,6 +639,7 @@ your code using Grunt.
 
 ## Release History
 
+ * 2018-01-30  [v0.3.0]  Allow specifying test commands in separate modules
  * 2018-01-27  [v0.2.0]  Allow saving screenshots in addition to snapshots
  * 2017-11-18  [v0.1.0]  Allow separate navigation, page interaction and saving snapshots
  * 2017-11-12  [v0.0.1]  Initial release
@@ -637,6 +671,7 @@ Licensed under the MIT license.
 [grunt-reg-viz]: https://github.com/prantlf/grunt-reg-viz
 [grunt-selenium-standalone]: https://github.com/zs-zs/grunt-selenium-standalone
 [keyboard key identifiers]: https://w3c.github.io/webdriver/webdriver-spec.html#keyboard-actions
+[v0.3.0]: https://github.com/prantlf/grunt-html-dom-snapshot/releases/tag/v0.3.0
 [v0.2.0]: https://github.com/prantlf/grunt-html-dom-snapshot/releases/tag/v0.2.0
 [v0.1.0]: https://github.com/prantlf/grunt-html-dom-snapshot/releases/tag/v0.1.0
 [v0.0.1]: https://github.com/prantlf/grunt-html-dom-snapshot/releases/tag/v0.0.1

tasks/html-dom-snapshot.js

@@ -37,8 +37,15 @@ module.exports = function (grunt) {
           }),
           target = this.target,
           pages = data.pages,
-          snapshots = options.dest;
-    var lastViewport = options.viewport;
+          snapshots = options.dest,
+          client = webdriverio.remote({
+            desiredCapabilities: options.browserCapabilities
+          });
+    var lastViewport = options.viewport,
+        urlCount = 0,
+        snapshotCount = 0,
+        screenshotCount = 0,
+        commands;
     if (pages) {
       grunt.log.warn('The property "pages" is deprecated. ' +
                      'Use "commands" with the same content.');
@@ -49,29 +56,13 @@ module.exports = function (grunt) {
       options.snapshots = snapshots;
       delete options.dest;
     }
-    const commands = data.commands || pages || [
-            Object.assign({
-              file: target
-            }, data)
-          ],
-          client = webdriverio.remote({
-            desiredCapabilities: options.browserCapabilities
-          });
-    var urlCount = 0,
-        snapshotCount = 0,
-        screenshotCount = 0;
 
     grunt.verbose.writeln('Open web browser window for the target "' +
                           target + '".');
     client.init()
           .then(setViewportSize)
-          .then(function () {
-            return commands.reduce(function (promise, command) {
-              return promise.then(function () {
-                return performCommand(command);
-              });
-            }, Promise.resolve());
-          })
+          .then(gatherCommands)
+          .then(performCommands)
           .then(function () {
             grunt.log.ok(commands.length + ' ' +
                 grunt.util.pluralize(commands.length, 'command/commands') +
@@ -92,6 +83,43 @@ module.exports = function (grunt) {
           })
           .then(done);
 
+    function gatherCommands() {
+      let scenarios = data.scenarios;
+      commands = data.commands || pages;
+      if (scenarios) {
+        if (!Array.isArray(scenarios)) {
+          scenarios = [scenarios];
+        }
+        const currentDirectory = process.cwd();
+        commands = scenarios
+          .reduce(function (scenarios, scenario) {
+            return scenarios.concat(grunt.file.expand(scenario));
+          }, [])
+          .reduce(function (scenarios, scenario) {
+            grunt.verbose.writeln('Load scenario  "' + scenario + '".');
+            if (!path.isAbsolute(scenario)) {
+              scenario = path.join(currentDirectory, scenario);
+            }
+            return scenarios.concat(require(scenario));
+          }, commands || []);
+      }
+      if (!commands) {
+        commands = [
+          Object.assign({
+            file: target
+          }, data)
+        ];
+      }
+    }
+
+    function performCommands() {
+      return commands.reduce(function (promise, command) {
+        return promise.then(function () {
+          return performCommand(command);
+        });
+      }, Promise.resolve());
+    }
+
     function setViewportSize() {
       grunt.verbose.writeln('Resize viewport to ' + lastViewport.width +
                             'x' + lastViewport.height + '.');

test/pages/scenario1.html

@@ -0,0 +1,7 @@
+<!DOCTYPE html>
+<html>
+<head>
+<title>scenario1</title>
+</head>
+<body>scenario1</body>
+</html>

test/scenarios/scenario1.js

@@ -0,0 +1,8 @@
+'use strict';
+
+module.exports = [
+  {
+    url: 'http://localhost:8881/test/pages/scenario1.html',
+    file: 'scenario1'
+  }
+];

test/test.js

@@ -85,5 +85,11 @@ exports['html-dom-snapshot'] = {
     expected = original.replace('<body class="first">', '<body class="first second third">');
     test.equal(expected, third, 'dynamic-third.html');
     test.done();
+  },
+
+  'scenario1': function (test) {
+    const pages = readPages('scenario1.html');
+    test.equal(pages.expected, pages.actual, 'scenario1.html');
+    test.done();
   }
 };