testilo 7.1.1 → 9.0.0

package/README.md

@@ -5,17 +5,23 @@ Utilities for 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.
+Testaro performs digital accessibility tests on web artifacts and creates reports in JSON format. The utilities in Testilo fall into two categories:
+- Job preparation
+- Report enhancement
 
 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.
 
 ## Branches
 
-The `writer` branch contains the state of Testilo as of 2022-11-07. In that branch, Testilo must read and write files when it aims, scores, or digests. That makes Testilo unusable as a dependency in applications that do not have permission to both read and write files.
+The `writer` branch contains the state of Testilo as of 2022-11-07. In that branch, Testilo must read and write files. That makes Testilo unusable as a dependency in applications that do not have permission to both read and write files.
 
-The `main` branch contains the state of Testilo starting on 2022-11-07. In that branch, Testilo does not need to read or write files when it aims, scores, or digests, so applications without write permission can still use Testilo as a dependency if they need only those functionalities.
+The `simple` branch contains the state of Testilo as of 2022-12-23. In that branch, Testilo does not need to read or write files, so applications without write permission can still use Testilo as a dependency.
 
-This `README.md` file documents the `main` branch.
+The `main` branch contains the state of Testilo from 2022-12-24 until now. In that branch, Testilo can prepare jobs that require multi-step operations to reach and pre-process the targets being tested.
+
+The `complexmerge` branch refactors `main` and is to be merged into `main` when the refactoring is complete.
+
+This `README.md` file documents the `complexmerge` branch and will document the `main` branch when `complexmerge` is merged into `main`.
 
 ## Dependencies
 
@@ -27,242 +33,428 @@ When Testilo is a dependency of another application, the `.env` file is not impo
 
 Testilo is written in Node.js. Commands are given to Testilo in a command-line (terminal) interface or programmatically.
 
-Shared routines that perform scoring, digesting, and comparing are _procs_ and are located in the `procs` directory.
+Shared routines are _procs_ and are located in the `procs` directory.
 
 Testilo can be installed wherever Node.js (version 14 or later) is installed. This can be a server or the same workstation on which Testaro is installed.
 
-The reason for Testilo being an independent package, rather than part of Testaro, is that Testilo can be installed on any host, while Testaro can run successfully only on a Windows or Macintosh workstation (and perhaps on some workstations with Ubuntu operating systems). Testaro runs tests similar to those that a human accessibility tester would run, using whatever browsers, input devices, system settings, simulated and attached devices, and assistive technologies tests may require. Thus, Testaro is limited to functionalities that require workstation attributes. For maximum flexibility in the management of Testaro jobs, all other functionalities are located outside of Testaro. You could have software such as Testilo running on a server, communicating with multiple workstations running Testaro, receiving job orders from the server and returning job results to the server for further processing.
+The reason for Testilo being an independent package, rather than part of Testaro, is that Testilo can be installed on any host, while Testaro can run successfully only on a Windows or Macintosh workstation (and perhaps on some workstations with Ubuntu operating systems). Testaro runs tests similar to those that a human accessibility tester would run, using whatever browsers, input devices, system settings, simulated and attached devices, and assistive technologies tests may require. Thus, Testaro is limited to functionalities that require workstation attributes. For maximum flexibility in the management of Testaro jobs, all other functionalities are located outside of Testaro. You could have software such as Testilo running on a server, communicating with multiple workstations running Testaro. The workstations could receive job orders from the server and return job results to the server for further processing.
 
-## Utilities
+## Job preparation
 
-### `aim`
+### Introduction
 
-The `aim` function allows you to _aim_ a script at a host. That means modifying the script so that it performs its operations on the specified host. The modifications are:
-- Modify the value of the `id` property of the script by:
-   - Prefixing the value with a time stamp.
-   - Suffixing the value with the value of the `id` property of the host.
-- Modify each `url` command of the script by changing the values of its `which`, `what`, and `id` properties to the values of those properties of the host.
-- Add a `source` property to the script, identifying the script, the host, and the requester.
+Testaro executes _jobs_. In a job, Testaro performs _acts_ (tests and other operations) on _targets_ (typically, web pages). The Testaro `README.md` file specifies the requirements for a job.
 
