@jrpool/kilotest 46.0.6 → 46.0.8

package/.github/workflows/smoke-test.yml

@@ -0,0 +1,26 @@
+name: Smoke Test
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set Node.js version
+        uses: actions/setup-node@v4
+        with:
+          node-version: '>=22.12.0'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run smoke test against deployed server
+        run: node smokeTest.js

package/apiIntegration.test.js

@@ -0,0 +1,82 @@
+/*
+  apiIntegration.test.js
+  Minimal HTTP integration tests verifying routing, body parsing, and JSON serialization, using the fixture corpus and a temporary in-process server.
+*/
+
+// IMPORTS
+
+const {test, before, after} = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const http = require('node:http');
+const {requestHandler} = require('./index');
+
+// CONSTANTS
+
+const port = 3998;
+
+// SETUP AND TEARDOWN
+
+const savedDBDir = process.env.DB_DIR;
+let server;
+
+before(async () => {
+  process.env.DB_DIR = path.join(__dirname, 'test', 'fixtures', 'db');
+  server = http.createServer(requestHandler);
+  await new Promise(resolve => server.listen(port, resolve));
+});
+
+after(async () => {
+  if (savedDBDir !== undefined) {
+    process.env.DB_DIR = savedDBDir;
+  }
+  else {
+    delete process.env.DB_DIR;
+  }
+  await new Promise(resolve => server.close(() => resolve()));
+});
+
+// HELPERS
+
+// Sends an HTTP request and returns the parsed JSON response body.
+const request = (method, requestPath, body = null) => new Promise((resolve, reject) => {
+  const options = {method, host: 'localhost', port, path: requestPath};
+  if (body) {
+    const bodyJSON = JSON.stringify(body);
+    options.headers = {
+      'content-type': 'application/json; charset=utf-8',
+      'content-length': Buffer.byteLength(bodyJSON)
+    };
+  }
+  const req = http.request(options, response => {
+    const chunks = [];
+    response.on('data', chunk => chunks.push(chunk));
+    response.on('end', () => {
+      const bodyString = chunks.join('');
+      try {
+        resolve({statusCode: response.statusCode, body: JSON.parse(bodyString)});
+      }
+      catch {
+        resolve({statusCode: response.statusCode, body: bodyString});
+      }
+    });
+  });
+  req.on('error', reject);
+  req.end(body ? JSON.stringify(body) : '');
+});
+
+// TESTS
+
+test('GET /api/listReports returns valid JSON through the HTTP routing layer', async () => {
+  const {body} = await request('GET', '/api/listReports');
+  assert.equal(body['tool name'], 'listReports');
+  const reports = body['response content']['basics about all available reports'];
+  assert.equal(reports.length, 6);
+});
+
+test('POST /api/requestFeature parses a JSON body and returns a JSON response through the HTTP routing layer', async () => {
+  const {body} = await request('POST', '/api/requestFeature', {feature: 'Add a dark mode toggle'});
+  const details = body['response content']['details about your request'];
+  assert.equal(details.error, undefined);
+  assert.equal(details.disposition, 'received and logged; manager notified');
+});

package/docs/SERVICE.md

