testilo 15.2.2 → 16.0.1

package/README.md

@@ -257,7 +257,7 @@ Suppose you ask for a merger of the above batch and script, **without** the isol
 
 ```javaScript
 {
-  id: '7is3i-ts99-acme',
+  id: '231120T1550-ts99-acme',
   what: 'Axe on account page',
   strict: true,
   timeLimit: 60,
@@ -315,14 +315,14 @@ Suppose you ask for a merger of the above batch and script, **without** the isol
     requester: 'you@yourdomain.tld'
   },
   creationTime: '2023-11-20T15:50:27',
-  timeStamp: '7is3i'
+  timeStamp: '231120T1550'
 }
 ```
 
 Testilo has substituted the `private` acts from the `acme` target of the batch for the placeholder when creating the job. Testilo also has:
 - let the script determine the browser type of the `launch` act.
-- added a unique timestamp to the job.
 - added the creation time to the job.
+- added a unique timestamp to the job (a more compact representation of the creation time).
 - given the job an ID that combines the timestamp with the script ID and the batch ID.
 - inserted a `sources` property into the job, recording facts about the script, the batch, the target, and the email address given by the user who requested the merger.
 
@@ -360,24 +360,70 @@ A user can invoke `merge` in this way:
 
 - Create a script and save it as a JSON file in the `scripts` subdirectory of the `process.env.SPECDIR` directory.
 - Create a batch and save it as a JSON file in the `batches` subdirectory of the `process.env.SPECDIR` directory.
-- In the Testilo project directory, execute one of these statements:
-    - `node call merge s b e true`
-    - `node call merge s b e false`
-    - `node call merge s b e`
+- In the Testilo project directory, execute this statement:
+    - `node call merge s b e i t`
 
-In these statements, replace `s` and `b` with the base names of the script and batch files, respectively. For example, if the script file is named `ts99.json`, then replace `s` with `ts99`. Replace `e` with an email address, or with an empty string if the environment variable `process.env.REQUESTER` exists and you want to use it.
-
-The first statement will cause a merger **with** isolation.
-The second and third statements will cause a merger **without* isolation.
+In these statements, replace:
+- `s` with the base name of the script file
+- `b` with the base name of the batch file
+- `e` with an email address, or with an empty string if the environment variable `process.env.REQUESTER` exists and you want to use it
+- `i` with `true` if you want test isolation or `false` if not
+- `t` with `true` if the job is to be saved in the `todo` subdirectory or `false` if it is to be saved in the `pending` subdirectory of the `process.env.JOBDIR` directory.
 
 The `call` module will retrieve the named script and batch from their respective directories.
-The `merge` module will create an array of jobs.
-The `call` module will save the jobs as JSON files in the `todo` subdirectory of the `process.env.JOBDIR` directory.
+The `merge` module will create an array of jobs, with or without test isolation.
+The `call` module will save the jobs as JSON files in the `todo` or `pending` subdirectory of the `process.env.JOBDIR` directory.
 
 #### Validation
 
 To test the `merge` module, in the project directory you can execute the statement `node validation/merge/validate`. If `merge` is valid, all logging statements will begin with “Success” and none will begin with “ERROR”.
 