-Execution by a module:
+You can create a job for Testaro directly, without using Testilo.
 
-```javaScript
-const aimScript = async () => {
-  const fs = require('fs/promises');
-  const host = {
-    which: https://w3c.org/,
-    what: 'World Wide Web Consortium',
-    id: w3c
-  };
-  const {aim} = require('testilo/aim');
-  const scriptJSON = await fs.readFile(`${process.env.SCRIPTDIR}/ts25.json`, 'utf8');
-  const script = JSON.parse(scriptJSON);
-  const aimedScript = aim(script, host, 'developer@w3c.org');
-  await fs.writeFile(
-    `${process.env.JOBDIR}/${aimedScript.id}.json`, JSON.stringify(aimedScript, null, 2)
-  );
-  console.log(`Script ${aimedScript.source.script} aimed at ${aimedScript.host.what}`);
-}
-aimScript();
-```
+Testilo can, however, make job preparation more efficient in two scenarios:
+- A common use case is to define a battery of tests and to have those tests performed on multiple targets. In that case, you need to create multiple jobs, one per page. The jobs are identical, except for the target-specific acts (including navigating to targets). If you tell Testilo about the tests and the targets, Testilo can create such collections of jobs for you.
+- Some tests operate on a copy of a target and modify that copy. Usually, one wants test isolation: The results of a test do not depend on any previously performed tests. To ensure test isolation, a job containing such target-modifying tests must follow them with acts that restore the target to its desired pre-test state. Testilo can insert the required target-restoring acts into each job after target-modifying tests.
 
-Execution by a user:
+The `merge` module performs these services.
 
-```bash
-node call aim ts25 https://w3.org/ 'World Wide Web Consortium' w3c developer@w3c.org
-```
+### Procedure
 
-In these examples, a copy of the script file named `ts25.json` in the `SCRIPTDIR` directory is aimed at the World Wide Web Consortium and then saved in the `JOBDIR` directory.
+To use the `merge` module, you need to create a _script_ and a _batch_:
+- The script is an object that specifies a job, except for the targets.
+- The batch is an object that specifies target-specific acts for targets.
 
-The `aim` function neither reads nor writes files. Its arguments are a script object, a host object, and a requester-email-address string, and it returns a job object, aimed at the host.
+The script contains an array of acts, with placeholders. For each target in the batch, the `merge` module creates a job, in which the placeholders are replaced with the acts specific to that target in the batch.
 
-### `merge`
+### Example
 
-The `merge` function is similar to the `aim` function, but it aims a script at multiple hosts, not only one. The hosts are identified in a _batch_, a file in the `BATCHDIR` directory. The output of `merge` is multiple script files, one per host, saved in the `JOBDIR` directory.
+Here is an example illustrating how merging works.
 
-A batch is a JSON-format file representing a `batch` object, which contains an array of _hosts_.
+#### Script
 
-Here is an example of a batch:
+Suppose you have created this script:
 
