testilo 4.0.0 → 4.0.2

package/README.md

@@ -3,10 +3,12 @@ Utilities for Testaro
 
 ## Introduction
 
-The Testilo package contains utilities that facilitate the use of the [Testaro package](https://www.npmjs.com/package/testaro).
+The Testilo package contains utilities that facilitate the use of the [Testaro](https://www.npmjs.com/package/testaro) package.
 
 Testaro performs digital accessibility tests on web artifacts and creates reports in JSON format. The utilities in Testilo prepare jobs for Testaro to run and create additional value from the reports that Testaro produces.
 
+Because Testilo supports Testaro, this `README` file presumes that you have access to the Testaro `README` file and therefore does not repeat information provided there.
+
 ## Dependencies
 
 The `dotenv` dependency lets you set environment variables in an untracked `.env` file. This prevents secret data, such as passwords, from being shared as part of this package.
@@ -25,23 +27,9 @@ The reason for Testilo being an independent package, rather than part of Testaro
 
 ### `merge`
 
-Testaro runs _jobs_. A job gives Testaro instructions.
-
-Sometimes you may want Testaro to perform a set of tests on multiple targets. The `merge` utility in Testilo facilitates this. It creates Testaro jobs out of a _script_ and a _batch_.
-
-A script tells Testaro where to go and what to do. If the where-to-go part identifies a specific URL, the script can be a job, ready for Testaro to run. But the where-to-go part can also be generic, such as `http://*.*`. Then the script needs to be converted to a job by having its generic destination replaced with a specific URL. A batch is a list of _hosts_ (URLs and metadata). Merging a batch and a script means generating from the script as many jobs as there are hosts in the batch. In each job, one host from the batch becomes the specific target.
-
-A script is a JSON file representing a `script` object, which contains a sequence of _commands_. Scripts are documented in detail in the Testaro `README.md` file.
-
-A batch is a JSON file representing a `batch` object, which contains an array of _hosts_. Each host is an object with three properties:
-- `id`: a string unique in the batch
-- `which`: a URL
-- `what`: a string naming the entity associated with the URL
+The `merge` utility is useful when you want Testaro to perform the same set of operations on multiple hosts. For example, you may want the same tests run on multiple web pages. You would have a single script, and you would want multiple jobs created from it. Each job would target one host, and, for that purpose, any `url` command in the script would be modified so that its properties are those of that host. The `merge` utility (similar to mail merge in office applications) does this. It creates Testaro jobs out of a script and a _batch_.
 
-The batch as a whole also has three properties:
-- `id`: a string composed of ASCII letters and digits
-- `what`: a string describing the batch
-- `hosts`: an array of host objects
+A batch is a JSON-format file representing a `batch` object, which contains an array of _hosts_.
 
 Here is an example of a batch:
 
@@ -83,7 +71,7 @@ Suppose that:
 - There is a script file named `testall.json`.
 - The above batch example is in a file named `usFedExec1.json`.
 
-The statement `node merge testall usFedExec1 allFedExec` would tell Testilo to merge the batch `../testing/batches/usFedExec1.json` and the script `../testing/scripts/testall.json` and write the two job files in `../testing/jobs/allFedExec`.
+The statement `node merge testall usFedExec1 allFedExec` would tell Testilo to merge the batch `../testing/batches/usFedExec1.json` and the script `../testing/scripts/testall.json` into two job files and save those files in the directory `../testing/jobs/allFedExec`. Testilo will create any directories necessary to save the files there.
 
 ### `score`
 

package/merge.js

@@ -1,12 +1,11 @@
 /*
   merge.js
-  Merges a batch and a script to produce jobs.
+  Merges a batch and a script to produce host-specific scripts.
   Arguments:
     0. base of name of script located in process.env.SCRIPTDIR.
     1. base of name of batch located in process.env.BATCHDIR.
-    2. name of subdirectory of process.env.JOBDIR into which to write host scripts.
   Usage example:
-    node merge tp18 weborgs tp18-weborgs-1
+    node merge tp18 weborgs
   Note: The subdirectory for host scripts will be created if it does not exist.
 */
 
@@ -21,40 +20,44 @@ const fs = require('fs/promises');
 
 const scriptDir = process.env.SCRIPTDIR || 'scripts';
 const batchDir = process.env.BATCHDIR || 'batches';
-const jobDir = process.env.JOBDIR || 'jobs';
+const watchDir = process.env.WATCHDIR || 'watch';
 const scriptName = process.argv[2];
 const batchName = process.argv[3];
-const jobSubdir = process.argv[4];
 
 // ########## FUNCTIONS
 
-// Merges a batch into a script and writes host scripts.
-const merge = async (script, batch, timeStamp, outDir) => {
-  await fs.mkdir(outDir, {recursive: true});
-  const {hosts} = batch;
+// Merges a batch into a script and writes host-specific scripts.
+const merge = async (script, batch) => {
+  // Create the watch directory if it does not exist.
+  await fs.mkdir(watchDir, {recursive: true});
   // For each host in the batch:
-  const jobs = hosts.map(host => {
+  const {hosts} = batch;
+  const newScripts = hosts.map(host => {
     // Copy the script.
     const newScript = JSON.parse(JSON.stringify(script));
     // In the copy, make all url commands visit the host.
     newScript.commands.forEach(command => {
       if (command.type === 'url') {
+        command.id = host.id;
         command.which = host.which;
         command.what = host.what;
       }
     });
-    // Create a host script.
-    return {
-      id: `${timeStamp}-${host.id}`,
-      host,
-      script: newScript
-    };
+    // Add source information to the script.
+    newScript.sources = {
+      script: script.id,
+      batch: batch.id
+    }
+    // Change the script id property to include the host ID.
+    newScript.id += `-${host.id}`;
+    // Return the host-specific script.
+    return newScript;
   });
-  // Write the host scripts.
-  for (const job of jobs) {
-    await fs.writeFile(`${outDir}/${job.id}.json`, JSON.stringify(job, null, 2));
+  // Write the host-specific scripts.
+  for (const newScript of newScripts) {
+    await fs.writeFile(`${watchDir}/${newScript.id}.json`, JSON.stringify(newScript, null, 2));
   };
-  console.log(`Merger completed. Count of jobs created: ${hosts.length}`);
+  console.log(`Merger completed. Count of scripts created: ${hosts.length}`);
 };
 
 // ########## OPERATION
@@ -65,8 +68,6 @@ fs.readFile(`${scriptDir}/${scriptName}.json`, 'utf8')
   .then(async batchFile => {
     const script = JSON.parse(scriptFile);
     const batch = JSON.parse(batchFile);
-    const timeStamp = Math.floor((Date.now() - Date.UTC(2022, 1)) / 2000).toString(36);
-    const outDir = `${jobDir}/${jobSubdir}`;
-    await merge(script, batch, timeStamp, outDir);
+    await merge(script, batch);
   });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testilo",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "Client that scores and digests Testaro reports",
   "main": "index.js",
   "scripts": {