@jrpool/kilotest 46.0.1 → 46.0.3

package/env.example

@@ -12,6 +12,9 @@ THIS_KILOTEST_HOST=__placeholder__
 LOCAL_KILOTEST_HOST=http://localhost:3000
 # URL of the deployed host.
 DEPLOYED_KILOTEST_HOST=https://kilotest.com
+# Path of the data directory (defaults to the db subdirectory of the project root). Tests set
+# this to a fixture directory so they never read or write the real db.
+DB_DIR=__placeholder__
 
 # Alert configuration:
 

package/eslint.config.mjs

@@ -9,7 +9,8 @@ export default defineConfig([
   {
     ignores: [
       "docs/IDEAS.md",
-      "package-lock.json"
+      "package-lock.json",
+      "coverage/**"
     ]
   },
   {

package/index.js

@@ -65,9 +65,9 @@ const answer = {
 // CONSTANTS
 
 const protocol = process.env.PROTOCOL || 'http';
-const queuePath = path.join(jobsPath, 'queue');
-const claimedPath = path.join(jobsPath, 'claimed');
-const failedPath = path.join(jobsPath, 'failed');
+const queuePath = () => path.join(jobsPath(), 'queue');
+const claimedPath = () => path.join(jobsPath(), 'claimed');
+const failedPath = () => path.join(jobsPath(), 'failed');
 // Credentials of the Testaro workers, by worker ID, from a JSON-object environment variable.
 // Each worker ID maps to a secret (used only to authenticate the worker, never published) and a
 // name (a non-secret label safe to publish, e.g. in report data and logs).
@@ -238,7 +238,7 @@ const processJobRequest = async (request, response, workerName) => jobLock(async
   const claimedJobNames = jobNames.claimed;
   // For each claimed job:
   for (const jobName of claimedJobNames) {
-    const job = await getObject(path.join(jobsPath, 'claimed', jobName));
+    const job = await getObject(path.join(jobsPath(), 'claimed', jobName));
     const {id, sources} = job;
     const {worker} = sources;
     // If its assignee is the worker:
@@ -248,7 +248,7 @@ const processJobRequest = async (request, response, workerName) => jobLock(async
       await serveError({message: `${messageStart}${messageEnd}`}, response, false);
       // Reclassify the job as failed.
       await fs.rename(
-        path.join(claimedPath, jobName), path.join(failedPath, jobName)
+        path.join(claimedPath(), jobName), path.join(failedPath(), jobName)
       );
       clean = false;
       // Stop checking claimed jobs.
@@ -262,7 +262,7 @@ const processJobRequest = async (request, response, workerName) => jobLock(async
     if (queuedJobNames.length) {
       const oldestJobName = queuedJobNames[0];
       // Get the first one.
-      const firstJob = await getObject(path.join(queuePath, oldestJobName));
+      const firstJob = await getObject(path.join(queuePath(), oldestJobName));
       // Add the public worker name to the job, in a property Testaro does not read or alter.
       firstJob.sources.worker = workerName;
       console.log(
@@ -278,10 +278,10 @@ const processJobRequest = async (request, response, workerName) => jobLock(async
       console.log(`${messageStart}${messageEnd}`);
       // Save the job in the claimed-jobs directory.
       await fs.writeFile(
-        path.join(claimedPath, oldestJobName), getJSON(firstJob)
+        path.join(claimedPath(), oldestJobName), getJSON(firstJob)
       );
       // Delete it from the queue.
-      await fs.unlink(path.join(queuePath, oldestJobName));
+      await fs.unlink(path.join(queuePath(), oldestJobName));
     }
     // Otherwise, i.e. if no jobs are queued:
     else {
@@ -661,7 +661,7 @@ const requestHandler = async (request, response) => {
               // Delete the rejected URL.
               delete recs[url];
               // Save the revised recommendations.
-              await fs.writeFile(path.join(jobsPath, 'recs.json'), getJSON(recs));
+              await fs.writeFile(path.join(jobsPath(), 'recs.json'), getJSON(recs));
             });
             // Set a location header for a response.
             response.setHeader('content-location', '/enqueueForm.html');
@@ -739,7 +739,7 @@ const requestHandler = async (request, response) => {
             if (id && isTimeStamp(timeStamp) && isJobID(jobID) && what && url) {
               const [timeStamp, jobID] = id.split('-');
               // Get the job the report is from.
-              const claimedJob = await getObject(path.join(claimedPath, `${id}.json`));
+              const claimedJob = await getObject(path.join(claimedPath(), `${id}.json`));
               // If the job was actually assigned to this worker:
               if (typeof claimedJob === 'object' && claimedJob.sources?.worker === workerName) {
                 console.log(`Testaro report ${id} was received from worker ${workerName}`);
@@ -755,7 +755,7 @@ const requestHandler = async (request, response) => {
                 // Check the monetary balances and send alerts if nearing exhaustion.
                 await checkBalancesForAlerts(report);
                 // Delete the job.
-                await fs.unlink(path.join(claimedPath, `${id}.json`));
+                await fs.unlink(path.join(claimedPath(), `${id}.json`));
                 console.log(`Completed job ${id} deleted`);
                 // Acknowledge receipt.
                 response.setHeader('content-type', 'application/json; charset=utf-8');
@@ -868,7 +868,7 @@ const requestHandler = async (request, response) => {
 
 const serve = async (protocolModule, options) => {
   // Create any missing directories.
-  for (const path of [queuePath, claimedPath, failedPath, hiddenReportsPath, reportsPath]) {
+  for (const path of [queuePath(), claimedPath(), failedPath(), hiddenReportsPath(), reportsPath()]) {
     await fs.mkdir(path, {recursive: true});
   }
   const server = protocolModule === 'https'

package/openapi.yaml

@@ -254,9 +254,9 @@ paths:
                                       type: object
                                       properties:
                                         name:
-                                          anyOf:
-                                            - type: string
-                                            - type: 'null'
+                                          type:
+                                            - string
+                                            - 'null'
                                         reason for failure:
                                           description: Copied verbatim from the Testaro report; shape may vary.
                                       required:
@@ -266,9 +266,9 @@ paths:
                                   names of rule engines that reported rule violations:
                                     type: array
                                     items:
-                                      anyOf:
-                                        - type: string
-                                        - type: 'null'
+                                      type:
+                                        - string
+                                        - 'null'
                                   counts of issues by priority:
                                     type: object
                                     properties:
@@ -782,9 +782,9 @@ paths:
                     type: object
                     properties:
                       size of the report in bytes:
-                        anyOf:
-                          - type: number
-                          - type: string
+                        type:
+                          - number
+                          - string
                       full report:
                         description: The full raw Testaro/Testilo report JSON, copied verbatim, or an error object if it could not be retrieved.
                     required:
@@ -1224,9 +1224,9 @@ components:
           type: string
           description: URL of the equivalent web UI page for this request.
         closest ancestor request:
-          anyOf:
-            - type: string
-            - type: 'null'
+          type:
+            - string
+            - 'null'
       required:
         - this request
         - closest ancestor request
@@ -1290,13 +1290,13 @@ components:
         identifier:
           type: string
         name:
-          anyOf:
-            - type: string
-            - type: 'null'
+          type:
+            - string
+            - 'null'
         sponsor:
-          anyOf:
-            - type: string
-            - type: 'null'
+          type:
+            - string
+            - 'null'
       required:
         - identifier
         - name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "46.0.1",
+  "version": "46.0.3",
   "description": "Ensemble testing for front-end web quality",
   "main": "index.js",
   "engines": {

package/test/fixtures/buildFixtures.js

@@ -0,0 +1,244 @@
+/*
+  buildFixtures.js
+  Builds the fixture corpus for Kilotest tests.
+
+  Each fixture is a minimal Testaro report in the current format, crafted so
+  that the expected API response can be hand-computed and hard-coded into
+  tests. The fixtures collectively cover the `outcome` property values
+  (`failed`, `cantTell`, and missing/undefined), superseded reports, empty
+  reports, and prevented rule engines.
+
+  Run with: node test/fixtures/buildFixtures.js [targetDir]
+  Defaults to test/fixtures/db under the project root.
+*/
+
+// IMPORTS
+
+const fs = require('fs/promises');
+const path = require('path');
+
+// CONSTANTS
+
+// Issue IDs with known specs in testaro-issues, chosen for different weights.
+const ISSUE_LINK_NO_TEXT = 'linkNoText';       // weight 4 (highest)
+const ISSUE_FOCUS_INDICATION = 'focusIndicationBad'; // weight 4
+const ISSUE_ALL_CAPS = 'allCaps';              // weight 1 (lowest)
+
+// Rule engine IDs that exist in util.js ruleEngines.
+const ENGINE_AXE = 'axe';
+const ENGINE_ALFA = 'alfa';
+const ENGINE_IBM = 'ibm';
+
+// FUNCTIONS
+
+// Returns a minimal catalog item.
+const catalogItem = (tagName, text, pathID = '/html', boxID = '0:0:100:50') => ({
+  tagName,
+  id: '',
+  startTag: `<${tagName.toLowerCase()}>`,
+  text,
+  textLinkable: false,
+  boxID,
+  pathID,
+  headingIndex: '',
+  checkpoint: 0
+});
+
+// Returns a minimal standard instance.
+const instance = (
+  ruleID, what, outcome, issueID, catalogIndex, ordinalSeverity = 2, count = 1
+) => ({
+  ruleID,
+  what,
+  ordinalSeverity,
+  outcome,
+  count,
+  catalogIndex: String(catalogIndex),
+  checkpoint: 0,
+  issueID
+});
+
+// Returns a minimal test act.
+const testAct = (which, instances) => ({
+  type: 'test',
+  which,
+  startTime: '26-01-01T00:00',
+  endTime: '26-01-01T00:01',
+  result: {
+    standardResult: {
+      instances,
+      outcomeTotals: {
+        failed: instances.filter(i => i.outcome === 'failed').length,
+        cantTell: instances.filter(i => i.outcome === 'cantTell').length
+      }
+    }
+  }
+});
+
+// Returns a minimal valid report.
+const report = (id, what, url, acts, catalog, endTime = '26-01-01T00:10') => ({
+  id,
+  what,
+  strict: false,
+  standard: 'only',
+  device: {id: 'default'},
+  browserID: 'chromium',
+  creationTimeStamp: id.slice(0, 11),
+  executionTimeStamp: id.slice(0, 11),
+  target: {what, url},
+  sources: {worker: 'test-worker'},
+  acts,
+  jobData: {
+    startTime: '26-01-01T00:00',
+    endTime,
+    elapsedSeconds: 600,
+    preventions: {},
+    issuelessRules: []
+  },
+  catalog,
+  images: {},
+  checkpoints: []
+});
+
+// Writes a JSON file with a trailing newline.
+const writeJSON = async (filePath, object) => {
+  await fs.writeFile(filePath, `${JSON.stringify(object, null, 2)}\n`);
+};
+
+// MAIN
+
+const main = async () => {
+  const targetDir = process.argv[2] || path.join(__dirname, 'db');
+  const reportsDir = path.join(targetDir, 'reports');
+  await fs.mkdir(reportsDir, {recursive: true});
+  await fs.mkdir(path.join(targetDir, 'jobs', 'queue'), {recursive: true});
+  await fs.mkdir(path.join(targetDir, 'jobs', 'claimed'), {recursive: true});
+  await fs.mkdir(path.join(targetDir, 'jobs', 'failed'), {recursive: true});
+  await fs.mkdir(path.join(targetDir, 'hiddenReports'), {recursive: true});
+
+  // Fixture 1: mixedOutcomes
+  // Two rule engines, three instances: one failed, one cantTell, one failed.
+  // The cantTell instance must be excluded from issue/violator counts.
+  // Two distinct issues (linkNoText weight 4, allCaps weight 1) and two
+  // distinct violator catalog indexes (0 and 1).
+  const mixedCatalog = {
+    '0': catalogItem('A', 'About Us', '/html/body/a[1]', '10:20:80:30'),
+    '1': catalogItem('P', 'ALL ABOUT US', '/html/body/p[1]', '10:60:80:20')
+  };
+  const mixedActs = [
+    testAct(ENGINE_AXE, [
+      instance('r11', 'The link does not have an accessible name', 'failed',
+        ISSUE_LINK_NO_TEXT, 0, 2, 1),
+      instance('r65', 'Focus Visible', 'cantTell',
+        ISSUE_FOCUS_INDICATION, 0, 0, 1)
+    ]),
+    testAct(ENGINE_ALFA, [
+      instance('r11', 'The link does not have an accessible name', 'failed',
+        ISSUE_LINK_NO_TEXT, 0, 2, 1),
+      instance('r3', 'Text is all-capital', 'failed',
+        ISSUE_ALL_CAPS, 1, 1, 1)
+    ])
+  ];
+  await writeJSON(
+    path.join(reportsDir, '260101T0000-mix.json'),
+    report('260101T0000-mix', 'Mixed Outcomes Page',
+      'https://example.com/mixed', mixedActs, mixedCatalog)
+  );
+
+  // Fixture 2: allCantTell
+  // All instances have outcome cantTell, so no issues or violators should be
+  // reported by listIssues, listViolators, or listDiagnoses.
+  const cantTellCatalog = {
+    '0': catalogItem('A', 'Click here', '/html/body/a[1]', '5:10:60:20')
+  };
+  const cantTellActs = [
+    testAct(ENGINE_AXE, [
+      instance('r65', 'Focus Visible', 'cantTell',
+        ISSUE_FOCUS_INDICATION, 0, 0, 1)
+    ])
+  ];
+  await writeJSON(
+    path.join(reportsDir, '260101T0001-ct.json'),
+    report('260101T0001-ct', 'All CantTell Page',
+      'https://example.com/canttell', cantTellActs, cantTellCatalog)
+  );
+
+  // Fixture 3: noOutcomes
+  // Instances with no outcome property. Testaro defaults to 'failed', but
+  // Kilotest code checks `outcome !== 'cantTell'`, so missing outcome (undefined)
+  // is treated as a violation. This verifies that behavior.
+  const noOutcomeCatalog = {
+    '0': catalogItem('BUTTON', 'Submit', '/html/body/button[1]', '15:25:70:30')
+  };
+  const noOutcomeActs = [
+    testAct(ENGINE_IBM, [
+      {
+        ruleID: 'r1',
+        what: 'Button has no accessible name',
+        ordinalSeverity: 3,
+        count: 1,
+        catalogIndex: '0',
+        checkpoint: 0,
+        issueID: ISSUE_LINK_NO_TEXT
+      }
+    ])
+  ];
+  await writeJSON(
+    path.join(reportsDir, '260101T0002-no.json'),
+    report('260101T0002-no', 'No Outcomes Page',
+      'https://example.com/nooutcomes', noOutcomeActs, noOutcomeCatalog)
+  );
+
+  // Fixture 4: superseded
+  // A report about the same page as mixedOutcomes but with a later timestamp,
+  // so mixedOutcomes is superseded by this one.
+  const newerActs = [
+    testAct(ENGINE_AXE, [
+      instance('r11', 'The link does not have an accessible name', 'failed',
+        ISSUE_LINK_NO_TEXT, 0, 2, 1)
+    ])
+  ];
+  await writeJSON(
+    path.join(reportsDir, '260202T0000-new.json'),
+    report('260202T0000-new', 'Mixed Outcomes Page',
+      'https://example.com/mixed', newerActs, mixedCatalog, '26-02-02T00:10')
+  );
+
+  // Fixture 5: empty
+  // A valid report with no test acts that have instances, so listIssues
+  // returns zero issues.
+  await writeJSON(
+    path.join(reportsDir, '260101T0005-emp.json'),
+    report('260101T0005-emp', 'Empty Results Page',
+      'https://example.com/empty', [testAct(ENGINE_AXE, [])], {})
+  );
+
+  // Fixture 6: prevented
+  // A report where one rule engine was prevented from testing.
+  const preventedCatalog = {
+    '0': catalogItem('IMG', 'An image', '/html/body/img[1]', '0:0:200:100')
+  };
+  const preventedActs = [
+    testAct(ENGINE_AXE, [
+      instance('r11', 'The image has no alt text', 'failed',
+        ISSUE_LINK_NO_TEXT, 0, 2, 1)
+    ])
+  ];
+  const preventedReport = report('260101T0006-prv', 'Prevented Page',
+    'https://example.com/prevented', preventedActs, preventedCatalog);
+  preventedReport.jobData.preventions = {alfa: 'page timed out'};
+  await writeJSON(
+    path.join(reportsDir, '260101T0006-prv.json'),
+    preventedReport
+  );
+
+  // Write an empty recs.json so getRecs does not try to create one.
+  await writeJSON(path.join(targetDir, 'jobs', 'recs.json'), {});
+
+  console.log(`Fixtures built in ${targetDir}`);
+};
+
+main().catch(error => {
+  console.error(error);
+  process.exit(1);
+});

package/test/fixtures/db/jobs/recs.json

@@ -0,0 +1 @@
+{}

package/test/fixtures/db/reports/260101T0000-mix.json

@@ -0,0 +1,126 @@
+{
+  "id": "260101T0000-mix",
+  "what": "Mixed Outcomes Page",
+  "strict": false,
+  "standard": "only",
+  "device": {
+    "id": "default"
+  },
+  "browserID": "chromium",
+  "creationTimeStamp": "260101T0000",
+  "executionTimeStamp": "260101T0000",
+  "target": {
+    "what": "Mixed Outcomes Page",
+    "url": "https://example.com/mixed"
+  },
+  "sources": {
+    "worker": "test-worker"
+  },
+  "acts": [
+    {
+      "type": "test",
+      "which": "axe",
+      "startTime": "26-01-01T00:00",
+      "endTime": "26-01-01T00:01",
+      "result": {
+        "standardResult": {
+          "instances": [
+            {
+              "ruleID": "r11",
+              "what": "The link does not have an accessible name",
+              "ordinalSeverity": 2,
+              "outcome": "failed",
+              "count": 1,
+              "catalogIndex": "0",
+              "checkpoint": 0,
+              "issueID": "linkNoText"
+            },
+            {
+              "ruleID": "r65",
+              "what": "Focus Visible",
+              "ordinalSeverity": 0,
+              "outcome": "cantTell",
+              "count": 1,
+              "catalogIndex": "0",
+              "checkpoint": 0,
+              "issueID": "focusIndicationBad"
+            }
+          ],
+          "outcomeTotals": {
+            "failed": 1,
+            "cantTell": 1
+          }
+        }
+      }
+    },
+    {
+      "type": "test",
+      "which": "alfa",
+      "startTime": "26-01-01T00:00",
+      "endTime": "26-01-01T00:01",
+      "result": {
+        "standardResult": {
+          "instances": [
+            {
+              "ruleID": "r11",
+              "what": "The link does not have an accessible name",
+              "ordinalSeverity": 2,
+              "outcome": "failed",
+              "count": 1,
+              "catalogIndex": "0",
+              "checkpoint": 0,
+              "issueID": "linkNoText"
+            },
+            {
+              "ruleID": "r3",
+              "what": "Text is all-capital",
+              "ordinalSeverity": 1,
+              "outcome": "failed",
+              "count": 1,
+              "catalogIndex": "1",
+              "checkpoint": 0,
+              "issueID": "allCaps"
+            }
+          ],
+          "outcomeTotals": {
+            "failed": 2,
+            "cantTell": 0
+          }
+        }
+      }
+    }
+  ],
+  "jobData": {
+    "startTime": "26-01-01T00:00",
+    "endTime": "26-01-01T00:10",
+    "elapsedSeconds": 600,
+    "preventions": {},
+    "issuelessRules": []
+  },
+  "catalog": {
+    "0": {
+      "tagName": "A",
+      "id": "",
+      "startTag": "<a>",
+      "text": "About Us",
+      "textLinkable": false,
+      "boxID": "10:20:80:30",
+      "pathID": "/html/body/a[1]",
+      "headingIndex": "",
+      "checkpoint": 0
+    },
+    "1": {
+      "tagName": "P",
+      "id": "",
+      "startTag": "<p>",
+      "text": "ALL ABOUT US",
+      "textLinkable": false,
+      "boxID": "10:60:80:20",
+      "pathID": "/html/body/p[1]",
+      "headingIndex": "",
+      "checkpoint": 0
+    }
+  },
+  "images": {},
+  "checkpoints": []
+}

package/test/fixtures/db/reports/260101T0001-ct.json

@@ -0,0 +1,69 @@
+{
+  "id": "260101T0001-ct",
+  "what": "All CantTell Page",
+  "strict": false,
+  "standard": "only",
+  "device": {
+    "id": "default"
+  },
+  "browserID": "chromium",
+  "creationTimeStamp": "260101T0001",
+  "executionTimeStamp": "260101T0001",
+  "target": {
+    "what": "All CantTell Page",
+    "url": "https://example.com/canttell"
+  },
+  "sources": {
+    "worker": "test-worker"
+  },
+  "acts": [
+    {
+      "type": "test",
+      "which": "axe",
+      "startTime": "26-01-01T00:00",
+      "endTime": "26-01-01T00:01",
+      "result": {
+        "standardResult": {
+          "instances": [
+            {
+              "ruleID": "r65",
+              "what": "Focus Visible",
+              "ordinalSeverity": 0,
+              "outcome": "cantTell",
+              "count": 1,
+              "catalogIndex": "0",
+              "checkpoint": 0,
+              "issueID": "focusIndicationBad"
+            }
+          ],
+          "outcomeTotals": {
+            "failed": 0,
+            "cantTell": 1
+          }
+        }
+      }
+    }
+  ],
+  "jobData": {
+    "startTime": "26-01-01T00:00",
+    "endTime": "26-01-01T00:10",
+    "elapsedSeconds": 600,
+    "preventions": {},
+    "issuelessRules": []
+  },
+  "catalog": {
+    "0": {
+      "tagName": "A",
+      "id": "",
+      "startTag": "<a>",
+      "text": "Click here",
+      "textLinkable": false,
+      "boxID": "5:10:60:20",
+      "pathID": "/html/body/a[1]",
+      "headingIndex": "",
+      "checkpoint": 0
+    }
+  },
+  "images": {},
+  "checkpoints": []
+}

package/test/fixtures/db/reports/260101T0002-no.json

@@ -0,0 +1,68 @@
+{
+  "id": "260101T0002-no",
+  "what": "No Outcomes Page",
+  "strict": false,
+  "standard": "only",
+  "device": {
+    "id": "default"
+  },
+  "browserID": "chromium",
+  "creationTimeStamp": "260101T0002",
+  "executionTimeStamp": "260101T0002",
+  "target": {
+    "what": "No Outcomes Page",
+    "url": "https://example.com/nooutcomes"
+  },
+  "sources": {
+    "worker": "test-worker"
+  },
+  "acts": [
+    {
+      "type": "test",
+      "which": "ibm",
+      "startTime": "26-01-01T00:00",
+      "endTime": "26-01-01T00:01",
+      "result": {
+        "standardResult": {
+          "instances": [
+            {
+              "ruleID": "r1",
+              "what": "Button has no accessible name",
+              "ordinalSeverity": 3,
+              "count": 1,
+              "catalogIndex": "0",
+              "checkpoint": 0,
+              "issueID": "linkNoText"
+            }
+          ],
+          "outcomeTotals": {
+            "failed": 0,
+            "cantTell": 0
+          }
+        }
+      }
+    }
+  ],
+  "jobData": {
+    "startTime": "26-01-01T00:00",
+    "endTime": "26-01-01T00:10",
+    "elapsedSeconds": 600,
+    "preventions": {},
+    "issuelessRules": []
+  },
+  "catalog": {
+    "0": {
+      "tagName": "BUTTON",
+      "id": "",
+      "startTag": "<button>",
+      "text": "Submit",
+      "textLinkable": false,
+      "boxID": "15:25:70:30",
+      "pathID": "/html/body/button[1]",
+      "headingIndex": "",
+      "checkpoint": 0
+    }
+  },
+  "images": {},
+  "checkpoints": []
+}

package/test/fixtures/db/reports/260101T0005-emp.json

@@ -0,0 +1,46 @@
+{
+  "id": "260101T0005-emp",
+  "what": "Empty Results Page",
+  "strict": false,
+  "standard": "only",
+  "device": {
+    "id": "default"
+  },
+  "browserID": "chromium",
+  "creationTimeStamp": "260101T0005",
+  "executionTimeStamp": "260101T0005",
+  "target": {
+    "what": "Empty Results Page",
+    "url": "https://example.com/empty"
+  },
+  "sources": {
+    "worker": "test-worker"
+  },
+  "acts": [
+    {
+      "type": "test",
+      "which": "axe",
+      "startTime": "26-01-01T00:00",
+      "endTime": "26-01-01T00:01",
+      "result": {
+        "standardResult": {
+          "instances": [],
+          "outcomeTotals": {
+            "failed": 0,
+            "cantTell": 0
+          }
+        }
+      }
+    }
+  ],
+  "jobData": {
+    "startTime": "26-01-01T00:00",
+    "endTime": "26-01-01T00:10",
+    "elapsedSeconds": 600,
+    "preventions": {},
+    "issuelessRules": []
+  },
+  "catalog": {},
+  "images": {},
+  "checkpoints": []
+}

package/test/fixtures/db/reports/260101T0006-prv.json

@@ -0,0 +1,71 @@
+{
+  "id": "260101T0006-prv",
+  "what": "Prevented Page",
+  "strict": false,
+  "standard": "only",
+  "device": {
+    "id": "default"
+  },
+  "browserID": "chromium",
+  "creationTimeStamp": "260101T0006",
+  "executionTimeStamp": "260101T0006",
+  "target": {
+    "what": "Prevented Page",
+    "url": "https://example.com/prevented"
+  },
+  "sources": {
+    "worker": "test-worker"
+  },
+  "acts": [
+    {
+      "type": "test",
+      "which": "axe",
+      "startTime": "26-01-01T00:00",
+      "endTime": "26-01-01T00:01",
+      "result": {
+        "standardResult": {
+          "instances": [
+            {
+              "ruleID": "r11",
+              "what": "The image has no alt text",
+              "ordinalSeverity": 2,
+              "outcome": "failed",
+              "count": 1,
+              "catalogIndex": "0",
+              "checkpoint": 0,
+              "issueID": "linkNoText"
+            }
+          ],
+          "outcomeTotals": {
+            "failed": 1,
+            "cantTell": 0
+          }
+        }
+      }
+    }
+  ],
+  "jobData": {
+    "startTime": "26-01-01T00:00",
+    "endTime": "26-01-01T00:10",
+    "elapsedSeconds": 600,
+    "preventions": {
+      "alfa": "page timed out"
+    },
+    "issuelessRules": []
+  },
+  "catalog": {
+    "0": {
+      "tagName": "IMG",
+      "id": "",
+      "startTag": "<img>",
+      "text": "An image",
+      "textLinkable": false,
+      "boxID": "0:0:200:100",
+      "pathID": "/html/body/img[1]",
+      "headingIndex": "",
+      "checkpoint": 0
+    }
+  },
+  "images": {},
+  "checkpoints": []
+}

package/test/fixtures/db/reports/260202T0000-new.json

@@ -0,0 +1,80 @@
+{
+  "id": "260202T0000-new",
+  "what": "Mixed Outcomes Page",
+  "strict": false,
+  "standard": "only",
+  "device": {
+    "id": "default"
+  },
+  "browserID": "chromium",
+  "creationTimeStamp": "260202T0000",
+  "executionTimeStamp": "260202T0000",
+  "target": {
+    "what": "Mixed Outcomes Page",
+    "url": "https://example.com/mixed"
+  },
+  "sources": {
+    "worker": "test-worker"
+  },
+  "acts": [
+    {
+      "type": "test",
+      "which": "axe",
+      "startTime": "26-01-01T00:00",
+      "endTime": "26-01-01T00:01",
+      "result": {
+        "standardResult": {
+          "instances": [
+            {
+              "ruleID": "r11",
+              "what": "The link does not have an accessible name",
+              "ordinalSeverity": 2,
+              "outcome": "failed",
+              "count": 1,
+              "catalogIndex": "0",
+              "checkpoint": 0,
+              "issueID": "linkNoText"
+            }
+          ],
+          "outcomeTotals": {
+            "failed": 1,
+            "cantTell": 0
+          }
+        }
+      }
+    }
+  ],
+  "jobData": {
+    "startTime": "26-01-01T00:00",
+    "endTime": "26-02-02T00:10",
+    "elapsedSeconds": 600,
+    "preventions": {},
+    "issuelessRules": []
+  },
+  "catalog": {
+    "0": {
+      "tagName": "A",
+      "id": "",
+      "startTag": "<a>",
+      "text": "About Us",
+      "textLinkable": false,
+      "boxID": "10:20:80:30",
+      "pathID": "/html/body/a[1]",
+      "headingIndex": "",
+      "checkpoint": 0
+    },
+    "1": {
+      "tagName": "P",
+      "id": "",
+      "startTag": "<p>",
+      "text": "ALL ABOUT US",
+      "textLinkable": false,
+      "boxID": "10:60:80:20",
+      "pathID": "/html/body/p[1]",
+      "headingIndex": "",
+      "checkpoint": 0
+    }
+  },
+  "images": {},
+  "checkpoints": []
+}

package/util.js

@@ -14,18 +14,19 @@ const wcagMap = require('./wcagMap.json');
 
 // CONSTANTS
 
-// Path of the data directory.
-const dbPath = exports.dbPath = path.join(__dirname, 'db');
+// Path of the data directory. Read afresh on every call (rather than cached at module load) so
+// that tests can point Kilotest at a fixture directory via the DB_DIR environment variable.
+const dbPath = exports.dbPath = () => process.env.DB_DIR || path.join(__dirname, 'db');
 // Path of the jobs directory.
-const jobsPath = exports.jobsPath = path.join(dbPath, 'jobs');
+const jobsPath = exports.jobsPath = () => path.join(dbPath(), 'jobs');
 // Path of the recommendations file.
-const recsPath = exports.recsPath = path.join(jobsPath, 'recs.json');
+const recsPath = exports.recsPath = () => path.join(jobsPath(), 'recs.json');
 // Path of the reports directory.
-const reportsPath = exports.reportsPath = path.join(dbPath, 'reports');
+const reportsPath = exports.reportsPath = () => path.join(dbPath(), 'reports');
 // Path of the hidden-reports directory.
-const hiddenReportsPath = exports.hiddenReportsPath = path.join(dbPath, 'hiddenReports');
+const hiddenReportsPath = exports.hiddenReportsPath = () => path.join(dbPath(), 'hiddenReports');
 // Path of the reports data file.
-const reportsExtractPath = exports.reportsExtractPath = path.join(dbPath, 'reportsExtract.json');
+const reportsExtractPath = exports.reportsExtractPath = () => path.join(dbPath(), 'reportsExtract.json');
 // IDs, names, and sponsors of Testaro rule engines.
 const ruleEngines = exports.ruleEngines = {
   alfa: ['Alfa', 'Siteimprove'],
@@ -145,7 +146,7 @@ const getJobNames = exports.getJobNames = async () => {
   let fileNames;
   for (const category of ['queue', 'claimed', 'failed']) {
     try {
-      fileNames = await fs.readdir(path.join(jobsPath, category));
+      fileNames = await fs.readdir(path.join(jobsPath(), category));
     }
     catch(error) {
       return `ERROR: Job directory ${category} not readable (${error.message})`;
@@ -229,10 +230,10 @@ const getRecs = exports.getRecs = async () => {
   let recs;
   let recsJSON;
   try {
-    recsJSON = await fs.readFile(recsPath, 'utf8');
+    recsJSON = await fs.readFile(recsPath(), 'utf8');
   }
   catch(error) {
-    await fs.writeFile(recsPath, '{}\n');
+    await fs.writeFile(recsPath(), '{}\n');
     return `ERROR: recommendations file not readable, so created an empty one (${error.message})`;
   }
   try {
@@ -285,7 +286,7 @@ exports.isRecommendable = async url => {
   const jobNames = await getJobNames();
   // For each claimed job:
   for (const fileName of jobNames.claimed) {
-    const job = await getObject(path.join(jobsPath, 'claimed', fileName));
+    const job = await getObject(path.join(jobsPath(), 'claimed', fileName));
     // If its URL is that of the recommended target:
     if (job.target.url === url) {
       // Return this.
@@ -294,7 +295,7 @@ exports.isRecommendable = async url => {
   }
   // If no claimed job has the URL of the target, for each queued job:
   for (const fileName of jobNames.queue) {
-    const job = await getObject(path.join(jobsPath, 'queue', fileName));
+    const job = await getObject(path.join(jobsPath(), 'queue', fileName));
     // If its URL is that of the recommended target:
     if (job.target.url === url) {
       // Return this.
@@ -415,7 +416,7 @@ const updateRecs = exports.updateRecs = (what, url, why) => recsLock(async () =>
     why
   });
   // Save the revised recommendations.
-  await fs.writeFile(recsPath, getJSON(recs));
+  await fs.writeFile(recsPath(), getJSON(recs));
   // Return success.
   return {};
 });
@@ -435,7 +436,7 @@ exports.getPathID = (catalog, catalogIndex, pathID) => {
 };
 // Returns the path of an available report file.
 const getReportPath = exports.getReportPath = (timeStamp, jobID) => path
-.join(reportsPath, `${timeStamp}-${jobID}.json`);
+.join(reportsPath(), `${timeStamp}-${jobID}.json`);
 // Returns whether a report is valid.
 const isValidReport = exports.isValidReport = report => {
   // Return whether it has the type and properties required by Kilotest:
@@ -644,7 +645,7 @@ exports.getPageDataStrings = async (timeStamp, jobID, pageData) => {
 // Returns the creation time and size of a report.
 const getReportStats = exports.getReportStats = async (timeStamp, jobID) => {
   const reportStat = await fs.stat(
-    path.join(reportsPath, `${timeStamp}-${jobID}.json`),
+    path.join(reportsPath(), `${timeStamp}-${jobID}.json`),
     {throwIfNoEntry: false}
   );
   if (!reportStat) {
@@ -656,9 +657,9 @@ const getReportStats = exports.getReportStats = async (timeStamp, jobID) => {
 };
 // Returns whether a report is hidden.
 exports.isHidden = async (timeStamp, jobID) => {
-  await fs.mkdir(hiddenReportsPath, {recursive: true});
+  await fs.mkdir(hiddenReportsPath(), {recursive: true});
   // Get the names of the hidden report files.
-  const hiddenReportFileNames = await fs.readdir(hiddenReportsPath);
+  const hiddenReportFileNames = await fs.readdir(hiddenReportsPath());
   // Return whether the report is among them.
   return hiddenReportFileNames.includes(`${timeStamp}-${jobID}.json`);
 };
@@ -667,11 +668,11 @@ const makeReportsExtract = exports.makeReportsExtract = async () => {
   // Initialize the reports data.
   const reportsExtract = {};
   // Get the names of all report files.
-  const reportFileNames = await fs.readdir(reportsPath);
+  const reportFileNames = await fs.readdir(reportsPath());
   // For each of them:
   for (const reportFileName of reportFileNames) {
     // Get its content.
-    const reportJSON = await fs.readFile(path.join(reportsPath, reportFileName), 'utf8');
+    const reportJSON = await fs.readFile(path.join(reportsPath(), reportFileName), 'utf8');
     // Get the object that it represents.
     const report = JSON.parse(reportJSON);
     const {target, jobData} = report;
@@ -690,9 +691,9 @@ const makeReportsExtract = exports.makeReportsExtract = async () => {
     reportsExtract[jobName] = reportExtract;
   }
   // Ensure the data directory exists.
-  await fs.mkdir(dbPath, {recursive: true});
+  await fs.mkdir(dbPath(), {recursive: true});
   // Save the extract of the reports.
-  await fs.writeFile(reportsExtractPath, getJSON(reportsExtract));
+  await fs.writeFile(reportsExtractPath(), getJSON(reportsExtract));
   // Return it.
   return reportsExtract;
 };
@@ -701,7 +702,7 @@ const getReportsExtract = exports.getReportsExtract = async () => {
   let reportsExtract;
   try {
     // Get the reports extract file.
-    const reportsExtractJSON = await fs.readFile(reportsExtractPath, 'utf8');
+    const reportsExtractJSON = await fs.readFile(reportsExtractPath(), 'utf8');
     // Get its data.
     reportsExtract = JSON.parse(reportsExtractJSON);
     // If it is empty:

package/util.test.js

@@ -0,0 +1,87 @@
+/*
+  util.test.js
+  Tests for util.js data-path injection (Phase 1).
+*/
+
+// IMPORTS
+
+const {test} = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const {
+  dbPath,
+  jobsPath,
+  recsPath,
+  reportsPath,
+  hiddenReportsPath,
+  reportsExtractPath
+} = require('./util');
+
+// TESTS
+
+test('dbPath defaults to the project db directory when DB_DIR is unset', () => {
+  const saved = process.env.DB_DIR;
+  delete process.env.DB_DIR;
+  try {
+    assert.equal(dbPath(), path.join(__dirname, 'db'));
+  }
+  finally {
+    if (saved !== undefined) {
+      process.env.DB_DIR = saved;
+    }
+  }
+});
+
+test('dbPath honors DB_DIR when it is set', () => {
+  const saved = process.env.DB_DIR;
+  process.env.DB_DIR = '/tmp/kilotest-fixtures';
+  try {
+    assert.equal(dbPath(), '/tmp/kilotest-fixtures');
+  }
+  finally {
+    if (saved !== undefined) {
+      process.env.DB_DIR = saved;
+    }
+    else {
+      delete process.env.DB_DIR;
+    }
+  }
+});
+
+test('jobsPath, recsPath, reportsPath, hiddenReportsPath, and reportsExtractPath derive from DB_DIR', () => {
+  const saved = process.env.DB_DIR;
+  process.env.DB_DIR = '/tmp/kilotest-fixtures';
+  try {
+    assert.equal(jobsPath(), path.join('/tmp/kilotest-fixtures', 'jobs'));
+    assert.equal(recsPath(), path.join('/tmp/kilotest-fixtures', 'jobs', 'recs.json'));
+    assert.equal(reportsPath(), path.join('/tmp/kilotest-fixtures', 'reports'));
+    assert.equal(hiddenReportsPath(), path.join('/tmp/kilotest-fixtures', 'hiddenReports'));
+    assert.equal(reportsExtractPath(), path.join('/tmp/kilotest-fixtures', 'reportsExtract.json'));
+  }
+  finally {
+    if (saved !== undefined) {
+      process.env.DB_DIR = saved;
+    }
+    else {
+      delete process.env.DB_DIR;
+    }
+  }
+});
+
+test('changing DB_DIR between calls is reflected by the path functions', () => {
+  const saved = process.env.DB_DIR;
+  try {
+    process.env.DB_DIR = '/tmp/a';
+    assert.equal(reportsPath(), path.join('/tmp/a', 'reports'));
+    process.env.DB_DIR = '/tmp/b';
+    assert.equal(reportsPath(), path.join('/tmp/b', 'reports'));
+  }
+  finally {
+    if (saved !== undefined) {
+      process.env.DB_DIR = saved;
+    }
+    else {
+      delete process.env.DB_DIR;
+    }
+  }
+});

package/web/enqueue/index.js

@@ -35,7 +35,7 @@ exports.answer = async (url, what, authCode) => {
     };
     // Save the job in the queue.
     await fs.writeFile(
-      path.join(jobsPath, 'queue', `${jobName}.json`), getJSON(job)
+      path.join(jobsPath(), 'queue', `${jobName}.json`), getJSON(job)
     );
     console.log(`Retest queued for ${what} as job ${jobName}`);
     // Isolate this revision.
@@ -45,7 +45,7 @@ exports.answer = async (url, what, authCode) => {
       // Delete the recommendations to test the target.
       delete recs[url];
       // Save the revised recommendations.
-      await fs.writeFile(path.join(jobsPath, 'recs.json'), getJSON(recs));
+      await fs.writeFile(path.join(jobsPath(), 'recs.json'), getJSON(recs));
     });
     // Get the answer template.
     let answerPage = await fs.readFile(path.join(__dirname, 'index.html'), 'utf8');

package/web/expungeReportsForm/index.js

@@ -24,7 +24,7 @@ exports.answer = async (_, search) => {
         // For each report to be deleted:
         for (const jobName of jobNames) {
           // Delete it.
-          await fs.unlink(path.join(reportsPath, `${jobName}.json`));
+          await fs.unlink(path.join(reportsPath(), `${jobName}.json`));
         }
         // Update the extract of the available reports.
         await makeReportsExtract();
@@ -47,7 +47,7 @@ exports.answer = async (_, search) => {
       }
     }
   }
-  const reportNames = await fs.readdir(reportsPath);
+  const reportNames = await fs.readdir(reportsPath());
   const reportSpecs = [];
   // For each report:
   for (const reportName of reportNames) {

package/web/hideReportForm/index.js

@@ -23,7 +23,7 @@ exports.answer = async (_, search) => {
       const fileName = `${jobName}.json`;
       try {
         // Move the specified report to the directory of hidden reports.
-        await fs.rename(path.join(reportsPath, fileName), path.join(hiddenReportsPath, fileName));
+        await fs.rename(path.join(reportsPath(), fileName), path.join(hiddenReportsPath(), fileName));
         // Update the data on the available reports.
         await makeReportsExtract();
       }

package/web/listReports/index.js

@@ -60,7 +60,7 @@ const populateQuery = async query => {
     // For each job in the category:
     for (const fileName of jobFileNames[category]) {
       // Get the job.
-      const job = await getObject(path.join(jobsPath, category, fileName));
+      const job = await getObject(path.join(jobsPath(), category, fileName));
       // Add a line.
       lines[category].push(`${margin}<li><code>${job.target.url}</code> (${job.target.what})</li>`);
     }

package/web/pruneReportsForm/index.js

@@ -24,7 +24,7 @@ exports.answer = async (_, search) => {
         // For each report to be deleted:
         for (const jobName of jobNames) {
           // Delete it.
-          await fs.unlink(path.join(reportsPath, `${jobName}.json`));
+          await fs.unlink(path.join(reportsPath(), `${jobName}.json`));
         }
         // Update the extract of the available reports.
         await makeReportsExtract();
@@ -47,7 +47,7 @@ exports.answer = async (_, search) => {
       }
     }
   }
-  const reportNames = await fs.readdir(reportsPath);
+  const reportNames = await fs.readdir(reportsPath());
   // Initialize an array of report summaries.
   const reportSpecs = [];
   // For each report:

package/web/rewindReportsForm/index.js

@@ -24,7 +24,7 @@ exports.answer = async (_, search) => {
         // For each report to be deleted:
         for (const jobName of jobNames) {
           // Delete it.
-          await fs.unlink(path.join(reportsPath, `${jobName}.json`));
+          await fs.unlink(path.join(reportsPath(), `${jobName}.json`));
         }
       }
       // If this failed:
@@ -45,7 +45,7 @@ exports.answer = async (_, search) => {
       }
     }
   }
-  const reportNames = await fs.readdir(reportsPath);
+  const reportNames = await fs.readdir(reportsPath());
   const reportSpecs = [];
   // For each report:
   for (const reportName of reportNames) {

package/web/unhideReportForm/index.js

@@ -23,7 +23,7 @@ exports.answer = async (_, search) => {
       const fileName = `${jobName}.json`;
       try {
         // Move the report to the reports directory.
-        await fs.rename(path.join(hiddenReportsPath, fileName), path.join(reportsPath, fileName));
+        await fs.rename(path.join(hiddenReportsPath(), fileName), path.join(reportsPath(), fileName));
         // Update the data on the available reports.
         await makeReportsExtract();
       }
@@ -47,11 +47,11 @@ exports.answer = async (_, search) => {
   // Initialize an array of data on reports to be unhidden.
   const reportsData = [];
   // Get the names of the hidden report files.
-  const hiddenReportFileNames = await fs.readdir(hiddenReportsPath);
+  const hiddenReportFileNames = await fs.readdir(hiddenReportsPath());
   // For each hidden report:
   for (const reportFileName of hiddenReportFileNames) {
     // Get its file.
-    const reportJSON = await fs.readFile(path.join(hiddenReportsPath, reportFileName), 'utf8');
+    const reportJSON = await fs.readFile(path.join(hiddenReportsPath(), reportFileName), 'utf8');
     // Get the report.
     const report = JSON.parse(reportJSON);
     const {id, target} = report;