testilo 10.3.1 → 11.0.2

package/README.md

@@ -36,214 +36,260 @@ Testaro executes _jobs_. In a job, Testaro performs _acts_ (tests and other oper
 You can create a job for Testaro directly, without using Testilo.
 
 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.
+- A common use case is to define a battery of tests and to have those same tests performed on multiple targets. In that case, it is efficient to create multiple jobs, one per target. 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 test acts must follow them with acts that restore the target to its pre-test state. Testilo can insert the required target-restoring acts into each job after target-modifying test act.
 
-The `merge` module performs these services.
+The `batch` and `merge` modules performs these services.
 
-### Procedure
+### Target lists
 
-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 simplest version of a list of targets is _target list_. It is stored as a tab-delimited text file, with one line per target. Each line contains 3 items, with tabs between them:
+- An ID for the target
+- A description of the target
+- The URL of the target
 
-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.
+For example, a target list (with “→” representing the Tab character) might be:
 
-### Example
+```text
+w3c→World Wide Web Consortium→https://www.w3.org/
+moz→Mozilla Foundation→https://foundation.mozilla.org/en/
+```
 
-Here is an example illustrating how merging works.
+### Batches
 
-#### Script
+Targets can be specified in a more complex way, too. That allows you to create jobs in which particular targets are handled distinctively in particular contexts. The more complex representation of a set of targets is a _batch_. Here is the start of a batch, showing its first target:
 
-Suppose you have created this script:
+```javaScript
+{
+  id: 'clothing-stores',
+  what: 'clothing stores',
+  targets: [
+    {
+      id: 'acme',
+      what: 'Acme Clothes',
+      acts: {
+        public: [
+          {
+            type: 'launch'
+          },
+          {
+            type: 'url',
+            which: 'https://acmeclothes.com/',
+            what: 'Acme Clothes home page'
+          }
+        ],
+        private: [
+          {
+            type: 'launch'
+          },
+          {
+            type: 'url',
+            which: 'https://acmeclothes.com/login.html',
+            what: 'Acme Clothes login page'
+          },
+          {
+            type: 'text',
+            which: 'User Name',
+            what: 'tester34'
+          },
+          {
+            type: 'text',
+            which: 'Password',
+            what: '__TESTER34_PASSWORD__'
+          },
+          {
+            type: 'button',
+            which: 'Submit',
+            what: 'submit the login form'
+          },
+          {
+            type: 'wait',
+            which: 'title',
+            what: 'account'
+          }
+        ]
+      }
+    },
+    …
+  ]
+}
+```
+
+As shown, a batch, unlike a target list, defines named sequences of acts. They can be plugged into jobs, so various complex operations can be performed on each target.
+
+### Scripts
+
+The generic, target-independent description of a job is _script_. A script can contain _placeholders_ that Testilo replaces with acts from a batch, creating one job per target. Thus, one script plus one batch can generate an unlimited number of jobs.
+
+Here is a script:
 
 ```javaScript
 {
   id: 'ts25',
-  what: 'Motion, Axe, and bulk',
+  what: 'Axe and QualWeb on account page',
   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
-    },
-    {
-      type: 'placeholder',
-      which: 'main',
+      which: 'private',
       launch: 'chromium'
     },
     {
       type: 'test',
       which: 'axe',
-      withItems: true,
+      detailLevel: 1,
       rules: [],
-      what: 'Axe core, all rules, with details'
+      what: 'Axe core, all rules'
     },
     {
       type: 'test',
-      which: 'bulk',
-      what: 'count of visible elements'
+      which: 'qualWeb',
+      withNewContent: false,
+      what: 'QualWeb, all rules'
     }
   ]
 }
 ```
 
-The `acts` array of this script contains three acts of type `test` and two acts of type `placeholder`.
+This script has 2 acts. The first is a placeholder act. The above batch can be merged with this script to create jobs. In that case, the first job would launch a Chromium browser, navigate to the Acme login page, complete and submit the login form, wait for the account page to load, and then run the Axe tests. If the batch contained additional targets, additional jobs would be created, with the login actions for each target specified in the `private` array of the `acts` object of that target.
+
+As shown in this example, when a browser is launched by placeholder substitution, the script can determine the browser type (`chromium`, `firefox`, or `webkit`) by assigning a value to a `launch` property of the placeholder. That is useful, because sometimes it is the actions specified in a script that dictate which browser type is appropriate.
 
-#### Batch
+### Target list to batch
 
-Suppose you have also created this batch:
+If you have a target list, the `batch` module of Testilo can convert it to a batch. The batch will contain, for each target, one array of acts named `main`, containing a `launch` act (depending on the script to specify the browser type) and a `url` act.
+
+#### Invocation
+
+There are two ways to use the `batch` module.
+
+##### By a module
+
+A module can invoke `batch` in this way:
 
 ```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'
-          }
-        ]
-      }
-    }
-  ]
-}
+const {batch} = require('testilo/batch');
+const batchObj = batch(listID, what, targetList);
 ```
 
-This batch defines two targets.
+This invocation references `listID`, `what`, and `targetList` variables that the module must have already defined. They are all strings. `listID` is a unique identifier for the target list. `what` describes the target list. `targetList` is the target list. The `batch()` function of the `batch` module generates a batch and returns it as an object. The invoking module can further dispose of the batch as needed.
+
+##### By a user
+
+A user can invoke `batch` in this way:
+
+- Create a target list and save it as a text file (with tab-delimited items in newline-delimited lines) in the `targetLists` subdirectory of the `process.env.SPECDIR` directory. Name the file `x.tsv`, where `x` is the list ID.
+- In the Testilo project directory, execute this statement:
+    - `node call batch i`
+
+In this statement, replace `i` with the list ID.
+
+The `call` module will retrieve the named target list.
+The `batch` module will convert the target list to a batch.
+The `call` module will save the batch as a JSON file in the `batches` subdirectory of the `process.env.SPECDIR` directory.
+
+### Merge
 
-#### Isolation option
+Testilo merges batches with scripts by means of a `merge` module.
 
-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 `merge` module needs to be given a batch and a script. In addition, `merge` 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 act, except where that test act is the last act or where the next act after it is a placeholder.
 
 #### Output
 
-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:
+##### Without isolation
+
+Suppose you ask for a merger of the above batch and script, **without** the isolation option. Then the first job produced by `merge` will look like this:
 
 ```javaScript
 {
-  id: '7izc1-ts25-mozilla',
-  what: 'Motion, Axe, and bulk',
+  id: '7is3i-ts25-acme',
+  what: 'Axe on account page',
   strict: true,
   timeLimit: 60,
   acts: [
     {
       type: 'launch',
-      which: 'webkit'
+      which: 'chromium'
     },
     {
       type: 'url',
-      which: 'https://foundation.mozilla.org/en/',
-      what: 'Mozilla Foundation'
-    }
+      which: 'https://acmeclothes.com/login.html',
+      what: 'Acme Clothes login page'
+    },
     {
-      type: 'test',
-      which: 'motion',
-      what: 'spontaneous change of content; requires webkit',
-      delay: 2500,
-      interval: 2500,
-      count: 5
+      type: 'text',
+      which: 'User Name',
+      what: 'tester34'
     },
     {
-      type: 'launch',
-      which: 'chromium'
+      type: 'text',
+      which: 'Password',
+      what: '34SecretTester'
     },
     {
-      type: 'url',
-      which: 'https://foundation.mozilla.org/en/',
-      what: 'Mozilla Foundation'
-    }
+      type: 'button',
+      which: 'Submit',
+      what: 'submit the login form'
+    },
+    {
+      type: 'wait',
+      which: 'title',
+      what: 'account'
+    },
     {
       type: 'test',
       which: 'axe',
-      withItems: true,
+      detailLevel: 1,
       rules: [],
-      what: 'Axe core, all rules, with details'
+      what: 'Axe core, all rules'
     },
     {
       type: 'test',
-      which: 'bulk',
-      what: 'count of visible elements'
+      which: 'qualWeb',
+      withNewContent: false,
+      what: 'QualWeb, all rules'
     }
   ],
   sources: {
     script: 'ts25',
-    batch: 'weborgs',
+    batch: 'clothing-stores',
     target: {
-      id: 'mozilla',
-      what: 'Mozilla Foundation'
+      id: 'acme',
+      what: 'Acme Clothes'
     },
     requester: 'you@yourdomain.tld'
   },
   creationTime: '2023-11-20T15:50:27',
-  timeStamp: 'bizc1'
+  timeStamp: '7is3i'
 }
 ```
 
-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.
-
-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.
-
-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`.
+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.
+- 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.
 
-This job is ready to be executed by Testaro.
+This is a valid Testaro job.
 
-If, however, you requested a merger **with** isolation, then `merge` would act as if another instance of
+##### With isolation
 
-    ```javaScript
-    {
-      type: 'placeholder',
-      which: 'main',
-      launch: 'chromium'
-    },
-    ```
+If, however, you requested a merger **with** isolation, then Testilo would take cognizance of the fact that an `axe` test act is a target-modifying act. Testilo would therefore act as if another instance of the placeholder had been located in the script after the `axe` test act. So, copies of the same 6 acts that precede the `axe` test act would be inserted **after** the `axe` test act, too.
 
-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.
+Of the 10 tools providing tests for Testaro, 6 are target-modifying:
+- `axe`
+- `continuum`
+- `htmlcs`
+- `ibm`
+- `wave`
 
-### Invocation
+#### Invocation
 
 There are two ways to use the `merge` module.
 
-#### By a module
+##### By a module
 
 A module can invoke `merge` in this way:
 
@@ -254,7 +300,7 @@ const jobs = merge(script, batch, requester, true);
 
 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.
 
-#### By a user
+##### By a user
 
 A user can invoke `merge` in this way:
 
@@ -267,26 +313,16 @@ A user can invoke `merge` in this way:
 
 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 `s` 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 first statement will cause a merger **with** isolation.
+The second and third statements will cause a merger **without* isolation.
 
 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.
+The `call` module will save the jobs as JSON files in the `todo` 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`. All logging statements should begin with “Success” and none should begin with “ERROR”.
-
-### Examples
-
-There are script and batch examples in the `specs` directory.
+#### Validation
 
-The script example (with ID `ts21`) performs all of the tests available in Testaro, including the tests of 9 dependent tools. It contains 2 `placeholder` acts, one that specifies the Webkit browser for any `launch` act and one that specifies the Chromium browser for any `launch` act.
-
-The batch example (with ID `orgs`) specifies 2 targets.
-- One of them has the URL `https://example.com` and requires each placeholder to be replaced with 2 acts: a `launch` act and a `url` act.
-- The other has the URL `https://www.w3.org/WAI/ARIA/apg/example-index/accordion/accordion` and requires each placeholder to be replaced with 3 acts: a `launch` act, a `url` act, and a `button` act.
+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”.
 
 ## Report scoring
 
@@ -307,9 +343,14 @@ Thus, a report produced by Testaro contains these properties:
 - `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.
+Testilo can enhance such a report in three ways:
+- adding scores
+- creating digests
+- creating comprisons
+
+To add scores to reports, the `score` module of Testilo performs computations on the test results and adds a `score` property to each report.
 
-The `score` module scores a report. Its `score()` function takes two arguments:
+The `score()` function of the `score` module takes two arguments:
 - a scoring function
 - an array of report objects
 
@@ -325,58 +366,44 @@ A module can invoke `score` in this way:
 
 ```javaScript
 const {score} = require('testilo/score');
-const {scorer} = require('testilo/procs/score/sp25a');
-const scoredReports = score(scorer, rawReports);
+const {scorer} = require('testilo/procs/score/tsp25');
+score(scorer, reports);
 ```
 
-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.
+The first argument to `score()` is a scoring function. In this example, it has been obtained from a module in the Testilo package, but it could be a custom function. The second argument to `score()` is an array of report objects. The invoking module can further dispose of the scored reports as needed.
 
 #### By a user
 
 A user can invoke `score` in this way:
 
 ```bash
-node call score tsp25a
-node call score tsp25a 75
+node call score tsp25
+node call score tsp25 75m
 ```
 
 When a user invokes `score` in this example, the `call` module:
-- gets the scoring module `tsp25a` from its JSON file `tsp25a.json` in the `score` subdirectory of the `process.env.FUNCTIONDIR` directory
-- gets the reports from the `raw` subdirectory of the `process.env.REPORTDIR` directory
-- writes the scored reports to the `scored` subdirectory of the `process.env.REPORTDIR` directory
+- gets the scoring module `tsp25` from its JSON file `tsp25.json` in the `score` subdirectory of the `process.env.FUNCTIONDIR` directory.
+- gets the reports from the `raw` subdirectory of the `process.env.REPORTDIR` directory.
+- writes the scored reports in JSON format 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.
+The optional third argument to call (`75m` 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”.
-
-### Comprehensive example
+To test the `score` module, in the project directory you can execute the statement `node validation/score/validate`. If `score` is valid, all logging statements will begin with “Success” and none will begin with “ERROR”.
 
-The module `procs/score/tsp21.js` is an example of a comprehensive score proc. It is designed to score reports produced by Testaro from jobs that Testilo creates from the `ts21` script. That script causes Testaro to perform 1351 tests belonging to Testaro and nine other tools integrated into Testaro as dependencies.
-
-The `tsp21` score proc combines the results of those tests into a single score for each report. The `score` property that the proc adds to the report shows how the individual test results are aggregated into a score.
-
-The `tsp21` score proc imports the `procs/score/tic21.js` module, which classifies all the tests into 255 “issues”. Any two or more tests classified into the same issue are deemed to be approximately equivalent in intent. Using this classification, the score proc tabulates the test results by issue, so that all instances of the issue, regardless of which tool discovered the instances, are reported together.
-
-The issue classification in `tic21` assigns weights to the issues to reflect their estimated severities,and the scoring algorithm of `tsp21` adopts a compromise between issue-based and tool-based summation. Thus, if 3 tools discover 20 instances of an issue, the score increases (i.e. becomes worse) by more than it would if only 1 tool had discovered them, but less than 3 times as much. The motivations are that discovery of issue instances by multiple tools increases confidence that the issues are real, and passing accessibility tests is per se beneficial because it decreases risks associated with alleged inaccessibility.
-
-The `tsp21` score proc does **not** attempt to identify instances of issues. Thus, if tool A discovers 4 instances and tool B discovers 7 instances of some issue, `tsp21` does not attempt to say which of the 4 discovered by A are a subset of the 7 discovered by B. Instead,`tsp21` naïvely acts as if the 4 are all a subset of the 7, even though in reality the two sets might be entirely disjoint.
-
-In the `tsp21` scoring algorithm, the failure of a tool or of a Testaro test to run on a page increases the score of the page, and messages logged by the browser while tests are being performed on a page, especially error messages, also increase the score.
-
-## Report digesting
+## Rport digesting
 
 ### Introduction
 
-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_.
+Reports from Testaro 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` module digests a scored report. Its `digest()` function takes three arguments:
 - a digest template
 - a digesting function
-- an array of report objects
+- an array of scored report objects
 
-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 digest template is an HTML document containing placeholders. A copy of the template, with its placeholders replaced by computed values, becomes the digest. The digesting function defines the rules for replacing the placeholders with values. 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.
 
 ### Invocation
 
@@ -389,36 +416,36 @@ A module can invoke `digest` in this way:
 ```javaScript
 const {digest} = require('testilo/digest');
 const digesterDir = `${process.env.FUNCTIONDIR}/digest/dp25a`;
-fs.readFile(`${digesterDir}/index.html`)
+fs.readFile(`${digesterDir}/index.html`, 'utf8')
 .then(template => {
   const {digester} = require(`${digesterDir}/index`);
   const digestedReports = digest(template, digester, scoredReports);
 });
 ```
 
-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.
+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 scored report objects. The `digest()` function returns an array of digested reports. The invoking module can further dispose of the digested reports as needed.
 
 #### By a user
 
 A user can invoke `digest` in this way:
 
 ```bash
-node call digest dp25a
-node call digest dp25a 75
+node call digest tdp25
+node call digest tdp25 75m
 ```
 
 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
+- gets the template and the digesting module from subdirectory `tdp25` 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 optional third argument to call (`75m` 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 directory where digested reports are written.
 
 ### Validation
 
-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”.
+To test the `digest` module, in the project directory you can execute the statement `node validation/digest/validate`. If `digest` is valid, all logging statements will begin with “Success” and none will begin with “ERROR”.
 
 ### Report comparison
 
@@ -429,7 +456,7 @@ The `compare` module compares the scores in a collection of scored reports. Its
 - 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.
+The comparison template is an HTML document containing placeholders. A copy of the template, with its placeholders replaced by computed values, becomes the comparative report. The comparison function defines the rules for replacing the placeholders with values. 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
 
@@ -442,31 +469,31 @@ A module can invoke `compare` in this way:
 ```javaScript
 const fs = require('fs/promises);
 const {compare} = require('testilo/compare');
-const comparerDir = `${process.env.FUNCTIONDIR}/compare/cp25a`;
+const comparerDir = `${process.env.FUNCTIONDIR}/compare/tcp25`;
 fs.readFile(`${comparerDir}/index.html`)
 .then(template => {
   const {comparer} = require(`${comparerDir}/index`);
-  const comparativeReports = compare(template, comparer, scoredReports);
+  const comparativeReport = compare(template, comparer, scoredReports);
 });
 ```
 
-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.
+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. The `compare()` function returns a comparative report. The invoking module can further dispose of the comparative report as needed.
 
 #### By a user
 
 A user can invoke `compare` in this way:
 
 ```bash
-node call compare cp25a legislators
+node call compare tcp25 legislators
 ```
 
 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
+- gets the template and the comparison module from subdirectory `tcp25` 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.
+The comparative report 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 directory where comparative reports are written.
 
 ### Validation
 
-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”.
+To test the `compare` module, in the project directory you can execute the statement `node validation/compare/validate`. If `compare` is valid, all logging statements will begin with “Success” and none will begin with “ERROR”.