+### Series
+
+If you want to monitor a web resource by performing identical jobs repeatedly and comparing the results, you can use the `series` module to create a series of identical jobs.
+
+The jobs in a series differ from one another only in the timestamp segments of their `id` properties. For example, if the first job had the `id` value `240528T1316-mon-mozilla` and the events in the series occurred at intervals of 12 hours, then the second job would have the `id` value `240529T0116-mon-mozilla`.
+
+The `series` module adds a `sources.series` property to each job in the series. The value of that property is the `id` value of the first job in the series.
+
+To support monitoring, a server that receives job requests from testing agents can perform a time check on the first job in the queue. If the time specified by the `id` of the first job is in the future, the server can reply that there is no job to do.
+
+#### Invocation
+
+There are two ways to use the `series` module.
+
+##### By a module
+
+A module can invoke `series` in this way:
+
+```javaScript
+const {series} = require('testilo/series');
+const jobs = series(job, count, interval);
+```
+
+This invocation references a `job` variable, whose value is a job object. The `count` variable is an integer, 2 or greater, specifying how many events the series consists of. The `interval` variable is an integer, 1 or greater, specifying how many minutes are to elapse after each event before the next event. The `series()` function of the `series` module generates an array of job objects and returns the array. The invoking module can further dispose of the jobs as needed.
+
+##### By a user
+
+A user can invoke `series` in this way:
+
+- Create a job and save it as a JSON file in the `todo` subdirectory of the `process.env.JOBDIR` directory.
+- In the Testilo project directory, execute this statement:
+    - `node call series j c i`
+
+In this statement, replace:
+- `j` with a string that the filename of the starting job begins with
+- `c` with a count
+- `i` with an interval in minutes
+
+The `call` module will retrieve the first job that matches `j` from the `pending` subdirectory of the `process.env.JOBDIR` directory.
+The `series` module will create an array of jobs.
+The `call` module will save the jobs as JSON files in the `todo` subdirectory of the `process.env.JOBDIR` directory.
+
+#### Validation
+
+To test the `series` module, in the project directory you can execute the statement `node validation/series/validate`. If `series` is valid, all logging statements will begin with “Success” and none will begin with “ERROR”.
+
 ## Report scoring
 
 ### Introduction

package/call.js

@@ -24,6 +24,8 @@ const {batch} = require('./batch');
 const {script} = require('./script');
 // Function to process a merger.
 const {merge} = require('./merge');
+// Function to generate a job series.
+const {series} = require('./series');
 // Function to score reports.
 const {score} = require('./score');
 // Function to digest reports.
@@ -68,7 +70,7 @@ const callScript = async (scriptID, classificationID = null, ... issueIDs) => {
   console.log(`Script ${scriptID} created and saved in ${specDir}/scripts`);
 };
 // Fulfills a merging request.
-const callMerge = async (scriptID, batchID, requester, withIsolation = false) => {
+const callMerge = async (scriptID, batchID, requester, withIsolation, todo = true) => {
   // Get the script and the batch.
   const scriptJSON = await fs.readFile(`${specDir}/scripts/${scriptID}.json`, 'utf8');
   const script = JSON.parse(scriptJSON);
@@ -79,14 +81,38 @@ const callMerge = async (scriptID, batchID, requester, withIsolation = false) =>
   // Save the jobs.
   for (const job of jobs) {
     const jobJSON = JSON.stringify(job, null, 2);
-    await fs.writeFile(`${jobDir}/todo/${job.id}.json`, jobJSON);
+    const destination = todo ? 'todo' : 'pending';
+    await fs.writeFile(`${jobDir}/${destination}/${job.id}.json`, jobJSON);
   }
   const {timeStamp} = jobs[0];
   console.log(
-    `Script ${scriptID} and batch ${batchID} merged; jobs ${timeStamp}… saved in ${jobDir}/todo`
+    `Script ${scriptID} and batch ${batchID} merged as ${timeStamp}-… in ${jobDir}/${destination}`
   );
 };
-// Get selected reports.
+// Fulfills a series request.
+const callSeries = async (idStart, count, interval) => {
+  // Get the initial job.
+  const jobNames = await fs.readdir(`${jobDir}/pending`);
+  const seriesJobName = jobNames.find(jobName => jobName.startsWith(idStart));
+  // If it exists:
+  if (seriesJobName) {
+    // Generate a job series.
+    const jobJSON = await fs.readFile(`${jobDir}/todo/${seriesJobName}`, 'utf8');
+    const job = JSON.parse(jobJSON);
+    const jobSeries = series(job, Number.parseInt(count), Number.parseInt(interval));
+    // Save the jobs.
+    for (const item of jobSeries) {
+      await fs.writeFile(`${jobDir}/todo/${item.id}.json`, JSON.stringify(item, null, 2));
+    }
+    console.log(`Series of ${jobSeries.length} jobs generated and saved in ${jobDir}/todo`);
+  }
+  // Otherwise, i.e. if it does not exist:
+  else {
+    // Report this.
+    console.log('ERROR: No matching to-do job found');
+  }
+};
+// Gets selected reports.
 const getReports = async (type, selector = '') => {
   const allFileNames = await fs.readdir(`${reportDir}/${type}`);
   const reportIDs = allFileNames
@@ -215,6 +241,12 @@ else if (fn === 'merge' && fnArgs.length > 2 && fnArgs.length < 5) {
     console.log('Execution completed');
   });
 }