@@ -203,7 +203,7 @@ kilotest.com {
   }
   @allowedPOST {
     method POST
-    path /mcp /requestRetest.html/* /requestTest.html /recAction.html /reannotate.html /renewWCAG.html /api/* /tutorialComment.html
+    path /mcp /requestRetest.html/* /requestTest.html /recAction.html /reannotate.html /renewWCAG.html /api/* /tutorialComment.html /worker/job /worker/report
   }
   # Respond to OPTIONS requests.
   @allowedOPTIONS method OPTIONS
@@ -259,6 +259,30 @@ When a new version of the `kilotest` package has been published, the service can
 1. Update the Playwright browsers: `npx playwright install`
 1. Restart the service: `pm2 restart kilotest`
 
+## Branch protection
+
+The `main` branch on GitHub is protected to prevent direct pushes and to require a passing smoke test before any pull request can merge. The settings are configured in the GitHub repository as a ruleset under Settings > Branches > Branch protection rules.
+
+The required settings are:
+
+1. Require a pull request before merging.
+1. Require status checks to pass before merging.
+1. Add "Smoke Test" as a required status check.
+1. Require branches to be up to date before merging.
+1. Do not allow bypassing the above settings.
+
+A copy of the ruleset is located at `docs/Smoke Test.json`.
+
+The smoke-test check is defined in `.github/workflows/smoke-test.yml` and runs `smokeTest.js`, which sends HTTPS requests to all valid GET and POST paths on the deployed server and verifies that Caddy forwards each one to Kilotest rather than returning a bare 404.
+
+When a pull request adds a new route to `index.js`, the Caddyfile at `/etc/caddy/Caddyfile` on the server must be updated to forward the new path before the pull request can merge. The workflow to follow is:
+
+1. Add the new route to the `routes` constant and the dispatch chain in `index.js`.
+1. Update the Caddyfile (`/etc/caddy/Caddyfile`) on the server to forward the new path.
+1. Open or update the pull request.
+1. The smoke test workflow runs and verifies that all paths, including the new one, are forwarded by Caddy.
+1. If the Caddyfile was not updated, the smoke test reports a bare 404 for the new path, the required status check fails, and the pull request cannot merge.
+
 ## Performance
 
 The Cloud Compute host, in initial testing, took about 2.5 as long to process an example job as an Apple M2 Pro MacBook Pro with 16GB of memory. After tuning, the ratio was reduced to about 1.7.

package/docs/Smoke Test.json

@@ -0,0 +1,54 @@
+{
+  "id": 22391521,
+  "name": "Smoke Test",
+  "target": "branch",
+  "source_type": "Repository",
+  "source": "jrpool/kilotest",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "exclude": [],
+      "include": [
+        "~DEFAULT_BRANCH"
+      ]
+    }
+  },
+  "rules": [
+    {
+      "type": "deletion"
+    },
+    {
+      "type": "non_fast_forward"
+    },
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 0,
+        "dismiss_stale_reviews_on_push": true,
+        "required_reviewers": [],
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": false,
+        "require_extra_approval_for_unattributed_changes": true,
+        "allowed_merge_methods": [
+          "merge",
+          "squash",
+          "rebase"
+        ]
+      }
+    },
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": true,
+        "do_not_enforce_on_create": false,
+        "required_status_checks": [
+          {
+            "context": "Smoke Test"
+          }
+        ]
+      }
+    }
+  ],
+  "bypass_actors": []
+}

package/index.js

@@ -63,6 +63,54 @@ const answer = {
 
 // CONSTANTS
 
+// Paths that the application is authorized to handle, by method, as glob-style patterns where * matches any sequence of characters.
+const routes = exports.routes = {
+  GET: [
+    '/mcp',
+    '/',
+    '/index.html',
+    '/robots.txt',
+    '/openapi.yaml',
+    '/openapi.json',
+    '/swagger.yaml',
+    '/swagger.json',
+    '/api-docs',
+    '/llms.txt',
+    '/llms-full.txt',
+    '/sitemap.xml',
+    '/style.css',
+    '/fullReport.json/*',
+    '/api/*',
+    '/tutorial/images/*',
+    '/favicon.*',
+    '*.html*'
+  ],
+  POST: [
+    '/mcp',
+    '/requestTest.html',
+    '/requestRetest.html/*',
+    '/recAction.html',
+    '/reannotate.html',
+    '/renewWCAG.html',
+    '/worker/job',
+    '/worker/report',
+    '/api/*',
+    '/tutorialComment.html'
+  ]
+};
+// Returns whether a pathname matches a glob-style pattern.
+const matchPath = (pattern, pathname) => {
+  const regex = new RegExp(
+    '^' + pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') + '$'
+  );
+  return regex.test(pathname);
+};
+// Returns whether a pathname is authorized for a method.
+const isPathAllowed = (method, pathname) => {
+  const patterns = routes[method] || [];
+  return patterns.some(pattern => matchPath(pattern, pathname));
+};
+
 const protocol = process.env.PROTOCOL || 'http';
 const queuePath = () => path.join(jobsPath(), 'queue');
 const claimedPath = () => path.join(jobsPath(), 'claimed');
@@ -321,8 +369,12 @@ const requestHandler = async (request, response) => {
   const pathTail = pathname.split('/').slice(2).join('/');
   // If the request is a GET request:
   if (method === 'GET') {
+    // If the path is not authorized for GET requests:
+    if (!isPathAllowed('GET', pathname)) {
+      await serveError({message: `ERROR: Invalid GET request (${pathname})`}, response, true);
+    }
     // If it is for the model context protocol server:
-    if (pathname === mcpPath) {
+    else if (pathname === mcpPath) {
       // Handle the MCP request.
       await handleMCP(request, response);
     }
@@ -554,8 +606,12 @@ const requestHandler = async (request, response) => {
   }
   // Otherwise, if the request is a POST request:
   else if (method === 'POST') {
+    // If the path is not authorized for POST requests:
+    if (!isPathAllowed('POST', pathname)) {
+      await serveError({message: 'ERROR: Invalid POST request'}, response, true);
+    }
     // If it is for the model context protocol server:
-    if (pageName === 'mcp') {
+    else if (pageName === 'mcp') {
       await handleMCP(request, response);
     }
     // Otherwise, i.e. if it is not for the MCP server:
@@ -861,6 +917,10 @@ const requestHandler = async (request, response) => {
   }
 };
 
+// EXPORTS
+
+exports.requestHandler = requestHandler;
+
 // SERVER
 
 const serve = async (protocolModule, options) => {
@@ -879,23 +939,25 @@ const serve = async (protocolModule, options) => {
 
 // EXECUTION
 
-if (protocol === 'http') {
-  console.log('Starting HTTP server');
-  serve(http, {});
-}
-else if (protocol === 'https') {
-  console.log('Starting HTTPS server');
-  fs.readFile(process.env.KEY, 'utf8')
-  .then(
-    key => {
-      fs.readFile(process.env.CERT, 'utf8')
-      .then(
-        cert => {
-          serve(https, {key, cert});
-        },
-        error => console.log(error.message)
-      );
-    },
-    error => console.log(error.message)
-  );
+if (require.main === module) {
+  if (protocol === 'http') {
+    console.log('Starting HTTP server');
+    serve(http, {});
+  }
+  else if (protocol === 'https') {
+    console.log('Starting HTTPS server');
+    fs.readFile(process.env.KEY, 'utf8')
+    .then(
+      key => {
+        fs.readFile(process.env.CERT, 'utf8')
+        .then(
+          cert => {
+            serve(https, {key, cert});
+          },
+          error => console.log(error.message)
+        );
+      },
+      error => console.log(error.message)
+    );
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "46.0.6",
+  "version": "46.0.8",
   "description": "Ensemble testing for front-end web quality",
   "main": "index.js",
   "engines": {
@@ -10,7 +10,7 @@
     "start": "node index",
     "lint": "npx eslint && npx markdownlint-cli2",
     "test": "c8 node --test",
-    "test:api": "node api/testSuite",
+    "test:smoke": "node smokeTest",
     "generate:openapi": "node scripts/generate-openapi"
   },
   "repository": {
@@ -49,6 +49,7 @@
     "globals": "*",
     "js-yaml": "*",
     "markdownlint-cli2": "*",
+    "node-html-parser": "*",
     "zod-openapi": "*"
   },
   "allowScripts": {

package/routes.test.js

@@ -0,0 +1,69 @@
+/*
+  routes.test.js
+  Tests for the centralized routes table exported from index.js.
+*/
+
+// IMPORTS
+
+const {test} = require('node:test');
+const assert = require('node:assert/strict');
+const {routes} = require('./index');
+
+// TESTS
+
+test('routes has GET and POST arrays', () => {
+  assert.ok(Array.isArray(routes.GET));
+  assert.ok(Array.isArray(routes.POST));
+  assert.ok(routes.GET.length > 0);
+  assert.ok(routes.POST.length > 0);
+});
+
+test('routes GET includes all known GET paths', () => {
+  const required = [
+    '/mcp',
+    '/',
+    '/index.html',
+    '/robots.txt',
+    '/openapi.yaml',
+    '/openapi.json',
+    '/swagger.yaml',
+    '/swagger.json',
+    '/api-docs',
+    '/llms.txt',
+    '/llms-full.txt',
+    '/sitemap.xml',
+    '/style.css'
+  ];
+  for (const path of required) {
+    assert.ok(routes.GET.includes(path), `routes.GET missing ${path}`);
+  }
+});
+
+test('routes POST includes all known POST paths', () => {
+  const required = [
+    '/mcp',
+    '/requestTest.html',
+    '/recAction.html',
+    '/reannotate.html',
+    '/renewWCAG.html',
+    '/worker/job',
+    '/worker/report',
+    '/tutorialComment.html'
+  ];
+  for (const path of required) {
+    assert.ok(routes.POST.includes(path), `routes.POST missing ${path}`);
+  }
+});
+
+test('routes GET includes wildcard patterns for dynamic paths', () => {
+  assert.ok(routes.GET.some(p => p.includes('fullReport.json')));
+  assert.ok(routes.GET.some(p => p.includes('/api/')));
+  assert.ok(routes.GET.some(p => p.includes('tutorial/images')));
+  assert.ok(routes.GET.some(p => p.includes('favicon')));
+  assert.ok(routes.GET.some(p => p.includes('.html')));
+});
+
+test('routes POST includes wildcard patterns for dynamic paths', () => {
+  assert.ok(routes.POST.some(p => p.includes('requestRetest.html')));
+  assert.ok(routes.POST.some(p => p.includes('/api/')));
+});

package/routing.test.js

@@ -0,0 +1,77 @@
+/*
+  routing.test.js
+  Integration tests for HTTP routing in index.js, verifying that POST-only API services reject GET requests.
+*/
+
+// IMPORTS
+
+const {test, before, after} = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const http = require('node:http');
+const {requestHandler} = require('./index');
+
+// CONSTANTS
+
+const port = 3999;
+
+// SETUP AND TEARDOWN
+
+const savedDBDir = process.env.DB_DIR;
+let server;
+
+before(async () => {
+  process.env.DB_DIR = path.join(__dirname, 'test', 'fixtures', 'db');
+  server = http.createServer(requestHandler);
+  await new Promise(resolve => server.listen(port, resolve));
+});
+
+after(async () => {
+  if (savedDBDir !== undefined) {
+    process.env.DB_DIR = savedDBDir;
+  }
+  else {
+    delete process.env.DB_DIR;
+  }
+  await new Promise(resolve => server.close(() => resolve()));
+});
+
+// HELPERS
+
+// Sends a GET request and returns the response body as a string.
+const get = requestPath => new Promise((resolve, reject) => {
+  http.request({method: 'GET', host: 'localhost', port, path: requestPath}, response => {
+    const chunks = [];
+    response.on('data', chunk => chunks.push(chunk));
+    response.on('end', () => {
+      resolve({statusCode: response.statusCode, body: chunks.join('')});
+    });
+  })
+  .on('error', reject)
+  .end();
+});
+
+// TESTS
+
+test('GET /api/requestTest returns an error, not a test-request response', async () => {
+  const result = await get('/api/requestTest');
+  assert.ok(result.body.includes('Invalid service request'));
+});
+
+test('GET /api/requestRetest returns an error, not a retest-request response', async () => {
+  const result = await get('/api/requestRetest/260101T0001/ct');
+  assert.ok(result.body.includes('Invalid service request'));
+});
+
+test('GET /api/requestFeature returns an error, not a feature-request response', async () => {
+  const result = await get('/api/requestFeature');
+  assert.ok(result.body.includes('Invalid service request'));
+});
+
+test('GET /api/listReports returns a valid JSON response', async () => {
+  const result = await get('/api/listReports');
+  const body = JSON.parse(result.body);
+  assert.equal(body['tool name'], 'listReports');
+  const reports = body['response content']['basics about all available reports'];
+  assert.equal(reports.length, 6);
+});

package/smokeTest.js

@@ -0,0 +1,123 @@
+/*
+  smokeTest.js
+  Sends requests to all valid GET and POST paths on the deployed server and verifies that Caddy forwards them to Kilotest (i.e., the response is not a bare Caddy 404).
+*/
+
+// IMPORTS
+
+const https = require('https');
+const {routes} = require('./index');
+
+// CONSTANTS
+
+const host = process.env.SMOKE_HOST || 'kilotest.com';
+// Concrete paths matching each wildcard pattern in the routes table, for smoke testing.
+const concretePaths = {
+  GET: {
+    '/mcp': '/mcp',
+    '/': '/',
+    '/index.html': '/index.html',
+    '/robots.txt': '/robots.txt',
+    '/openapi.yaml': '/openapi.yaml',
+    '/openapi.json': '/openapi.json',
+    '/swagger.yaml': '/swagger.yaml',
+    '/swagger.json': '/swagger.json',
+    '/api-docs': '/api-docs',
+    '/llms.txt': '/llms.txt',
+    '/llms-full.txt': '/llms-full.txt',
+    '/sitemap.xml': '/sitemap.xml',
+    '/style.css': '/style.css',
+    '/fullReport.json/*': '/fullReport.json/260101T0000/mix',
+    '/api/*': '/api/listReports',
+    '/tutorial/images/*': '/tutorial/images/diagram.png',
+    '/favicon.*': '/favicon.ico',
+    '*.html*': '/listReports.html'
+  },
+  POST: {
+    '/mcp': '/mcp',
+    '/requestTest.html': '/requestTest.html',
+    '/requestRetest.html/*': '/requestRetest.html/260101T0001/ct',
+    '/recAction.html': '/recAction.html',
+    '/reannotate.html': '/reannotate.html',
+    '/renewWCAG.html': '/renewWCAG.html',
+    '/worker/job': '/worker/job',
+    '/worker/report': '/worker/report',
+    '/api/*': '/api/requestFeature',
+    '/tutorialComment.html': '/tutorialComment.html'
+  }
+};
+// Minimal POST bodies for paths that require them.
+const postBodies = {
+  '/api/requestFeature': {feature: 'smoke test'},
+  '/requestTest.html': {what: 'Smoke Test Page', url: 'https://smoketest.example.com', why: 'smoke test'},
+  '/requestRetest.html/260101T0001/ct': {why: 'smoke test'},
+  '/recAction.html': {target: 'https://smoketest.example.com\tSmoke Test Page', authCode: 'invalid'},
+  '/reannotate.html': {authCode: 'invalid'},
+  '/renewWCAG.html': {authCode: 'invalid'},
+  '/worker/job': {},
+  '/worker/report': {},
+  '/tutorialComment.html': {content: 'smoke test'},
+  '/mcp': {}
+};
+
+// FUNCTIONS
+
+// 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 options = {
+    method,
+    host,
+    path: requestPath,
+    headers: body ? {
+      'content-type': 'application/json; charset=utf-8',
+      'content-length': Buffer.byteLength(body)
+    } : {}
+  };
+  const req = https.request(options, response => {
+    const chunks = [];
+    response.on('data', chunk => chunks.push(chunk));
+    response.on('end', () => {
+      const responseBody = chunks.join('');
+      resolve({statusCode: response.statusCode, bodyLength: responseBody.length});
+    });
+  });
+  req.on('error', reject);
+  req.end(body || '');
+});
+
+// Returns whether a response is a bare Caddy 404 (the failure this test detects).
+const isCaddy404 = result => result.statusCode === 404 && result.bodyLength === 0;
+
+// EXECUTION
+
+(async () => {
+  let failures = 0;
+  for (const method of ['GET', 'POST']) {
+    console.log(`\n=== ${method} paths ===`);
+    for (const pattern of routes[method]) {
+      const requestPath = concretePaths[method][pattern];
+      if (!requestPath) {
+        console.log(`FAIL: no concrete path defined for pattern ${pattern}`);
+        failures++;
+        continue;
+      }
+      try {
+        const result = await sendRequest(method, requestPath);
+        if (isCaddy404(result)) {
+          console.log(`FAIL: ${method} ${requestPath} -> Caddy 404 (path not forwarded)`);
+          failures++;
+        }
+        else {
+          console.log(`PASS: ${method} ${requestPath} -> ${result.statusCode} (body ${result.bodyLength} bytes)`);
+        }
+      }
+      catch (error) {
+        console.log(`FAIL: ${method} ${requestPath} -> error: ${error.message}`);
+        failures++;
+      }
+    }
+  }
+  console.log(`\n=== ${failures === 0 ? 'All paths forwarded' : `${failures} failure(s)`} ===`);
+  process.exit(failures === 0 ? 0 : 1);
+})();