-```json
+```javaScript
 {
-  "id": "usFedExec1",
-  "what": "United States federal executive agencies",
-  "hosts": [
+  id: 'ts25',
+  what: 'Motion, Axe, and bulk',
+  strict: true,
+  timeLimit: 60,
+  acts: [
+    {
+      type: 'placeholder',
+      which: 'main',
+      launch: 'webkit'
+    },
+    {
+      type: 'test',
+      which: 'motion',
+      what: 'spontaneous change of content; requires webkit',
+      delay: 2500,
+      interval: 2500,
+      count: 5
+    },
     {
-      "id": "achp",
-      "which": "https://www.achp.gov/",
-      "what": "Advisory Council on Historic Preservation (ACHP)"
+      type: 'placeholder',
+      which: 'main',
+      launch: 'chromium'
     },
     {
-      "id": "agm",
-      "which": "https://www.usagm.gov/",
-      "what": "Agency for Global Media"
+      type: 'test',
+      which: 'axe',
+      withItems: true,
+      rules: [],
+      what: 'Axe core, all rules, with details'
+    },
+    {
+      type: 'test',
+      which: 'bulk',
+      what: 'count of visible elements'
     }
   ]
 }
 ```
 
-Execution by a module:
+The `acts` array of this script contains tree regular acts and two placeholders.
 
-```javaScript
-const {merge} = require('testilo/merge');
-merge('ts25', 'weborgs', 'developer@w3.org')
-.then(() => {
-  console.log('Merger complete');
-});
-```
+#### Batch
 
-Execution by a user:
+Suppose you have also created this batch:
 
-```bash
-node call merge ts25 weborgs developer@w3.org
+```javaScript
+{
+  id: 'weborgs',
+  what: 'Web standards organizations',
+  targets: [
+    {
+      id: 'mozilla',
+      what: 'Mozilla Foundation',
+      acts: {
+        main: [
+          {
+            type: 'launch'
+          },
+          {
+            type: 'url',
+            which: 'https://foundation.mozilla.org/en/',
+            what: 'Mozilla Foundation'
+          }
+        ]
+      }
+    },
+    {
+      id: 'w3c',
+      what: 'World Wide Web Consortium',
+      acts: {
+        main: [
+          {
+            type: 'launch'
+          },
+          {
+            type: 'url',
+            which: 'https://www.w3.org/',
+            what: 'World Wide Web Consortium'
+          }
+        ]
+      }
+    }
+  ]
+}
 ```
 
-In these examples, a copy of the script file named `ts25.json` in the `SCRIPTDIR` directory is aimed at all the hosts in the batch file named `weborgs.json` in the `BATCHDIR` directory, and the resulting jobs are saved in the `JOBDIR` directory. Each job has a `sources` property that identifies an email address to be notified after the job has been run.
+This batch defines two targets.
 
-### `score`
+#### Isolation option
 
-Testaro performs tests and produces reports of test results. Testilo can add scores to those reports. In this way, each report can not only detail successes and failures of individual tests but also assign scores to those results and combine the partial scores into total scores.
+The `merge` module offers an isolation option. If you exercise it, the `merge` module will act as if the latest placeholder were again inserted after each target-modifying test, except where that test is the last act or the next act after it is a placeholder.
 
-The `score` function performs scoring. It depends on a _score proc_ to define the scoring rules. Some score procs are in the Testilo package (in the `procs/score` directory), and you can create more score procs to implement different rules.
+#### Output
 
-Execution by a module:
+Suppose you ask for a merger of the above batch and script, **without** the isolation option. Then the first job produced by `merge` could be:
 
 ```javaScript
-const scoreReport = async (scoreProcID, rawReportID) => {
-  const fs = require('fs/promises');
-  const {score} = require('testilo/score');
-  const {scorer} = require(`${process.env.SCOREPROCDIR}/${scoreProcID}`);
-  const rawReportJSON = await fs.readFile(
-    `${process.env.REPORTDIR_RAW}/${rawReportID}.json`, 'utf8'
-  );
-  const rawReport = JSON.parse(rawReportJSON);
-  const scoredReport = score(scorer, rawReport);
-  await fs.writeFile(
-    `${process.env.REPORTDIR_SCORED}/${scoredReport.id}.json`, JSON.stringify(scoredReport, null, 2)
-  );
-  console.log(`Report ${scoredReport.id} scored`);
-};
-scoreReport('sp25a', '756mr-ts25-w3c');
+{
+  id: '7izc1-ts25-mozilla',
+  what: 'Motion, Axe, and bulk',
+  strict: true,
+  timeLimit: 60,
+  acts: [
+    {
+      type: 'launch',
+      which: 'webkit'
+    },
+    {
+      type: 'url',
+      which: 'https://foundation.mozilla.org/en/',
+      what: 'Mozilla Foundation'
+    }
+    {
+      type: 'test',
+      which: 'motion',
+      what: 'spontaneous change of content; requires webkit',
+      delay: 2500,
+      interval: 2500,
+      count: 5
+    },
+    {
+      type: 'launch',
+      which: 'chromium'
+    },
+    {
+      type: 'url',
+      which: 'https://foundation.mozilla.org/en/',
+      what: 'Mozilla Foundation'
+    }
+    {
+      type: 'test',
+      which: 'axe',
+      withItems: true,
+      rules: [],
+      what: 'Axe core, all rules, with details'
+    },
+    {
+      type: 'test',
+      which: 'bulk',
+      what: 'count of visible elements'
+    }
+  ],
+  sources: {
+    script: 'ts25',
+    batch: 'weborgs',
+    target: {
+      id: 'mozilla',
+      what: 'Mozilla Foundation'
+    },
+    requester: 'you@yourdomain.tld'
+  },
+  creationTime: '2023-11-20T15:50:27',
+  timeStamp: 'bizc1'
+}
 ```
 
-Execution by a user:
+Most of the properties of this job object come from your script and your batch. The acts of type `placeholder` in the script have been replaced with the specified (i.e. `main`) array of acts of the first target of the batch. In this case, that target has only one array of acts, and that array contains two acts, but a target could have multiple act arrays with distinct names, and an act array could include any number of acts or be empty.
 
-```bash
-node call score sp25a
-node call score sp25a 756mr
-```
+If the named array of acts includes an act of type `launch`, that act gets a `which` property, identical to the value of the `launch` property of the `placeholder` object. In this way, a placeholder can dictate which browser type is to be launched.
 
-In these examples, the `score` function applies a score proc named `sp25a`, of which a copy is in the file `sp25a.json` in the `SCOREPROCDIR` directory, to a raw report `756mr-ts25-w3c.json` in the `REPORTDIR_RAW` directory and returns the same report with score data added. The scored report is saved in the `REPORTDIR_SCORED` directory.
+The `merge` module has added other properties to the job:
+- a creation time
+- a timestamp, derived from the creation time
+- a job ID, composed of the timestamp, the script ID, and the target ID
+- a `sources` property, identifying the script, the batch, the target within the batch, and an email address obtained from the environment variable `process.env.REQUESTER`.
 
-The user statement can pass only 2 arguments to `call` if the first report in the `REPORTDIR_RAW` directory is the desired raw report. If there are multiple reports in that directory and the desired one is not the first, the user must pass 3 arguments to `call`, and the third argument must be a string, such that the first report in that directory that begins with that string is the desired report.
+This job is ready to be executed by Testaro.
 
-The `score` function neither reads nor writes files. Its arguments are a score-proc string and a raw-report object, and it returns a scored-report object.
+If, however, you requested a merger **with** isolation, then `merge` would act as if another instance of
 
-### `multiScore`
+    ```javaScript
+    {
+      type: 'placeholder',
+      which: 'main',
+      launch: 'chromium'
+    },
+    ```
+
+were located in the script after the `axe` test, because the `axe` test is target-modifying and could therefore change the result of the `bulk` test that follows it. So, additional acts of type `launch` and `url` would appear after the `axe` test in the job.
+
+### Invocation
 
-The `multiScore` function scores all the reports in the `REPORTDIR_RAW` directory and writes the scored reports in the `REPORTDIR_SCORED` directory.
+There are two ways to use the `merge` module.
 
-Execution by a module:
+#### By a module
+
+A module can invoke `merge` in this way:
 
 ```javaScript
-const {multiScore} = require('testilo/multiScore');
-multiScore('sp25a')
-.then(hostCount => {
-  console.log(`Scoring complete. Count of reports scored: ${hostCount}`);
-});
+const {merge} = require('testilo/merge');
+const jobs = merge(script, batch, requester, true);
 ```
 
-Execution by a user:
+This invocation references `script`, `batch`, and `requester` variables that the module must have already defined. The `script` and `batch` variables are a script object and a batch object, respectively. The `requester` variable is an email address. The fourth argument is a boolean, specifying whether to perform isolation; a missing fourth argument is equivalent to `false`. The `merge()` function of the `merge` module generates jobs and returns them in an array. The invoking module can further dispose of the jobs as needed.
 
-```bash
-node call multiScore sp25a
-```
+#### By a user
+
+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 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 `ts25.json`, then replace `x` with `ts25`. 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.
 
-The argument to `multiScore` names the score proc to be used. The `multiScore` function scores all the reports in the `REPORTDIR_RAW` directory and writes the scored reports in the `REPORTDIR_SCORED` 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 in the `todo` subdirectory of the `process.env.JOBDIR` directory.
 
-### `digest`
+### Validation
 
-Testaro reports, both originally and after they are scored, are JavaScript objects. When represented as JSON, they are human-readable, but basically designed for machine tractability.
+To test the `merge` module, in the project directory you can execute the statement `node validation/merge/validate`. All logging statements should begin with “Success” and none should begin with “ERROR”.
 
-The `digest` function converts scored reports into HTML documents with explanatory content. Thus, it converts machine-oriented reports into human-oriented reports, called _digests_. It depends on a _digest proc_ to define the digesting rules. Some digest procs are in the Testilo package (in the `procs/digest` directory), and you can create more digest procs to implement different rules.
+## Report scoring
 
-Execution by a module:
+### Introduction
+
+Testaro executes jobs and produces reports of test results. A report is identical to a job (see the example above), except that:
+- The acts contain additional data recorded by Testaro to describe the results of the performance of the acts. Acts of type `test` have additional data describing test results (successes, failures, and details).
+- Testaro also adds a `jobData` property, describing information not specific to any particular act.
+
+Thus, a report produced by Testaro contains these properties:
+- `id`
+- `what`
+- `strict`
+- `timeLimit`
+- `acts`
+- `sources`
+- `creationTime`
+- `timeStamp`
+- `jobData`
+
+Testilo can add scores to a report. In this way, a report can not only detail successes and failures of individual tests but also assign scores to those results and combine the partial scores into total scores. The scores are contained in a new `score` property that Testilo adds to a report.
+
+The `score` module scores a report. Its `score()` function takes two arguments:
+- a scoring function
+- an array of report objects
+
+A scoring function defines scoring rules. The Testilo package contains a `procs/score` directory, in which there are modules that export scoring functions. You can use one of those scoring functions, or you can create your own.
+
+### Invocation
+
+There are two ways to use the `score` module.
+
+#### By a module
+
+A module can invoke `score` in this way:
 
 ```javaScript
-const digestReport = async (digestProcID, scoredReportID) => {
-  const fs = require('fs/promises');
-  const {digest} = require('testilo/digest');
-  const {makeQuery} = require(`${process.env.DIGESTPROCDIR}/${digestProcID}/index`);
-  const digestTemplate = await fs.readFile(
-    `${process.env.DIGESTPROCDIR}/${digestProcID}/index.html`
-  );
-  const digestedReport = digest(digestTemplate, makeQuery, scoredReport);
-  const digestedReport = digest(makeQuery, scoredReport);
-  await fs.writeFile(`${process.env.REPORTDIR_DIGESTED}/${digestedReport.id}.html`, digestedReport);
-  console.log(`Report ${digestedReport.id} digested`);
-};
-digestReport('dp25a', '756mr-ts25-w3c');
+const {score} = require('testilo/score');
+const {scorer} = require('testilo/procs/score/sp25a');
+const scoredReports = score(scorer, rawReports);
 ```
 
-Execution by a user:
+The first argument to `score()` is a scoring function. In this example, it has been obtained from a JSON file in the Testilo package, but it could be a custom function. The second argument to `score()` is an array of report objects.
+
+#### By a user
+
+A user can invoke `score` in this way:
 
 ```bash
-node call digest dp25a
-node call digest dp25a 756mr
+node call score sp25a
+node call score sp25a 75
 ```
 
-In these examples, the `digest` function applies a digest proc named `dp25a`, of which a copy is in the file `dp25a.json` in the `DIGESTPROCDIR` directory, to a scored report `756mr-ts25-w3c.json` in the `REPORTDIR_SCORED` directory and returns an HTML digest for that same report. The digest is saved in the `REPORTDIR_DIGESTED` directory.
+When a user invokes `score` in this example, the `call` module:
+- gets the scoring module `sp25a` from its JSON file `sp25a.json` in the `process.env.SCOREPROCDIR` directory
+- gets the reports from the r`raw` subdirectory of the `process.env.REPORTDIR` directory
+- writes the scored reports to the `scored` subdirectory of the `process.env.REPORTDIR` directory
+
+The optional third argument to call (`75` in this example) is a report selector. Without the argument, `call` gets all the reports in the `raw` subdirectory. With the argument, `call` gets only those reports whose names begin with the argument string.
+
+### Validation
+
+To test the `score` module, in the project directory you can execute the statement `node validation/score/validate`. All logging statements should begin with “Success” and none should begin with “ERROR”.
+
+## Report digesting
+
+### Introduction
 
-The user statement can pass only 2 arguments to `call` if the first report in the `REPORTDIR_SCORED` directory is the desired scored report. If there are multiple reports in that directory and the desired one is not the first, the user must pass 3 arguments to `call`, and the third argument must be a string, such that the first report in that directory that begins with that string is the desired report.
+Reports created by Testaro, both originally and after they are scored, are JavaScript objects. When represented as JSON, they are human-readable, but not human-friendly. They are basically designed for machine tractability. Testilo can _digest_ a scored report, converting it to a human-oriented HTML document, or _digest_.
 
-The `digest` function neither reads nor writes files. Its arguments are a digest-proc string and a scored-report object, and it returns a digest HTML string.
+The `digest` module digests a scored report. Its `digest()` function takes three arguments:
+- a digest template
+- a digesting function
+- an array of report objects
 
-### `multiDigest`
+The digest template is an HTML document containing placeholders. A copy of the template, with its placeholders replaced by texts, becomes the digest. The digesting function defines the rules for replacing the placeholders with texts. The Testilo package contains a `procs/digest` directory, in which there are subdirectories containing pairs of templates and modules that export digesting functions. You can use one of those pairs, or you can create your own.
 
-The `multiDigest` function digests all the reports in the `REPORTDIR_SCORED` directory and writes the digests in the `REPORTDIR_DIGESTED` directory.
+### Invocation
 
-Execution by a module:
+There are two ways to use the `digest` module.
+
+#### By a module
+
+A module can invoke `digest` in this way:
 
 ```javaScript
-const {multiDigest} = require('testilo/multiDigest');
-multiDigest('dp25a')
-.then(hostCount => {
-  console.log(`Digesting complete. Count of reports digested: ${hostCount}`);
+const {digest} = require('testilo/digest');
+const digesterDir = `${process.env.FUNCTIONDIR}/digest/dp25a`;
+fs.readFile(`${digesterDir}/index.html`)
+.then(template => {
+  const {digester} = require(`${digesterDir}/index`);
+  const digestedReports = digest(template, digester, scoredReports);
 });
 ```
 
-Execution by a user:
+The first two arguments to `digest()` are a digest template and a digesting function. In this example, they have been obtained from files in the Testilo package, but they could be custom-made. The third argument to `digest()` is an array of report objects.
+
+#### By a user
+
+A user can invoke `digest` in this way:
 
 ```bash
-node call multiDigest dp25a
+node call digest dp25a
+node call digest dp25a 75
 ```
 
-The argument to `multiDigest` or the second argument to `call` names the digest proc to be used. The `multiDigest` function digests all the reports in the `REPORTDIR_SCORED` directory and writes the digests in the `REPORTDIR_DIGESTED` directory.
+When a user invokes `digest` in this example, the `call` module:
+- gets the template and the digesting module from subdirectory `dp25a` in the `digest` subdirectory of the `process.env.FUNCTIONDIR` directory
+- gets the reports from the `scored` subdirectory of the `process.env.REPORTDIR` directory
+- writes the digested reports to the `digested` subdirectory of the `process.env.REPORTDIR` directory
+
+The optional third argument to call (`75` in this example) is a report selector. Without the argument, `call` gets all the reports in the `scored` subdirectory of the `process.env.REPORTDIR` directory. With the argument, `call` gets only those reports whose names begin with the argument string.
 
-The digests created by `digest` are HTML files, and they expect a `style.css` file to exist in their directory. The `reports/digested/style.css` file in Testilo is an appropriate stylesheet to be copied into the `REPORTDIR_DIGESTED` directory.
+The digests created by `digest` are HTML files, and they expect a `style.css` file to exist in their directory. The `reports/digested/style.css` file in Testilo is an appropriate stylesheet to be copied into the directory where digested reports are written.
 
-### `compare`
+### Validation
 
-You can summarize multiple scored reports by producing a document comparing the scores. The `compare` function does this. It gathers scores from a set of scored reports and produces an HTML document comparing the scores. It depends on a _comparison proc_ to define the rules for making and showing the comparative scores. Some compare procs are in the Testilo package (in the `procs/compare` directory), and you can create more compare procs to implement different rules.
+To test the `digest` module, in the project directory you can execute the statement `node validation/digest/validate`. All logging statements should begin with “Success” and none should begin with “ERROR”.
 
-Execution by a module:
+### Report comparison
+
+If you use Testilo to perform a battery of tests on multiple targets, you may want a single report that compares the total scores received by the targets. Testilo can produce such a _comparative report_.
+
+The `compare` module compares the scores in a collection of scored reports. Its `compare()` function takes three arguments:
+- a comparison template
+- a comparison function
+- an array of scored reports
+
+The comparison template is an HTML document containing placeholders. A copy of the template, with its placeholders replaced by texts, becomes the comparative report. The comparison function defines the rules for replacing the placeholders with texts. The Testilo package contains a `procs/compare` directory, in which there are subdirectories containing pairs of templates and modules that export comparison functions. You can use one of those pairs, or you can create your own.
+
+### Invocation
+
+There are two ways to use the `compare` module.
+
+#### By a module
+
+A module can invoke `compare` in this way:
 
 ```javaScript
+const fs = require('fs/promises);
 const {compare} = require('testilo/compare');
-compare('cp25a', 'legislators')
-.then(() => {
-  console.log(`Comparison complete`);
+const comparerDir = `${process.env.FUNCTIONDIR}/compare/cp25a`;
+fs.readFile(`${comparerDir}/index.html`)
+.then(template => {
+  const {comparer} = require(`${comparerDir}/index`);
+  const comparativeReports = compare(template, comparer, scoredReports);
 });
 ```
 
-Execution by a user:
+The first two arguments to `compare()` are a template and a comparison function. In this example, they have been obtained from files in the Testilo package, but they could be custom-made. The third argument to `compare()` is an array of report objects.
+
+#### By a user
+
+A user can invoke `compare` in this way:
 
 ```bash
 node call compare cp25a legislators
 ```
 
-The first argument to `compare`, or the second argument to `call`,  names the comparison proc to be used. The subsequent argument specifies a base of the name of the comparative report that will be produced. The scores in all reports in the `REPORTDIR_SCORED` directory will be compared. The comparative report will be written in the `COMPARISONDIR` directory.
+When a user invokes `compare` in this example, the `call` module:
+- gets the template and the comparison module from subdirectory `cp25a` of the subdirectory `compare` in the `process.env.FUNCTIONDIR` directory
+- gets all the reports in the `scored` subdirectory of the `process.env.REPORTDIR` directory
+- writes the comparative report as an HTML file named `legislators.html` to the `comparative` subdirectory of the `process.env.REPORTDIR` directory
+
+The comparative reports created by `compare` are HTML files, and they expect a `style.css` file to exist in their directory. The `reports/comparative/style.css` file in Testilo is an appropriate stylesheet to be copied into the directory where comparative reports are written.
+
+### Validation
 
-The comparison created by `compare` is an HTML file, and it expects a `style.css` file to exist in its directory. The `reports/comparative/style.css` file in Testilo is an appropriate stylesheet to be copied into the `COMPARISONDIR` directory.
+To test the `compare` module, in the project directory you can execute the statement `node validation/compare/validate`. All logging statements should begin with “Success” and none should begin with “ERROR”.