@jrpool/kilotest 46.1.0 → 46.1.2

package/.devin/config.local.json

@@ -29,7 +29,10 @@
       "Exec($DOCKER exec)",
       "Exec($DOCKER stop)",
       "Exec(sed)",
-      "Exec(awk)"
+      "Exec(awk)",
+      "Exec(nvm ls)",
+      "Exec(.)",
+      "Exec(nvm alias)"
     ]
   }
 }

package/api/listReports.js

@@ -6,7 +6,7 @@
 // IMPORTS
 
 const {getReportBasics, getResponseMetadata, getToolsFacts, thisHost} = require('./util');
-const {getReportExtracts} = require('../util');
+const {getLatestReportExtracts, getReportExtracts} = require('../util');
 
 // FUNCTIONS
 
@@ -22,11 +22,13 @@ exports.response = async () => {
   const reportsBasics = [];
   // Get extracts of all available reports.
   const reportExtracts = await getReportExtracts();
+  // Get the latest report extracts once, to avoid recomputing them for every report.
+  const latestReportExtracts = await getLatestReportExtracts();
   // For each report:
   for (const extract of reportExtracts) {
     const {error, jobID, timeStamp} = extract;
     // Get the basics about it (which may be only an error message).
-    const reportBasics = await getReportBasics(timeStamp, jobID);
+    const reportBasics = await getReportBasics(timeStamp, jobID, extract, latestReportExtracts);
     // If this succeeded:
     if (!error) {
       // Add instructions for getting details to the basics.

package/api/util.js

@@ -68,28 +68,32 @@ exports.getRuleEnginesFacts = ruleEngineIDSet => {
   return ruleEnginesFacts;
 };
 // Returns the basics about a report.
-exports.getReportBasics = async (timeStamp, jobID) => {
-  // Get the creation time of the report.
-  const reportStats = await getReportStats(timeStamp, jobID);
-  // If the  report does not exist:
-  if (!reportStats) {
-    // Log and return this.
-    console.error(`Report ${timeStamp}-${jobID} does not exist.`);
-    return {
-      error: `Report ${timeStamp}-${jobID} could not be retrieved.`
-    };
+// Accepts optional precomputed extract and latestReportExtracts to avoid redundant
+// reads when called in a loop over all reports (e.g. by listReports).
+exports.getReportBasics = async (timeStamp, jobID, extract = null, latestReportExtracts = null) => {
+  // If an extract was not provided, verify the report exists and read it.
+  if (!extract) {
+    // Get the creation time of the report.
+    const reportStats = await getReportStats(timeStamp, jobID);
+    // If the  report does not exist:
+    if (!reportStats) {
+      // Log and return this.
+      console.error(`Report ${timeStamp}-${jobID} does not exist.`);
+      return {
+        error: `Report ${timeStamp}-${jobID} could not be retrieved.`
+      };
+    }
+    // Otherwise, i.e. if it exists, get an extract of the report.
+    extract = await getReportExtract(timeStamp, jobID);
+  }
+  const {url, what, reportTime} = extract;
+  // If the latest report extracts were not provided, compute them.
+  if (!latestReportExtracts) {
+    latestReportExtracts = await getLatestReportExtracts();
   }
-  // Otherwise, i.e. if it exists, get an extract of the report.
-  const reportExtract = await getReportExtract(timeStamp, jobID);
-  const {url, what} = reportExtract;
-  const latestReportExtracts = await getLatestReportExtracts();
-  // Otherwise, i.e. if the report exists, get whether this report has been superseded.
+  // Get whether this report has been superseded.
   const isSuperseded = latestReportExtracts
-  .every(extract => extract.timeStamp !== timeStamp || extract.jobID !== jobID);
-  // Get the completion time from the report content, not the file system birth time,
-  // because the birth time depends on when the file was created on the file system
-  // and does not reflect the actual report completion time.
-  const {reportTime} = reportExtract;
+  .every(ex => ex.timeStamp !== timeStamp || ex.jobID !== jobID);
   // Get the basics about the report.
   const basics = {
     identifier: `${timeStamp}-${jobID}`,

package/apiIntegration.test.js

@@ -77,7 +77,7 @@ const request = (method, requestPath, body = null) => new Promise((resolve, reje
 
 // TESTS
 
-test('GET /api/listReports returns valid JSON through the HTTP routing layer', async () => {
+test('GET /api/listReports returns valid JSON through the HTTP routing layer', {timeout: 500}, async () => {
   const {body} = await request('GET', '/api/listReports');
   assert.equal(body['tool name'], 'listReports');
   const reports = body['response content']['basics about all available reports'];

package/index.js

@@ -360,6 +360,12 @@ const requestHandler = async (request, response) => {
   const {pathname, search} = requestURL;
   const pageName = pathname.split('/')[1];
   const pathTail = pathname.split('/').slice(2).join('/');
+  // If the request is a smoke-test probe, respond perfunctorily without executing a handler.
+  if (request.headers['x-kilotest-smoke']) {
+    response.setHeader('content-type', 'application/json; charset=utf-8');
+    response.end('{}');
+    return;
+  }
   // If the request is a GET request:
   if (method === 'GET') {
     // If the path is not authorized for GET requests:

package/index.test.js

@@ -147,6 +147,26 @@ test('routes has GET and POST arrays', () => {
   assert.ok(Array.isArray(routes.POST));
 });
 
+// TESTS: smoke-test short-circuit
+
+test('GET with x-kilotest-smoke header returns a perfunctory 200', async () => {
+  const res = await request('GET', '/api/listReports', null, {'x-kilotest-smoke': '1'});
+  assert.equal(res.statusCode, 200);
+  assert.equal(res.body, '{}');
+});
+
+test('POST with x-kilotest-smoke header returns a perfunctory 200', async () => {
+  const res = await request('POST', '/api/requestFeature', {}, {'x-kilotest-smoke': '1'});
+  assert.equal(res.statusCode, 200);
+  assert.equal(res.body, '{}');
+});
+
+test('GET without x-kilotest-smoke header executes the handler', async () => {
+  const res = await request('GET', '/api/listReports');
+  assert.equal(res.statusCode, 200);
+  assert.notEqual(res.body, '{}');
+});
+
 // TESTS: GET routes
 
 test('GET / serves the home page as HTML', async () => {
@@ -1050,12 +1070,21 @@ test('getAbuseError uses unknown IP when no forwarding header or remote address'
 
 // UNIT TESTS FOR startServer
 
-test('startServer starts an HTTP server when protocol is http', async () => {
+test('startServer starts an HTTP server when protocol is http', {timeout: 500}, async () => {
   // Delete PROTOCOL to exercise the 'http' fallback in startServer.
   const savedProtocol = process.env.PROTOCOL;
+  // Use port 0 so the OS assigns an ephemeral port, avoiding collisions with production.
+  const savedPort = process.env.PORT;
+  process.env.PORT = '0';
   delete process.env.PROTOCOL;
   const server = await startServer();
   process.env.PROTOCOL = savedProtocol;
+  if (savedPort !== undefined) {
+    process.env.PORT = savedPort;
+  }
+  else {
+    delete process.env.PORT;
+  }
   try {
     assert.ok(server);
     assert.equal(typeof server.listen, 'function');
@@ -1078,6 +1107,56 @@ test('startServer starts an HTTP server when protocol is http', async () => {
   }
 });
 
+test('serve uses the default port 3000 when PORT is not set', {timeout: 500}, async () => {
+  // Exercise the '|| 3000' fallback branch in serve by deleting PORT and calling
+  // serve directly. The server will attempt to bind to port 3000. On a system
+  // where port 3000 is free, it succeeds and we close it. Where it is occupied,
+  // the error event fires and we accept that as proof the fallback was reached.
+  const savedPort = process.env.PORT;
+  delete process.env.PORT;
+  try {
+    const server = await indexModule.serve(http, {});
+    let bindError = null;
+    server.on('error', error => {
+      bindError = error;
+    });
+    // Wait briefly for either successful binding or an EADDRINUSE error.
+    await new Promise(resolve => {
+      const timer = setTimeout(resolve, 200);
+      server.on('listening', () => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+    if (bindError) {
+      assert.equal(bindError.code, 'EADDRINUSE', `Expected EADDRINUSE, got: ${bindError.message}`);
+    }
+    else {
+      const address = server.address();
+      assert.ok(typeof address === 'object' && address.port === 3000);
+    }
+    server.closeAllConnections?.();
+    await new Promise(resolve => {
+      const timer = setTimeout(() => {
+        server.closeAllConnections?.();
+        resolve();
+      }, 1000);
+      server.close(() => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+  }
+  finally {
+    if (savedPort !== undefined) {
+      process.env.PORT = savedPort;
+    }
+    else {
+      delete process.env.PORT;
+    }
+  }
+});
+
 test('startServer starts an HTTPS server when protocol is https', {timeout: 2000}, async () => {
   // Generate a self-signed certificate for the test using openssl.
   const {execSync} = require('node:child_process');
@@ -1094,6 +1173,9 @@ test('startServer starts an HTTPS server when protocol is https', {timeout: 2000
   const savedProtocol = process.env.PROTOCOL;
   const savedKey = process.env.KEY;
   const savedCert = process.env.CERT;
+  // Use port 0 so the OS assigns an ephemeral port, avoiding collisions with production.
+  const savedPort = process.env.PORT;
+  process.env.PORT = '0';
   process.env.PROTOCOL = 'https';
   process.env.KEY = keyPath;
   process.env.CERT = certPath;
@@ -1134,6 +1216,12 @@ test('startServer starts an HTTPS server when protocol is https', {timeout: 2000
     else {
       delete process.env.CERT;
     }
+    if (savedPort !== undefined) {
+      process.env.PORT = savedPort;
+    }
+    else {
+      delete process.env.PORT;
+    }
     fsSync.rmSync(tmpDir, {recursive: true, force: true});
   }
 });

package/package.json

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

package/smokeTest.js

@@ -68,14 +68,16 @@ const postBodies = {
 // Sends an HTTPS request and returns the status code and body length.
 const sendRequest = (method, requestPath) => new Promise((resolve, reject) => {
   const body = method === 'POST' ? JSON.stringify(postBodies[requestPath] || {}) : null;
+  const headers = {'x-kilotest-smoke': '1'};
+  if (body) {
+    headers['content-type'] = 'application/json; charset=utf-8';
+    headers['content-length'] = Buffer.byteLength(body);
+  }
   const options = {
     method,
     host,
     path: requestPath,
-    headers: body ? {
-      'content-type': 'application/json; charset=utf-8',
-      'content-length': Buffer.byteLength(body)
-    } : {}
+    headers
   };
   const req = https.request(options, response => {
     const chunks = [];

package/util.js

@@ -673,12 +673,14 @@ exports.isHidden = async (timeStamp, jobID) => {
 // Returns an extract of an available report, or an error object if it cannot be read or parsed.
 const getReportExtract = exports.getReportExtract = async (timeStamp, jobID) => {
   try {
+    // Get the report.
     const reportJSON = await fs.readFile(
       path.join(reportsPath(), `${timeStamp}-${jobID}.json`), 'utf8'
     );
     const report = JSON.parse(reportJSON);
     const {target, jobData} = report;
     const {what, url} = target;
+    // Return an extract of it.
     return {
       timeStamp,
       jobID,
@@ -695,12 +697,17 @@ const getReportExtract = exports.getReportExtract = async (timeStamp, jobID) =>
 };
 // Returns extracts of all available reports.
 const getReportExtracts = exports.getReportExtracts = async () => {
+  // Get the names of the available report files.
   const reportFileNames = await fs.readdir(reportsPath());
+  // Initialize an array of extracts.
   const extracts = [];
+  // For each one:
   for (const reportFileName of reportFileNames) {
     const [timeStamp, jobID] = reportFileName.slice(0, -5).split('-');
+    // Get an extract of it.
     const extract = await getReportExtract(timeStamp, jobID);
     if (!extract.error) {
+      // Add the extract to the array.
       extracts.push(extract);
     }
   }
@@ -715,11 +722,15 @@ exports.isReportAvailable = async (what, url) => {
 };
 // Gets extracts of the latest available reports for all page descriptions.
 exports.getLatestReportExtracts = async () => {
+  // Get extracts of all available reports.
   const reportExtracts = await getReportExtracts();
+  // Sort them by page description and, secondarily, completion time.
   objectSort(reportExtracts, 'reportTime', 'alpha');
   objectSort(reportExtracts, 'what', 'alpha');
+  // Get those that are not superseded.
   const latestReportExtracts = reportExtracts
   .filter((extract, index) => extract.what !== reportExtracts[index + 1]?.what);
+  // Return them.
   return latestReportExtracts;
 };
 // Gets the descriptions of multi-report pages.