package/web/listDiagnoses/listDiagnoses.test.js

@@ -0,0 +1,74 @@
+/*
+  listDiagnoses.test.js
+  UI tests for web/listDiagnoses/index.js using the fixture corpus.
+*/
+
+// IMPORTS
+
+const {test, before, after} = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const {parse} = require('node-html-parser');
+const {answer} = require('./index');
+
+// SETUP AND TEARDOWN
+
+const savedDBDir = process.env.DB_DIR;
+
+before(() => {
+  process.env.DB_DIR = path.join(__dirname, '..', '..', 'test', 'fixtures', 'db');
+});
+
+after(() => {
+  if (savedDBDir !== undefined) {
+    process.env.DB_DIR = savedDBDir;
+  }
+  else {
+    delete process.env.DB_DIR;
+  }
+});
+
+// TESTS
+
+test('listDiagnoses returns an ok status with valid HTML for catalogIndex 0, linkNoText, in the mixed report', async () => {
+  const result = await answer('linkNoText/260101T0000/mix/0');
+  assert.equal(result.status, 'ok');
+  assert.ok(result.answerPage);
+  const html = parse(result.answerPage);
+  assert.ok(html.querySelector('title'));
+});
+
+test('listDiagnoses includes the issue summary in the HTML', async () => {
+  const result = await answer('linkNoText/260101T0000/mix/0');
+  assert.ok(result.answerPage.includes('link not named'));
+});
+
+test('listDiagnoses includes the element tag name and text from the catalog', async () => {
+  const result = await answer('linkNoText/260101T0000/mix/0');
+  assert.ok(result.answerPage.includes('About Us'));
+});
+
+test('listDiagnoses includes diagnosis descriptions from the rule engines', async () => {
+  const result = await answer('linkNoText/260101T0000/mix/0');
+  assert.ok(result.answerPage.includes('The link does not have an accessible name'));
+});
+
+test('listDiagnoses returns an error status for a hidden report', async () => {
+  const result = await answer('linkNoText/260101T0007/hid/0');
+  assert.equal(result.status, 'error');
+});
+
+test('listDiagnoses returns an error status for a nonexistent report', async () => {
+  const result = await answer('linkNoText/999999T9999/xyz/0');
+  assert.equal(result.status, 'error');
+});
+
+test('listDiagnoses returns ok with no diagnoses for a nonexistent catalog index', async () => {
+  const result = await answer('linkNoText/260101T0000/mix/999');
+  assert.equal(result.status, 'ok');
+  const html = parse(result.answerPage);
+  const diagnosisItems = html.querySelectorAll('li');
+  // The page may have other li elements, but none should contain diagnosis descriptions.
+  const diagnosisTexts = diagnosisItems.map(li => li.text);
+  assert.ok(!diagnosisTexts.some(t => t.includes('The link does not have an accessible name')));
+});