+else if (fn === 'series' && fnArgs.length === 3) {
+  callSeries(... fnArgs)
+  .then(() => {
+    console.log('Execution completed');
+  });
+}
 else if (fn === 'score' && fnArgs.length > 0 && fnArgs.length < 3) {
   callScore(... fnArgs)
   .then(() => {

package/merge.js

@@ -33,7 +33,8 @@ exports.merge = (script, batch, requester, isolate = false) => {
   // If the requester is unspecified, make it the standard requester.
   requester ||= stdRequester;
   // Create a timestamp.
-  const timeStamp = Math.floor((Date.now() - Date.UTC(2023, 6)) / 2000).toString(36);
+  const now = new Date();
+  const timeStamp = now.toISOString().slice(2, 16).replace(/[-:]/g, '');
   // Create a time description.
   const creationTime = (new Date()).toISOString().slice(0, 19);
   // Initialize a target-independent job.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testilo",
-  "version": "15.2.2",
+  "version": "16.0.1",
   "description": "Prepares and processes Testaro reports",
   "main": "aim.js",
   "scripts": {

package/series.js

@@ -0,0 +1,72 @@
+/*
+  series.js
+  Generates a series of Testaro jobs.
+  Arguments:
+    0. Initial job.
+    1. Job count.
+    2. Time interval in minutes.
+*/
+
+// ########## FUNCTIONS
+
+// Scores the specified raw reports.
+exports.series = (job, count, interval) => {
+  // If the arguments are valid:
+  if (
+    typeof job === 'object'
+    && count
+    && typeof count === 'number'
+    && count === Math.floor(count)
+    && count > 1
+    && interval
+    && typeof interval === 'number'
+    && interval === Math.floor(interval)
+    && interval > 0
+  ) {
+    // Get a copy of the initial job.
+    const template = JSON.parse(JSON.stringify(job));
+    // If it has an ID:
+    const jobID = template.id;
+    if (jobID) {
+      // If the ID specifies a valid time:
+      const s = jobID.slice(0, 11);
+      const dateSpec = `20${s[0]}${s[1]}-${s[2]}${s[3]}-${s[4]}${s[5]}`;
+      const timeSpec = `${s[7]}${s[8]}:${s[9]}${s[10]}`;
+      const dateTimeSpec = `${dateSpec}T${timeSpec}Z`;
+      const start = new Date(dateTimeSpec);
+      const startNum = start.valueOf();
+      if (startNum) {
+        // Initialize the series.
+        const series = [];
+        // For each job required:
+        for (let i = 0; i < count; i++) {
+          // Create it.
+          const nextJob = JSON.parse(JSON.stringify(template));
+          nextJob.sources.series = nextJob.id;
+          // Revise its ID.
+          const nextDate = new Date(startNum + i * interval * 60000);
+          const nextTimeStamp = nextDate.toISOString().slice(2, 16).replace(/[-:]/g, '');
+          nextJob.id = nextJob.id.replace(/^[^-]+/, nextTimeStamp);
+          // Add the job to the series.
+          series.push(nextJob);
+        }
+        return series;
+      }
+      // Otherwise, i.e. if it does not specify a valid time:
+      else {
+        // Report this.
+        console.log('ERROR: Initial job ID starts with an invalid time specification');
+      }
+    }
+    // Otherwise, i.e. if it has no ID:
+    else {
+      // Report this.
+      console.log('ERROR: Initial job has no ID');
+    }
+  }
+  // Otherwise, i.e. if they are invalid:
+  else {
+    // Report this.
+    console.log('ERROR: Arguments invalid');
+  }
+};

package/validation/series/job.json

@@ -0,0 +1,44 @@
+{
+  "id": "240223T0815-mon-example",
+  "what": "Job for series validation",
+  "strict": true,
+  "timeLimit": 10,
+  "acts": [
+    {
+      "type": "launch",
+      "which": "chromium",
+      "what": "Chromium browser",
+      "startTime": 1662474496075,
+      "endTime": 1662474496453
+    },
+    {
+      "type": "url",
+      "which": "https://example.com",
+      "what": "Example of web page",
+      "startTime": 1662474496453,
+      "result": "https://example.com",
+      "endTime": 1662474501684
+    },
+    {
+      "type": "test",
+      "which": "testaro",
+      "url": "https://example.com",
+      "withItems": false,
+      "rules": [
+        "y",
+        "bulk"
+      ]
+    }
+  ],
+  "sources": {
+    "script": "mon",
+    "batch": "target",
+    "target": {
+      "id": "example",
+      "what": "Example of web page"
+    },
+    "requester": "user@domain.tld"
+  },
+  "creationTime": "2023-11-20T15:50:27",
+  "timeStamp": "240223T0815"
+}

package/validation/series/validate.js

@@ -0,0 +1,78 @@
+/*
+  validate.js
+  Validates series module.
+*/
+
+// ########## IMPORTS
+
+// Function to process files.
+const fs = require('fs/promises');
+// Function to generate a job series.
+const {series} = require('../../series');
+
+// ########## FUNCTIONS
+
+// Validates the series module.
+const validate = async () => {
+  // Get the job.
+  const jobJSON = await fs.readFile(`${__dirname}/job.json`, 'utf8');
+  const job = JSON.parse(jobJSON);
+  // Generate the series.
+  const jobs = series(job, 3, 5);
+  // Validate the series.
+  if (Array.isArray(jobs) && jobs.length === 3) {
+    console.log('Success: The count of jobs is correct');
+  }
+  else {
+    console.log('ERROR: The jobs are not an array of length 3');
+    return;
+  }
+  const job0 = jobs[0];
+  if (
+    job.id
+    && job.id === '240223T0815-mon-example'
+    && job0.id === job.id
+    && job0.sources
+    && job0.sources.series
+    && job0.sources.series === job.id
+  ) {
+    console.log('Success: The first job has the correct id and sources.series');
+  }
+  else {
+    console.log('ERROR: The first job has an incorrect id or sources.series');
+    return;
+  }
+  const job1 = jobs[1];
+  const job2 = jobs[2];
+  if (
+    job2.id
+    && job2.id === '240223T0825-mon-example'
+    && job2.sources
+    && job2.sources.series
+    && job2.sources.series === '240223T0815-mon-example'
+  ) {
+    console.log('Success: The third job has the correct id and sources.series');
+  }
+  else {
+    console.log('ERROR: The first job has an incorrect id or sources.series');
+    return;
+  }
+  if (
+    job1.acts
+    && job1.acts.length === 3
+    && job1.acts[2].rules
+    && job1.acts[2].rules.length === 2
+    && job2.acts
+    && job2.acts.length === 3
+    && job2.acts[2].rules
+    && job2.acts[2].rules.length === 2
+    && job2.acts[2].rules[1] === job1.acts[2].rules[1]
+  ) {
+    console.log('Success: The second and third jobs invoke the same rule');
+  }
+  else {
+    console.log('ERROR: The second and third job do not invoke the same rule');
+    return;
+  }
+};
+validate();