@jrpool/kilotest 46.0.0 → 46.0.2

package/api/util.test.js

@@ -0,0 +1,42 @@
+/*
+  util.test.js
+  Tests for api/util.js.
+*/
+
+// IMPORTS
+
+const {test} = require('node:test');
+const assert = require('node:assert/strict');
+const {getRuleEngineFacts, getRuleEnginesFacts} = require('./util');
+
+// TESTS
+
+test('getRuleEngineFacts returns the name and sponsor of a known rule engine', () => {
+  const facts = getRuleEngineFacts('axe');
+  assert.deepEqual(facts, {
+    identifier: 'axe',
+    name: 'Axe',
+    sponsor: 'Deque'
+  });
+});
+
+test('getRuleEngineFacts returns nulls for name and sponsor of an unknown rule engine', () => {
+  const facts = getRuleEngineFacts('nonexistentEngine');
+  assert.deepEqual(facts, {
+    identifier: 'nonexistentEngine',
+    name: null,
+    sponsor: null
+  });
+});
+
+test('getRuleEnginesFacts returns facts sorted alphabetically by name', () => {
+  // Names: ibm -> "Accessibility Checker", axe -> "Axe", wave -> "WAVE".
+  const facts = getRuleEnginesFacts(new Set(['wave', 'axe', 'ibm']));
+  assert.deepEqual(facts.map(fact => fact.identifier), ['ibm', 'axe', 'wave']);
+  assert.deepEqual(facts.map(fact => fact.name), ['Accessibility Checker', 'Axe', 'WAVE']);
+});
+
+test('getRuleEnginesFacts returns an empty array for an empty set', () => {
+  const facts = getRuleEnginesFacts(new Set());
+  assert.deepEqual(facts, []);
+});

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "46.0.0",
+  "version": "46.0.2",
   "description": "Ensemble testing for front-end web quality",
   "main": "index.js",
   "engines": {
@@ -9,7 +9,7 @@
   "scripts": {
     "start": "node index",
     "lint": "npx eslint && npx markdownlint-cli2",
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "c8 node --test",
     "test:api": "node api/testSuite",
     "generate:openapi": "node scripts/generate-openapi"
   },
@@ -44,6 +44,7 @@
     "@eslint/json": "*",
     "@eslint/markdown": "*",
     "@redocly/cli": "*",
+    "c8": "*",
     "eslint": "*",
     "globals": "*",
     "js-yaml": "*",
@@ -52,5 +53,28 @@
   },
   "allowScripts": {
     "fsevents@2.3.2": true
+  },
+  "c8": {
+    "all": true,
+    "reporter": [
+      "text",
+      "html"
+    ],
+    "include": [
+      "index.js",
+      "mcp.js",
+      "alerts.js",
+      "util.js",
+      "api/**/*.js"
+    ],
+    "exclude": [
+      "coverage/**",
+      "test{,s}/**",
+      "test{,-*}.{js,cjs,mjs}",
+      "**/*{.,-}test.{js,cjs,mjs}",
+      "**/__tests__/**",
+      "web/**",
+      "scripts/**"
+    ]
   }
 }

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;