package/web/listIssues/index.js

@@ -64,9 +64,9 @@ const getIssuesData = async (timeStamp, jobID) => {
         const instances = result?.standardResult?.instances ?? [];
         // For each of its standard instances:
         instances.forEach(instance => {
-          const {catalogIndex, issueID} = instance;
-          // If the instance identifies its rule as belonging to a non-ignorable issue:
-          if (issueID && issueID !== 'ignorable') {
+          const {catalogIndex, issueID, outcome} = instance;
+          // If the instance reports a violation and identifies a non-ignorable issue:
+          if (outcome !== 'cantTell' && issueID && issueID !== 'ignorable') {
             const issueClassification = issueSpecs[issueID];
             // If the issue has a current weighted classification:
             if (issueClassification && [1, 2, 3, 4].includes(issueClassification.weight)) {

package/web/listIssues/listIssues.test.js

@@ -0,0 +1,80 @@
+/*
+  listIssues.test.js
+  UI tests for web/listIssues/index.js using the fixture corpus.
+*/
+
+// IMPORTS
+
+const {test, before, after} = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const {parse} = require('node-html-parser');
+const {answer} = require('./index');
+
+// SETUP AND TEARDOWN
+
+const savedDBDir = process.env.DB_DIR;
+
+before(() => {
+  process.env.DB_DIR = path.join(__dirname, '..', '..', 'test', 'fixtures', 'db');
+});
+
+after(() => {
+  if (savedDBDir !== undefined) {
+    process.env.DB_DIR = savedDBDir;
+  }
+  else {
+    delete process.env.DB_DIR;
+  }
+});
+
+// TESTS
+
+test('listIssues returns an ok status with valid HTML for the mixed report', async () => {
+  const result = await answer('260101T0000/mix');
+  assert.equal(result.status, 'ok');
+  assert.ok(result.answerPage);
+  const html = parse(result.answerPage);
+  assert.ok(html.querySelector('title'));
+});
+
+test('listIssues includes the page description in the HTML for the mixed report', async () => {
+  const result = await answer('260101T0000/mix');
+  assert.ok(result.answerPage.includes('Mixed Outcomes Page'));
+});
+
+test('listIssues includes links to listViolators for issues in the mixed report', async () => {
+  const result = await answer('260101T0000/mix');
+  const html = parse(result.answerPage);
+  const violatorLinks = html.querySelectorAll('a[href*="listViolators.html"]');
+  assert.ok(violatorLinks.length >= 2);
+  const hrefs = violatorLinks.map(a => a.getAttribute('href'));
+  assert.ok(hrefs.some(href => href.includes('linkNoText')));
+  assert.ok(hrefs.some(href => href.includes('allCaps')));
+});
+
+test('listIssues returns an error status for a hidden report', async () => {
+  const result = await answer('260101T0007/hid');
+  assert.equal(result.status, 'error');
+});
+
+test('listIssues returns an error status for a nonexistent report', async () => {
+  const result = await answer('999999T9999/xyz');
+  assert.equal(result.status, 'error');
+});
+
+test('listIssues for the all-cantTell report shows no issue links', async () => {
+  const result = await answer('260101T0001/ct');
+  assert.equal(result.status, 'ok');
+  const html = parse(result.answerPage);
+  const violatorLinks = html.querySelectorAll('a[href*="listViolators.html"]');
+  assert.equal(violatorLinks.length, 0);
+});
+
+test('listIssues for the empty report shows no issue links', async () => {
+  const result = await answer('260101T0005/emp');
+  assert.equal(result.status, 'ok');
+  const html = parse(result.answerPage);
+  const violatorLinks = html.querySelectorAll('a[href*="listViolators.html"]');
+  assert.equal(violatorLinks.length, 0);
+});

package/web/listReports/listReports.test.js

@@ -0,0 +1,84 @@
+/*
+  listReports.test.js
+  UI tests for web/listReports/index.js using the fixture corpus.
+*/
+
+// IMPORTS
+
+const {test, before, after} = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const {parse} = require('node-html-parser');
+const {answer} = require('./index');
+
+// SETUP AND TEARDOWN
+
+const savedDBDir = process.env.DB_DIR;
+
+before(() => {
+  process.env.DB_DIR = path.join(__dirname, '..', '..', 'test', 'fixtures', 'db');
+});
+
+after(() => {
+  if (savedDBDir !== undefined) {
+    process.env.DB_DIR = savedDBDir;
+  }
+  else {
+    delete process.env.DB_DIR;
+  }
+});
+
+// TESTS
+
+test('listReports returns an ok status with valid HTML', async () => {
+  const result = await answer();
+  assert.equal(result.status, 'ok');
+  assert.ok(result.answerPage);
+  const html = parse(result.answerPage);
+  assert.equal(html.querySelector('title').text, 'Pages tested | Kilotest');
+});
+
+test('listReports includes the 6 non-hidden fixture reports as details elements', async () => {
+  const result = await answer();
+  const html = parse(result.answerPage);
+  const details = html.querySelectorAll('details');
+  assert.equal(details.length, 6);
+});
+
+test('listReports includes the page descriptions in summary elements', async () => {
+  const result = await answer();
+  const html = parse(result.answerPage);
+  const summaries = html.querySelectorAll('details > summary').map(s => s.text);
+  assert.ok(summaries.some(s => s.startsWith('Mixed Outcomes Page')));
+  assert.ok(summaries.some(s => s.startsWith('All CantTell Page')));
+  assert.ok(summaries.some(s => s.startsWith('No Outcomes Page')));
+  assert.ok(summaries.some(s => s.startsWith('Empty Results Page')));
+  assert.ok(summaries.some(s => s.startsWith('Prevented Page')));
+});
+
+test('listReports does not include the hidden report', async () => {
+  const result = await answer();
+  assert.ok(!result.answerPage.includes('Hidden Page'));
+});
+
+test('listReports includes links to listIssues for reports with issues', async () => {
+  const result = await answer();
+  const html = parse(result.answerPage);
+  const issueLinks = html.querySelectorAll('a[href*="listIssues.html"]');
+  assert.ok(issueLinks.length > 0);
+  const hrefs = issueLinks.map(a => a.getAttribute('href'));
+  assert.ok(hrefs.some(href => href.includes('260101T0000/mix')));
+});
+
+test('listReports includes the page URLs in the report details', async () => {
+  const result = await answer();
+  assert.ok(result.answerPage.includes('https://example.com/mixed'));
+  assert.ok(result.answerPage.includes('https://example.com/canttell'));
+});
+
+test('listReports includes a link to request testing a new page', async () => {
+  const result = await answer();
+  const html = parse(result.answerPage);
+  const testLink = html.querySelector('a[href="requestTestForm.html"]');
+  assert.ok(testLink);
+});

package/web/listViolators/listViolators.test.js

@@ -0,0 +1,66 @@
+/*
+  listViolators.test.js
+  UI tests for web/listViolators/index.js using the fixture corpus.
+*/
+
+// IMPORTS
+
+const {test, before, after} = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const {parse} = require('node-html-parser');
+const {answer} = require('./index');
+
+// SETUP AND TEARDOWN
+
+const savedDBDir = process.env.DB_DIR;
+
+before(() => {
+  process.env.DB_DIR = path.join(__dirname, '..', '..', 'test', 'fixtures', 'db');
+});
+
+after(() => {
+  if (savedDBDir !== undefined) {
+    process.env.DB_DIR = savedDBDir;
+  }
+  else {
+    delete process.env.DB_DIR;
+  }
+});
+
+// TESTS
+
+test('listViolators returns an ok status with valid HTML for linkNoText in the mixed report', async () => {
+  const result = await answer('linkNoText/260101T0000/mix');
+  assert.equal(result.status, 'ok');
+  assert.ok(result.answerPage);
+  const html = parse(result.answerPage);
+  assert.ok(html.querySelector('title'));
+});
+
+test('listViolators includes the issue summary in the HTML', async () => {
+  const result = await answer('linkNoText/260101T0000/mix');
+  assert.ok(result.answerPage.includes('link not named'));
+});
+
+test('listViolators includes links to listDiagnoses for violators', async () => {
+  const result = await answer('linkNoText/260101T0000/mix');
+  const html = parse(result.answerPage);
+  const diagnosisLinks = html.querySelectorAll('a[href*="listDiagnoses.html"]');
+  assert.ok(diagnosisLinks.length > 0);
+});
+
+test('listViolators returns an error status for a hidden report', async () => {
+  const result = await answer('linkNoText/260101T0007/hid');
+  assert.equal(result.status, 'error');
+});
+
+test('listViolators returns an error status for a nonexistent report', async () => {
+  const result = await answer('linkNoText/999999T9999/xyz');
+  assert.equal(result.status, 'error');
+});
+
+test('listViolators returns an error status for an unknown issue', async () => {
+  const result = await answer('nonexistentIssue/260101T0000/mix');
+  assert.equal(result.status, 'error');
+});

package/api/testSuite.js

@@ -1,311 +0,0 @@
-/*
-  © 2026 Jonathan Robert Pool.
-
-  Licensed under the MIT License. See LICENSE file at the project root or
-  https://opensource.org/license/mit/ for details.
-
-  SPDX-License-Identifier: MIT
-*/
-
-/*
-  researchAgent.js
-  Simulates a research agent.
-*/
-
-// IMPORTS
-
-require('dotenv').config();
-const httpClient = require('http');
-const httpsClient = require('https');
-
-// CONSTANTS
-
-const kilotestHosts = [
-  process.env.LOCAL_KILOTEST_HOST || 'http://localhost:3000',
-  process.env.DEPLOYED_KILOTEST_HOST || 'https://kilotest.com'
-];
-// Kilotest host specified by the argument.
-const kilotestHost = kilotestHosts[process.argv[2] === 'pub' ? 1 : 0];
-const hostParts = kilotestHost.split(/:\/*/);
-const scheme = hostParts[0] === 'https' ? 'https' : 'http';
-const client = scheme === 'https' ? httpsClient : httpClient;
-const host = hostParts[1] || 'localhost';
-const port = hostParts[2] || (scheme === 'https' ? 443 : 80);
-
-// FUNCTIONS
-
-// Gets, parses into an object, and returns the body of a response.
-const getBody = async response => {
-  const body = await new Promise(resolve => {
-    // Initialize an array of data from the response.
-    const chunks = [];
-    response
-    // If the response throws an error:
-    .on('error', error => {
-      const {message} = error;
-      // Report and return the error message.
-      console.log(message);
-      resolve({error: message});
-    })
-    // Whenever the response delivers data:
-    .on('data', chunk => {
-      // Add them to the array.
-      chunks.push(chunk);
-    })
-    // When the response is completed:
-    .on('end', () => {
-      const bodyString = chunks.join('');
-      try {
-        const body = JSON.parse(bodyString);
-        // Return the response body as an object.
-        resolve(body);
-      }
-      // If it is not JSON:
-      catch {
-        // Return this.
-        resolve({error: `Response body not JSON (${bodyString})`});
-      }
-    });
-  });
-  return body;
-};
-const getRequestOptions = (path, method = 'GET') => ({
-  method,
-  host,
-  port,
-  path,
-  headers: {
-    'body-type': 'application/json; charset=utf-8'
-  }
-});
-// Submits a request, returns the response body, and increments the results.
-const submitRequest = async (path, method, requestBody = null) => new Promise(resolve => {
-  console.log(`Making ${scheme} ${method} request on port ${port} of ${host} to ${path}`);
-  client.request(getRequestOptions(path, method), async response => {
-    const responseBody = await getBody(response);
-    resolve(responseBody);
-  })
-  .on('error', error => {
-    console.log(`ERROR submitting request (${JSON.stringify(error, null, 2)})`);
-    resolve({error});
-  })
-  .end(requestBody ? JSON.stringify(requestBody) : '');
-});
-// Submits requests to the specified Kilotest host.
-const requestService = async () => {
-  let body;
-  let jobID;
-  let method;
-  let path;
-  let reportBasics;
-  let reportsBasics;
-  let requestDetails;
-  let requestDisposition;
-  let responseContent;
-  let timeStamp;
-  console.log('======================\nRequest: List all available reports');
-  method = 'GET';
-  path = '/api/listReports';
-  body = await submitRequest(path, method);
-  responseContent = body?.['response content'] ?? {};
-  reportsBasics = responseContent?.['basics about all available reports'] ?? [];
-  if (
-    !reportsBasics.length
-    || !Array.isArray(reportsBasics)
-    || !reportsBasics.length
-    || reportsBasics.some(
-      reportBasics => reportBasics['how to get details about the report']?.method !== 'GET'
-    )
-  ) {
-    console.log(`reportsBasics: ${JSON.stringify(reportsBasics, null, 2)}`);
-    return;
-  }
-  console.log('======================\nRequest: List issues in one nonexistent report');
-  [timeStamp, jobID] = ['111111T1111', 'abc'];
-  method = 'GET';
-  path = `/api/listIssues/${timeStamp}/${jobID}`;
-  body = await submitRequest(path, method);
-  responseContent = body?.['response content'] ?? {};
-  reportBasics = responseContent?.['basics about the report'] ?? {};
-  if (
-    !reportBasics.error || !reportBasics.error.includes('missing, unreadable, or not JSON')
-  ) {
-    console.log(`reportBasics: ${JSON.stringify(reportBasics, null, 2)}`);
-    return;
-  }
-  console.log('======================\nRequest: List issues in one report');
-  const reportsBasicsIndex = Math.floor(reportsBasics.length * Math.random());
-  // Choose one report at random.
-  reportBasics = reportsBasics[reportsBasicsIndex];
-  // Get whether the report has been superseded by a later report about the same page.
-  const isSuperseded = reportBasics['whether a later report about the same page exists'];
-  [timeStamp, jobID] = reportBasics.identifier?.split('-') || [null, null];
-  if (!(timeStamp && jobID)) {
-    console.log(`reportBasicsIndex: ${reportsBasicsIndex}`);
-    console.log(`reportBasics: ${JSON.stringify(reportBasics, null, 2)}`);
-    return;
-  }
-  path = `/api/listIssues/${timeStamp}/${jobID}`;
-  body = await submitRequest(path, method);
-  responseContent = body?.['response content'] ?? {};
-  const issuesBasics = responseContent?.['basics about all issues reported in the report'] ?? [];
-  if (
-    !issuesBasics.length
-    || !Array.isArray(issuesBasics)
-    || !issuesBasics.length
-    || issuesBasics.some(issueBasics => !issueBasics['impact on a user'])
-  ) {
-    console.log(`issuesBasics: ${JSON.stringify(issuesBasics, null, 2)}`);
-    return;
-  }
-  console.log('======================\nRequest: List violators of one issue in one report');
-  // Get the issue IDs.
-  const issueIDs = issuesBasics.map(issueBasics => issueBasics.identifier);
-  // Choose one at random.
-  const issueID = issueIDs[Math.floor(Math.random() * issueIDs.length)];
-  path = `/api/listViolators/${issueID}/${timeStamp}/${jobID}`;
-  body = await submitRequest(path, method);
-  responseContent = body?.['response content'] ?? {};
-  const violatorsBasics = responseContent?.['basics about all elements exhibiting the issue'] ?? [];
-  if (
-    !violatorsBasics.length
-    || !Array.isArray(violatorsBasics)
-    || !violatorsBasics.length
-    || violatorsBasics.some(violatorBasics => !violatorBasics[
-      'count of rule engines reporting that the element exhibited the issue'
-    ])
-  ) {
-    console.log(`violatorsBasics: ${JSON.stringify(violatorsBasics, null, 2)}`);
-    return;
-  }
-  console.log(
-    '======================\nRequest: List diagnoses of one violation of one issue in one report'
-  );
-  // Get the issue IDs.
-  const violatorIDs = violatorsBasics.map(violatorBasics => violatorBasics.identifier);
-  // Choose one at random.
-  const violatorID = violatorIDs[Math.floor(Math.random() * violatorIDs.length)];
-  path = `/api/listDiagnoses/${violatorID}/${issueID}/${timeStamp}/${jobID}`;
-  body = await submitRequest(path, method);
-  responseContent = body?.['response content'] ?? {};
-  const diagnoses = responseContent?.['diagnoses of how the element exhibited the issue'] ?? [];
-  if (
-    !diagnoses.length
-    || !Array.isArray(diagnoses)
-    || !diagnoses.length
-    || diagnoses.some(
-      diagnosis => typeof diagnosis !== 'object' || !diagnosis['description of the violation']
-    )
-  ) {
-    console.log(`diagnoses: ${JSON.stringify(diagnoses, null, 2)}`);
-    return;
-  }
-  console.log('======================\nRequest: Get one report');
-  path = `/api/getReport/${timeStamp}/${jobID}`;
-  body = await submitRequest(path, method);
-  responseContent = body?.['response content'] ?? {};
-  const fullReport = responseContent?.['full report'] ?? {};
-  if (responseContent.error || typeof fullReport !== 'object' || !fullReport.device) {
-    console.log('Full report request failed');
-    return;
-  }
-  console.log('======================\nRequest: Make a test request with the GET method');
-  path = '/api/requestTest';
-  body = await submitRequest(path, method);
-  if (body.error?.message !== 'Invalid service request') {
-    console.log(`body: ${JSON.stringify(body, null, 2)}`);
-    return;
-  }
-  console.log('======================\nRequest: Request a test with a too short URL');
-  method = 'POST';
-  body = await submitRequest(path, method, {
-    description: 'Zilch',
-    URL: 'https://a.b',
-    reason: 'Just because'
-  });
-  responseContent = body?.['response content'] ?? {};
-  requestDetails = responseContent['details about your request'] ?? {};
-  if (!requestDetails.error?.includes('specified a URL for the page')) {
-    console.log(`requestDetails: ${JSON.stringify(requestDetails, null, 2)}`);
-    return;
-  }
-  console.log('======================\nRequest: Request a test');
-  body = await submitRequest(path, method, {
-    description: 'Organization that does not exist',
-    URL: 'https://nonexistentorg.com',
-    reason: 'I have no good reason for wanting this page to be tested'
-  });
-  responseContent = body?.['response content'] ?? {};
-  requestDetails = responseContent['details about your request'] ?? {};
-  requestDisposition = responseContent['disposition of your request'] ?? {};
-  if (
-    !requestDetails['reason why the page should be tested']
-    || !requestDisposition['what happens next']?.includes('1 hour to 1 day')
-  ) {
-    console.log(`requestDetails: ${JSON.stringify(requestDetails, null, 2)}`);
-    console.log(`requestDisposition: ${JSON.stringify(requestDisposition, null, 2)}`);
-    return;
-  }
-  console.log('======================\nRequest: Request a retest of a nonexistent report');
-  path = `/api/requestRetest/${timeStamp}/xyz`;
-  body = await submitRequest(path, method, {
-    reason: 'It would be cool to retest what does not exist'
-  });
-  responseContent = body?.['response content'] ?? {};
-  requestDetails = responseContent['details about your request'] ?? {};
-  if (!requestDetails.error?.includes('not an available report')) {
-    console.log(`requestDetails: ${JSON.stringify(requestDetails, null, 2)}`);
-    return;
-  }
-  console.log('======================\nRequest: Request a retest');
-  path = `/api/requestRetest/${timeStamp}/${jobID}`;
-  body = await submitRequest(path, method, {
-    reason: 'I just feel like making this request'
-  });
-  responseContent = body?.['response content'] ?? {};
-  requestDetails = responseContent['details about your request'] ?? {};
-  requestDisposition = responseContent['disposition of your request'] ?? {};
-  // If the report has been superseded:
-  if (isSuperseded) {
-    // Expect the request to be rejected.
-    if (!requestDetails.error?.includes('a later report about the page exists')) {
-      console.log(`requestDetails: ${JSON.stringify(requestDetails, null, 2)}`);
-      return;
-    }
-  }
-  // Otherwise, i.e. if the report has not been superseded:
-  else {
-    if (
-      !requestDetails['reason why the page should be retested']
-      || !requestDisposition['how you can check for completion']
-    ) {
-      console.log(`requestDetails: ${JSON.stringify(requestDetails, null, 2)}`);
-      console.log(`requestDisposition: ${JSON.stringify(requestDisposition, null, 2)}`);
-      return;
-    }
-  }
-  console.log('======================\nRequest: Make a feature request');
-  path = '/api/requestFeature';
-  const featureRequest = 'Do the impossible';
-  body = await submitRequest(path, method, {
-    feature: featureRequest
-  });
-  const feature = body?.['this request']?.body?.feature ?? {};
-  requestDetails = body?.['response content']?.['details about your request'] ?? {};
-  if (
-    feature !== featureRequest
-    || !requestDetails.disposition?.includes('received and logged')
-  ) {
-    console.log(`requestDetails: ${JSON.stringify(requestDetails, null, 2)}`);
-    return;
-  }
-  console.log('======================\nRequest: Results');
-  console.log('All tests succeeded');
-};
-
-// EXECUTION
-
-// Execute the research agent.
-(async () => {
-  await requestService();
-})();