@jrpool/kilotest 46.0.14 → 46.1.2

package/.devin/config.local.json

@@ -9,7 +9,30 @@
       "Exec(git show)",
       "Exec(git commit)",
       "Exec(git check-ignore)",
-      "Exec(git remote)"
+      "Exec(git remote)",
+      "Exec(node)",
+      "Exec(source)",
+      "Exec(nvm use)",
+      "Exec(npm run)",
+      "Exec(lsof)",
+      "Exec(uname)",
+      "Exec(mkdir)",
+      "Exec(set)",
+      "Exec(git add)",
+      "Exec(gh)",
+      "Exec(/opt/homebrew/bin/colima start)",
+      "Exec(/opt/homebrew/bin/docker info)",
+      "Exec(/opt/homebrew/bin/docker run)",
+      "Exec($DOCKER volume)",
+      "Exec($DOCKER run)",
+      "Exec($DOCKER logs)",
+      "Exec($DOCKER exec)",
+      "Exec($DOCKER stop)",
+      "Exec(sed)",
+      "Exec(awk)",
+      "Exec(nvm ls)",
+      "Exec(.)",
+      "Exec(nvm alias)"
     ]
   }
 }

package/.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
       - name: Set Node.js version
         uses: actions/setup-node@v4
         with:
-          node-version: '>=22.12.0'
+          node-version: '>=24.16.0'
 
       - name: Install dependencies
         run: npm ci

package/.github/workflows/publish-mcp.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Set Node.js version
         uses: actions/setup-node@v4
         with:
-          node-version: '>=22.12.0'
+          node-version: '>=24.16.0'
 
       - name: Verify server.json version matches api/version.js
         run: |

package/README.md

@@ -4,6 +4,7 @@
 [![license](https://img.shields.io/github/license/jrpool/kilotest?label=license)](LICENSE)
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-active-success)](https://registry.modelcontextprotocol.io/v0/servers?search=kilotest)
 [![GitHub stars](https://img.shields.io/github/stars/jrpool/kilotest?label=stars)](https://github.com/jrpool/kilotest/stargazers)
+[![Indexed on TensorBlock MCP Index](https://mcp-index.tensorblock.co/v1/servers/github-jrpool-kilotest-f518ba36/badge.svg)](https://tensorblock.co/mcp/servers/github-jrpool-kilotest-f518ba36)
 
 An ensemble testing and reporting service for front-end web quality
 
@@ -63,6 +64,7 @@ There is additional documentation at:
 
 - [QAI](https://kilotest.com/qai): a tutorial for allowing AI assistants to use Kilotest
 - [AI-TOOLS.md](docs/AI-TOOLS.md): how Kilotest implements the MCP protocol
+- [Summary of Kilotest capabilities](https://kilotest.com/capability.md)
 - [llms.txt](llms.txt): basic documentation for LLMs
 - [llms-full.txt](llms-full.txt): comprehensive documentation for LLMs
 - [lhm.plugin.json](lhm.plugin.json): documentation for registration with the LobeHub MCP Market

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/requestFeature.test.js

@@ -5,7 +5,7 @@
 
 // IMPORTS
 
-const {test, before, after} = require('node:test');
+const {test, before, beforeEach, after} = require('node:test');
 const assert = require('node:assert/strict');
 const alerts = require('../alerts');
 
@@ -14,13 +14,17 @@ const alerts = require('../alerts');
 let sendAlertCalls = [];
 
 before(() => {
-  sendAlertCalls = [];
   // @ts-expect-error: Replacing the real function with a mock for testing.
   alerts.sendAlert = async (subject, body) => {
     sendAlertCalls.push({subject, body});
   };
 });
 
+// Reset the call log before each test, so tests do not depend on execution order.
+beforeEach(() => {
+  sendAlertCalls = [];
+});
+
 // Require requestFeature after the mock is in place, so it captures the mocked sendAlert.
 const {response} = require('./requestFeature');
 

package/api/requestRetest.test.js

@@ -5,7 +5,7 @@
 
 // IMPORTS
 
-const {test, before, after} = require('node:test');
+const {test, before, beforeEach, after} = require('node:test');
 const assert = require('node:assert/strict');
 const path = require('node:path');
 const apiUtil = require('./util');
@@ -17,13 +17,17 @@ let processTestRequestCalls = [];
 
 before(() => {
   process.env.DB_DIR = path.join(__dirname, '..', 'test', 'fixtures', 'db');
-  processTestRequestCalls = [];
   // @ts-expect-error: Replacing the real function with a mock for testing.
   apiUtil.processTestRequest = async (testType, what, url, reason) => {
     processTestRequestCalls.push({testType, what, url, reason});
   };
 });
 
+// Reset the call log before each test, so tests do not depend on execution order.
+beforeEach(() => {
+  processTestRequestCalls = [];
+});
+
 // Require requestRetest after the mock is in place, so it captures the mocked processTestRequest.
 const {response} = require('./requestRetest');
 

package/api/requestTest.test.js

@@ -5,7 +5,7 @@
 
 // IMPORTS
 
-const {test, before, after} = require('node:test');
+const {test, before, beforeEach, after} = require('node:test');
 const assert = require('node:assert/strict');
 const path = require('node:path');
 const apiUtil = require('./util');
@@ -17,13 +17,17 @@ let processTestRequestCalls = [];
 
 before(() => {
   process.env.DB_DIR = path.join(__dirname, '..', 'test', 'fixtures', 'db');
-  processTestRequestCalls = [];
   // @ts-expect-error: Replacing the real function with a mock for testing.
   apiUtil.processTestRequest = async (testType, what, url, reason) => {
     processTestRequestCalls.push({testType, what, url, reason});
   };
 });
 
+// Reset the call log before each test, so tests do not depend on execution order.
+beforeEach(() => {
+  processTestRequestCalls = [];
+});
+
 // Require requestTest after the mock is in place, so it captures the mocked processTestRequest.
 const {response} = require('./requestTest');
 

package/api/util.js

@@ -35,7 +35,7 @@ exports.getResponseMetadata = () => ({
 exports.getToolsFacts = () => ({
   'name': 'Kilotest',
   'description': {
-    'what Kilotest does': 'Kilotest tools generate and make available findings about the front-end quality (i.e. accessibility, usability, and standards conformity) of web pages. A Kilotest job generates findings by using Testaro to test a page against more than a thousand rules defined by an ensemble of twelve rule engines. Testaro produces a report of the job. The report describes violations of the rules. Kilotest uses Testilo to enhance the report with a classification of the rule violations into about 300 issues. Kilotest makes facts about the issues and the violations retrievable at four levels of granularity.',
+    'what Kilotest does': 'Kilotest tools generate and make available findings about the front-end quality (i.e. accessibility, usability, and standards conformity) of web pages. A Kilotest job generates findings by using Testaro to test a page against about 1300 rules defined by an ensemble of twelve rule engines. Testaro produces a report of the job. The report describes violations of the rules. Kilotest uses Testilo to enhance the report with a classification of the rule violations into about 380 issues. Kilotest makes facts about the issues and the violations retrievable at four levels of granularity.',
     'how to retrieve findings': {
       'level 1': 'Use the listReports tool to get a list of available reports.',
       'level 2': 'Use the listIssues tool to get a list of issues in one report.',
@@ -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/capability.md

@@ -0,0 +1,51 @@
+# Kilotest capability manifest
+
+## Capability
+
+Web-page front-end quality audit. Kilotest tests public web pages for front-end quality, namely accessibility, usability, and standards conformity, and makes structured findings available for retrieval.
+
+## Purpose
+
+Language models and AI platforms often need accurate, page-specific data about the front-end quality of a web page to answer user questions. Rule engines, such as `axe-core`, `QualWeb`, and `WAVE`, provide such data, but with large coverage gaps. Orchestrating and reconciling numerous complementary rule engines would be difficult. Kilotest solves that problem by testing pages with an ensemble of numerous independent rule engines, making their results comparable, saving the results as JSON reports, mining the reports for facts at selectable levels of detail.
+
+## Interfaces
+
+- MCP server (Streamable HTTP): `https://kilotest.com/mcp`
+- OpenAPI specification: `https://kilotest.com/openapi.yaml`
+- HTTP API: see `https://kilotest.com/openapi.yaml` for endpoints
+- Web UI: `https://kilotest.com/`
+- LLM documentation: `https://kilotest.com/llms.txt` and `https://kilotest.com/llms-full.txt`
+
+## Initial input
+
+A request for a list of available reports.
+
+## Initial output
+
+A list of available reports.
+
+## Subsequent inputs
+
+- If there is no report about the wanted page, a request to test it, with a page description and its URL.
+- If there is a report about the wanted page, requests for findings from the report at successive levels of detail.
+
+## Subsequent outputs
+
+- From a request to test a page: confirmation of receipt. Upon approval and execution, the list of available reports will include the new report.
+- From a request for findings: Details about issues reported, related WCAG standards, what rules were violated, and which DOM elements violated them.
+
+## Side effects
+
+Kilotest reads the specified public web page during testing. It does not modify the target site. Testing is asynchronous and may take up to approximately one day before reports are available for newly requested pages.
+
+## Cost
+
+Free. No authentication is required for the web UI or the public MCP endpoint.
+
+## License
+
+MIT.
+
+## Repository
+
+`https://github.com/jrpool/kilotest`

package/checkinfo.js

@@ -0,0 +1,146 @@
+/*
+  checkinfo.js
+  Summarizes the validation scope of the lint, test, and test:smoke scripts by deriving file and test-case counts from their actual configurations, so the summary stays accurate as the codebase changes.
+*/
+
+// IMPORTS
+
+const fs = require('fs');
+const path = require('path');
+const {execSync} = require('child_process');
+
+// CONSTANTS
+
+const rootDir = __dirname;
+const excludeDirs = new Set(['node_modules', '.git', 'coverage']);
+
+// FUNCTIONS
+
+// Recursively collects all files under a directory, skipping excluded directories.
+const collectFiles = dir => {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!excludeDirs.has(entry.name)) {
+        results.push(...collectFiles(fullPath));
+      }
+    }
+    else {
+      results.push(fullPath);
+    }
+  }
+  return results;
+};
+
+// Converts a glob pattern to a RegExp for matching relative paths.
+// Supports * (non-segment), ** (any), and literal characters.
+const globToRegExp = pattern => {
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '\x00')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\x00/g, '.*');
+  return new RegExp('^' + escaped + '$');
+};
+
+// Returns whether a relative path matches any pattern in a list.
+const matchesAny = (relPath, patterns) => patterns.some(p => globToRegExp(p).test(relPath));
+
+// Extracts the top-level ignores array from eslint.config.mjs.
+const getEslintIgnores = () => {
+  const content = fs.readFileSync(path.join(rootDir, 'eslint.config.mjs'), 'utf8');
+  const match = content.match(/ignores:\s*\[([\s\S]*?)\]/);
+  if (!match) {
+    return [];
+  }
+  return [...match[1].matchAll(/"([^"]+)"/g)].map(m => m[1]);
+};
+
+// Parses .markdownlint-cli2.jsonc and returns its ignores array.
+const getMarkdownlintIgnores = () => {
+  const content = fs.readFileSync(path.join(rootDir, '.markdownlint-cli2.jsonc'), 'utf8');
+  const stripped = content.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
+  const match = stripped.match(/"ignores"\s*:\s*\[([\s\S]*?)\]/);
+  if (!match) {
+    return [];
+  }
+  return [...match[1].matchAll(/"([^"]+)"/g)].map(m => m[1]);
+};
+
+// Runs the Node test runner with the TAP reporter and parses the test count, so dynamically generated tests (e.g., from for-loops) are counted accurately.
+const getTestCaseCount = () => {
+  const output = execSync(
+    'node --require ./test/setup.cjs --test --test-concurrency=1 --test-timeout=100 --test-reporter=tap',
+    {cwd: rootDir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']}
+  );
+  const match = output.match(/^# tests (\d+)$/m);
+  return match ? Number(match[1]) : 0;
+};
+
+// MAIN
+
+const allFiles = collectFiles(rootDir);
+const relFiles = allFiles.map(f => path.relative(rootDir, f));
+
+const eslintIgnores = getEslintIgnores();
+const markdownlintIgnores = getMarkdownlintIgnores();
+
+// ESLint file counts by extension, excluding ignored files.
+const eslintExts = {js: 0, json: 0, md: 0, css: 0};
+for (const rel of relFiles) {
+  if (matchesAny(rel, eslintIgnores)) {
+    continue;
+  }
+  if (/\.(js|mjs|cjs)$/.test(rel)) {
+    eslintExts.js++;
+  }
+  else if (/\.json$/.test(rel)) {
+    eslintExts.json++;
+  }
+  else if (/\.md$/.test(rel)) {
+    eslintExts.md++;
+  }
+  else if (/\.css$/.test(rel)) {
+    eslintExts.css++;
+  }
+}
+const eslintTotal = Object.values(eslintExts).reduce((a, b) => a + b, 0);
+
+// markdownlint file count (markdown files not ignored).
+const markdownlintCount = relFiles.filter(
+  rel => rel.endsWith('.md') && !matchesAny(rel, markdownlintIgnores)
+).length;
+
+// Test file and test-case counts.
+const testFiles = relFiles.filter(rel => /\.test\.js$/.test(rel));
+const testCaseCount = getTestCaseCount();
+
+// Smoke-test path counts from the routes table in index.js.
+const {routes} = require('./index');
+const smokeGetCount = routes.GET.length;
+const smokePostCount = routes.POST.length;
+const smokeTotal = smokeGetCount + smokePostCount;
+
+// OUTPUT
+
+const parts = [
+  ['lint', [
+    `ESLint: ${eslintTotal} files (${eslintExts.js} JS, ${eslintExts.json} JSON, ${eslintExts.md} MD, ${eslintExts.css} CSS)`,
+    `markdownlint: ${markdownlintCount} files`
+  ]],
+  ['test', [
+    `${testFiles.length} test files, ${testCaseCount} test cases`
+  ]],
+  ['test:smoke', [
+    `${smokeTotal} paths (${smokeGetCount} GET, ${smokePostCount} POST)`
+  ]]
+];
+
+console.log('Validation summary:');
+for (const [name, lines] of parts) {
+  console.log(`  ${name}:`);
+  for (const line of lines) {
+    console.log(`    ${line}`);
+  }
+}

package/docs/AI-TOOLS.md

@@ -27,6 +27,7 @@ The internal features that make Kilotest a collection of tools for language mode
 - A generated `openapi.yaml` file, documenting the Kilotest API, conforming to the [OpenAPI specification](https://spec.openapis.org/oas/v3.1.0).
 - An `mcp.js` file, providing an MCP server for Kilotest.
 - A `server.json` file, conforming to the [MCP server schema](https://modelcontextprotocol.io/), and a GitHub Actions workflow (`publish-mcp.yml`) that authenticates via GitHub OIDC and publishes that file to the official MCP Registry whenever `server.json` or `api/version.js` changes on the `main` branch.
+- A `capability.md` file with a URL, summarizing what Kilotest tools can do.
 - `mcp`, `mcp-server`, and `modelcontextprotocol` keywords in `package.json`, supporting discovery of the `@jrpool/kilotest` npm package by tools and humans searching the npm registry for MCP servers.
 - An `lhm.plugin.json` file, conforming to the [LobeHub plugin manifest format](https://market.lobehub.com/s/publish-mcp/references/manifest), declaring Kilotest as a plugin in the [LobeHub MCP Market](https://lobehub.com/mcp). Publishing and updating are non-automated (`lhm plugin publish`/`update`), because LobeHub requires browser-based OAuth and does not support machine-to-machine publishing.
 - A `sitemap.xml` file.
@@ -44,7 +45,7 @@ The external features that support the use of Kilotest as a collection of AI too
 - Registration of Kilotest as an active server in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=kilotest) (`io.github.jrpool/kilotest`), maintained by the [Model Context Protocol](https://modelcontextprotocol.io/) project. The [PulseMCP](https://www.pulsemcp.com/servers) directory and the VS Code MCP gallery both crawl this registry, so Kilotest is discoverable through them with no separate submission.
 - Registration of Kilotest with the [Smithery](https://smithery.ai/servers/pool/kilotest) MCP server registry.
 - Registration of Kilotest with the [Glama](https://glama.ai/mcp/connectors/com.kilotest/kilotest) MCP server registry.
-- a [pull request](https://github.com/TensorBlock/awesome-mcp-servers/pull/2221) (on 2026-09-07) to add Kilotest to the [Awesome MCP Servers](https://github.com/TensorBlock/awesome-mcp-servers) list.
+- Registration of Kilotest with [Awesome MCP Servers](https://www.tensorblock.co/mcp/servers/github-jrpool-kilotest-f518ba36).
 - Registration of Kilotest with the [RapidAPI](https://rapidapi.com/jrpool/api/kilotest/playground/apiendpoint_0f03577a-ff9a-472a-a0ed-533bd198981a) Hub.
 - Registration of Kilotest with the [LobeHub MCP Market](https://lobehub.com/mcp) (identifier: `jrpool-kilotest`), enabled with an `lhm.plugin.json` file.
 - Deployment of an MCP server in HTTP mode on the Kilotest service host.
@@ -99,3 +100,32 @@ Other future work:
 
 - Add to QAI, or replace much of the current QAI content with, an [Add Custom Connector link](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Kilotest&connectorUrl=https%3A%2F%2Fkilotest.com%2Fmcp).
 - Consider subscribing to a `Claude.ai` Team plan and submitting Kilotest to the [Claude Connectors Directory](https://claude.com/docs/connectors/building/submission). Details provided by GLM-5.2 High: “If accepted, Kilotest would get a permanent listing URL like `https://claude.ai/directory/connectors/kilotest` with a Connect button, and would appear in Claude’s in-product browse/search and ‘Suggested Connectors’. This is the highest-value listing for your use cases, because it puts Kilotest directly in front of Claude users who have not explicitly searched for it.”
+- Recommended by GLM-5.2 High: Submit a Kilotest-appropriate request to one or more AI platforms and discover whether the model discovers Kilotest and, if so, either uses it or offers to use it in the creation of a response.
+- Recommended by ChatGPT: A general capability manifest that says, in one machine-readable place: Here are the capabilities Kilotest provides; here are all the interfaces through which you can invoke them; here are their requirements and effects. For example:
+
+    ```markdown
+    Capability: web-page-quality-audit
+
+    Purpose:
+      Test a public web page for accessibility,
+      usability, HTML and web-standards problems.
+
+    Interfaces:
+      MCP: https://kilotest.com/mcp
+      OpenAPI: https://kilotest.com/openapi.yaml
+      Web UI: https://kilotest.com/
+
+    Input:
+      Public URL
+
+    Output:
+      Structured findings, affected elements,
+      rule-engine diagnoses, WCAG mappings
+
+    Side effects:
+      Reads the specified public web page.
+      Does not modify the target site.
+
+    Cost:
+      ...
+    ```

package/docs/SERVICE.md

@@ -199,7 +199,7 @@ kilotest.com {
   # Specify the only paths of forwardable requests.
   @allowedGET {
     method GET
-    path /mcp / /index.html /robots.txt /openapi.yaml /openapi.json /swagger.yaml /swagger.json /api-docs /llms.txt /llms-full.txt *.html* /fullReport.json/* /api/* /tutorial/images/* /favicon.* /style.css /sitemap.xml
+    path /mcp / /index.html /robots.txt /openapi.yaml /openapi.json /swagger.yaml /swagger.json /api-docs /llms.txt /llms-full.txt /capability.md *.html* /fullReport.json/* /api/* /tutorial/images/* /favicon.* /style.css /sitemap.xml
   }
   @allowedPOST {
     method POST

package/index.html

@@ -71,6 +71,7 @@
         <p>The rule engines perform about 1,300 tests in total. <a href="https://medium.com/cvs-health-tech-blog/how-to-run-a-thousand-accessibility-tests-63692ad120c3">Open-source software</a> developed initially at CVS Health drives the rule engines, tries to weed out invalid results, and distills the findings into about 380 <q>issues</q>.</p>
         <h2>Features</h2>
         <p>With Kilotest, you can get results of already performed tests and propose web pages for testing. (Immediate testing on request may become available in a future version.)</p>
+        <p>There is a <a href="/capability.md">capability document</a> that summarizes what Kilotest can do for human and AI-agent users.</p>
         <h2>How to use Kilotest</h2>
         <h3>If you are a human user on the web</h3>
         <p>You can use Kilotest starting on this page.</p>

package/index.js

@@ -66,36 +66,37 @@ const answer = {
 // 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',
+    '*.html*',
     '/',
-    '/index.html',
-    '/robots.txt',
-    '/openapi.yaml',
-    '/openapi.json',
-    '/swagger.yaml',
-    '/swagger.json',
     '/api-docs',
-    '/llms.txt',
+    '/api/*',
+    '/capability.md',
+    '/favicon.*',
+    '/fullReport.json/*',
+    '/index.html',
     '/llms-full.txt',
+    '/llms.txt',
+    '/mcp',
+    '/openapi.json',
+    '/openapi.yaml',
+    '/robots.txt',
     '/sitemap.xml',
     '/style.css',
-    '/fullReport.json/*',
-    '/api/*',
-    '/tutorial/images/*',
-    '/favicon.*',
-    '*.html*'
+    '/swagger.json',
+    '/swagger.yaml',
+    '/tutorial/images/*'
   ],
   POST: [
+    '/api/*',
     '/mcp',
-    '/requestTest.html',
-    '/requestRetest.html/*',
-    '/recAction.html',
     '/reannotate.html',
+    '/recAction.html',
     '/renewWCAG.html',
+    '/requestRetest.html/*',
+    '/requestTest.html',
+    '/tutorialComment.html',
     '/worker/job',
-    '/worker/report',
-    '/api/*',
-    '/tutorialComment.html'
+    '/worker/report'
   ]
 };
 const protocol = process.env.PROTOCOL || 'http';
@@ -359,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:
@@ -412,6 +419,13 @@ const requestHandler = async (request, response) => {
       setHeaders('text/plain', '/llms-full.txt', 'medium');
       response.end(llmsfull);
     }
+    // Otherwise, if it is for the summary of capabilities:
+    else if (pageName === 'capability.md') {
+      const capabilityDoc = await fs.readFile('capability.md', 'utf8');
+      // Serve it.
+      setHeaders('text/markdown', '/capability.md', 'medium');
+      response.end(capabilityDoc);
+    }
     // Otherwise, if it is for the XML sitemap:
     else if (pageName === 'sitemap.xml') {
       const sitemap = await fs.readFile('sitemap.xml', 'utf8');

package/index.test.js

@@ -18,7 +18,7 @@ process.env.TESTARO_WORKERS = JSON.stringify({
 
 // IMPORTS
 
-const {test, before, after} = require('node:test');
+const {test, before, beforeEach, after} = require('node:test');
 const assert = require('node:assert/strict');
 const http = require('node:http');
 const fs = require('node:fs/promises');
@@ -35,7 +35,12 @@ const recsPath = path.join(fixtureDBDir, 'jobs', 'recs.json');
 let server;
 
 before(async () => {
-  // Restore recs.json and clean job directories before running.
+  server = http.createServer(requestHandler);
+  await new Promise(resolve => server.listen(port, () => resolve()));
+});
+
+// Restore recs.json and clean job directories before each test, so tests do not depend on execution order.
+beforeEach(async () => {
   await fs.writeFile(recsPath, '{}\n');
   for (const sub of ['claimed', 'queue', 'failed']) {
     const dir = path.join(fixtureDBDir, 'jobs', sub);
@@ -45,8 +50,6 @@ before(async () => {
       await fs.unlink(path.join(dir, file)).catch(() => {});
     }
   }
-  server = http.createServer(requestHandler);
-  await new Promise(resolve => server.listen(port, () => resolve()));
 });
 
 after(async () => {
@@ -144,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 () => {
@@ -211,6 +234,13 @@ test('GET /llms-full.txt serves the LLM detailed guide as text', async () => {
   assert.ok(res.body.length > 0);
 });
 
+test('GET /capability.md serves the capability manifest as markdown', async () => {
+  const res = await request('GET', '/capability.md');
+  assert.equal(res.statusCode, 200);
+  assert.ok(res.headers['content-type'].includes('text/markdown'));
+  assert.ok(res.body.length > 0);
+});
+
 test('GET /sitemap.xml serves the sitemap as XML', async () => {
   const res = await request('GET', '/sitemap.xml');
   assert.equal(res.statusCode, 200);
@@ -251,7 +281,7 @@ test('GET /api/listViolators/linkNoText/260101T0000/mix returns JSON', async ()
   assert.equal(body['tool name'], 'listViolators');
 });
 
-test('GET /api/listDiagnoses/0/linkNoText/260101T0000/mix returns JSON', async () => {
+test('GET /api/listDiagnoses/0/linkNoText/260101T0000/mix returns JSON', {timeout: 500}, async () => {
   const res = await request('GET', '/api/listDiagnoses/0/linkNoText/260101T0000/mix');
   assert.equal(res.statusCode, 200);
   const body = jsonBody(res);
@@ -265,7 +295,7 @@ test('GET /api/getReport/260101T0000/mix returns JSON with the report', async ()
   assert.equal(body['tool name'], 'getReport');
 });
 
-test('GET /api/invalidService returns an error', async () => {
+test('GET /api/invalidService returns an error', {timeout: 500}, async () => {
   const res = await request('GET', '/api/invalidService');
   assert.equal(res.statusCode, 400);
   const body = jsonBody(res);
@@ -281,7 +311,7 @@ test('GET /fullReport.json/260101T0000/mix downloads the report as JSON', async
   assert.ok(body.target);
 });
 
-test('GET /fullReport.json/invalid/invalid returns an error page', async () => {
+test('GET /fullReport.json/invalid/invalid returns an error page', {timeout: 500}, async () => {
   const res = await request('GET', '/fullReport.json/invalid/invalid');
   assert.equal(res.statusCode, 400);
   assert.ok(res.headers['content-type'].includes('text/html'));
@@ -382,7 +412,7 @@ test('POST /requestRetest.html/invalid/invalid with invalid data returns an erro
   assert.ok(res.body.includes('Invalid retest recommendation'));
 });
 
-test('POST /api/requestTest with valid JSON returns a JSON response', async () => {
+test('POST /api/requestTest with valid JSON returns a JSON response', {timeout: 500}, async () => {
   const res = await request('POST', '/api/requestTest', {
     description: `API Test Page ${uniqueStamp}`,
     URL: `https://example.com/api-test-${uniqueStamp}`,
@@ -502,7 +532,7 @@ test('serveError sends HTML for human requests (isHumanUser = true)', async () =
 
 // TESTS: recAction.html
 
-test('POST /recAction.html with invalid auth code returns an error', async () => {
+test('POST /recAction.html with invalid auth code returns an error', {timeout: 500}, async () => {
   const res = await formRequest('POST', '/recAction.html', {
     target: 'https://example.com\tTest Page',
     authCode: 'wrong-code'
@@ -542,7 +572,7 @@ test('GET /fullReport.json/260101T0007/hid returns an abuse error for a hidden r
   assert.ok(res.body.includes('Invalid request'));
 });
 
-test('POST /recAction.html with valid auth code and approval returns HTML', async () => {
+test('POST /recAction.html with valid auth code and approval returns HTML', {timeout: 500}, async () => {
   await fs.writeFile(recsPath, '{}\n');
   await formRequest('POST', '/requestTest.html', {
     what: `Approval Test Page ${uniqueStamp}`,
@@ -619,7 +649,7 @@ test('POST /renewWCAG.html with valid auth code serves the answer page', async (
   }
 });
 
-test('POST /tutorialComment.html with empty content returns a JSON error', async () => {
+test('POST /tutorialComment.html with empty content returns a JSON error', {timeout: 500}, async () => {
   const res = await request('POST', '/tutorialComment.html', {
     content: ''
   });
@@ -691,7 +721,7 @@ test('POST /worker/job with no colon in decoded credentials returns 401', async
 
 // TESTS: processJobRequest branches
 
-test('POST /worker/job with a claimed job assigned to the worker returns an error and reclassifies the job', async () => {
+test('POST /worker/job with a claimed job assigned to the worker returns an error and reclassifies the job', {timeout: 500}, async () => {
   // Create a claimed job assigned to Worker One.
   const claimedDir = path.join(fixtureDBDir, 'jobs', 'claimed');
   const failedDir = path.join(fixtureDBDir, 'jobs', 'failed');
@@ -712,6 +742,8 @@ test('POST /worker/job with a claimed job assigned to the worker returns an erro
   // The worker should get an error about the incomplete job.
   const body = jsonBody(res);
   assert.ok(body.error.message.includes('has not completed job'));
+  // Wait for the async rename to complete.
+  await new Promise(resolve => setTimeout(resolve, 100));
   // The job should have been moved to failed.
   const failedExists = await fs.access(failedJobPath).then(() => true).catch(() => false);
   assert.ok(failedExists, 'Job should be moved to failed directory');
@@ -758,7 +790,7 @@ test('POST /worker/job with a queued job assigns it to the worker', {timeout: 50
 
 // TESTS: worker/report valid submission
 
-test('POST /worker/report with valid authentication and valid claimed job processes the report', async () => {
+test('POST /worker/report with valid authentication and valid claimed job processes the report', {timeout: 500}, async () => {
   // Use a unique job ID that does not conflict with existing fixtures.
   const jobID = '990101T0000-tst';
   const reportPath = path.join(fixtureDBDir, 'reports', `${jobID}.json`);
@@ -851,6 +883,18 @@ for (const pagePath of htmlPagePaths) {
   });
 }
 
+test('GET /enqueueForm.html shows recommendations when recs.json has entries', async () => {
+  await fs.writeFile(recsPath, JSON.stringify({
+    'https://example.com/enqueue-test': [
+      {what: 'Enqueue Test Page', why: 'Needs testing for accessibility'}
+    ]
+  }));
+  const res = await request('GET', '/enqueueForm.html');
+  assert.equal(res.statusCode, 200);
+  assert.ok(res.body.includes('https://example.com/enqueue-test'));
+  assert.ok(res.body.includes('Enqueue Test Page'));
+});
+
 test('GET /listRules.html returns an error page when called without arguments', async () => {
   const res = await request('GET', '/listRules.html');
   assert.equal(res.statusCode, 400);
@@ -891,7 +935,7 @@ test('POST /mcp returns a response from the MCP handler', async () => {
 
 // TESTS: answer error branches
 
-test('POST /requestTest.html with valid format but duplicate URL returns an answer error', async () => {
+test('POST /requestTest.html with valid format but duplicate URL returns an answer error', {timeout: 500}, async () => {
   await fs.writeFile(recsPath, '{}\n');
   // First request to create the recommendation.
   await formRequest('POST', '/requestTest.html', {
@@ -909,7 +953,7 @@ test('POST /requestTest.html with valid format but duplicate URL returns an answ
   assert.ok(res.body.includes('Duplicate recommendation'));
 });
 
-test('POST /requestRetest.html with valid format but duplicate retest returns an answer error', async () => {
+test('POST /requestRetest.html with valid format but duplicate retest returns an answer error', {timeout: 500}, async () => {
   await fs.writeFile(recsPath, '{}\n');
   // First retest to create the recommendation.
   await formRequest('POST', '/requestRetest.html/260202T0000/new', {
@@ -923,7 +967,7 @@ test('POST /requestRetest.html with valid format but duplicate retest returns an
   assert.ok(res.body.includes('Duplicate recommendation'));
 });
 
-test('POST /recAction.html with valid auth code and approval of a duplicate returns an error', async () => {
+test('POST /recAction.html with valid auth code and approval of a duplicate returns an error', {timeout: 500}, async () => {
   await fs.writeFile(recsPath, '{}\n');
   // Create a recommendation.
   await formRequest('POST', '/requestTest.html', {
@@ -1026,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');
@@ -1054,7 +1107,57 @@ test('startServer starts an HTTP server when protocol is http', async () => {
   }
 });
 
-test('startServer starts an HTTPS server when protocol is https', {timeout: 500}, 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');
   const os = require('node:os');
@@ -1070,6 +1173,9 @@ test('startServer starts an HTTPS server when protocol is https', {timeout: 500}
   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;
@@ -1110,6 +1216,12 @@ test('startServer starts an HTTPS server when protocol is https', {timeout: 500}
     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/llms-full.txt

@@ -172,6 +172,7 @@ More information about Kilotest features and internals:
 - [Tutorial, “Accessibility testing strategies”](https://kilotest.com/tutorial.html)
 - [Tutorial on authorizing language models to use Kilotest](https://kilotest.com/qai/)
 - [README file](https://github.com/jrpool/kilotest/blob/main/README.md)
+- [Summary of Kilotest capabilities](https://kilotest.com/capability.md)
 - [Testaro rule-engine orchestrator](https://github.com/YRA-Tech/testaro)
 - [Testaro rule classifier](https://github.com/YRA-Tech/testaro-issues)
 - [Research report on Testaro](https://arxiv.org/abs/2309.10167)

package/llms.txt

@@ -33,6 +33,7 @@ Kilotest helps language models and AI platforms to give thorough, accurate and t
 ## More documents
 
 - [Detailed explanation of Kilotest and its capabilities for LLMs](https://kilotest.com/llms-full.txt)
+- [Summary of Kilotest capabilities](https://kilotest.com/capability.md)
 - [OpenAPI specification for Kilotest](https://kilotest.com/openapi.yaml)
 - [Kilotest as connector to and collection of AI Tools](https://github.com/jrpool/kilotest/blob/main/docs/AI-TOOLS.md)
 - [Tutorial on authorizing language models to use Kilotest](https://kilotest.com/qai/)

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "46.0.14",
+  "version": "46.1.2",
   "description": "Ensemble testing for front-end web quality",
   "main": "index.js",
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=24.16.0"
   },
   "scripts": {
     "start": "node index",
-    "lint": "npx eslint && npx markdownlint-cli2",
-    "test": "c8 node --require ./test/setup.cjs --test --test-concurrency=1 --test-timeout=70",
+    "lint": "npx eslint && out=$(npx markdownlint-cli2 2>&1); code=$?; if [ $code -ne 0 ]; then echo \"$out\"; exit $code; fi",
+    "test": "c8 node --require ./test/setup.cjs --test --test-concurrency=1 --test-timeout=100 --test-randomize",
     "test:smoke": "node smokeTest",
+    "checkinfo": "node checkinfo",
     "generate:openapi": "node scripts/generate-openapi"
   },
   "repository": {

package/smokeTest.js

@@ -14,50 +14,53 @@ 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',
+    '*.html*': '/listReports.html',
     '/': '/',
-    '/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',
+    '/api/*': '/api/listReports',
+    '/capability.md': '/capability.md',
+    '/favicon.*': '/favicon.ico',
+    '/fullReport.json/*': '/fullReport.json/260101T0000/mix',
+    '/index.html': '/index.html',
     '/llms-full.txt': '/llms-full.txt',
+    '/llms.txt': '/llms.txt',
+    '/mcp': '/mcp',
+    '/openapi.json': '/openapi.json',
+    '/openapi.yaml': '/openapi.yaml',
+    '/robots.txt': '/robots.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'
+    '/swagger.json': '/swagger.json',
+    '/swagger.yaml': '/swagger.yaml',
+    '/tutorial/images/*': '/tutorial/images/diagram.png'
   },
   POST: {
+    '/api/*': '/api/requestFeature',
     '/mcp': '/mcp',
-    '/requestTest.html': '/requestTest.html',
-    '/requestRetest.html/*': '/requestRetest.html/260101T0001/ct',
-    '/recAction.html': '/recAction.html',
     '/reannotate.html': '/reannotate.html',
+    '/recAction.html': '/recAction.html',
     '/renewWCAG.html': '/renewWCAG.html',
+    '/requestRetest.html/*': '/requestRetest.html/260101T0001/ct',
+    '/requestTest.html': '/requestTest.html',
+    '/tutorialComment.html': '/tutorialComment.html',
     '/worker/job': '/worker/job',
-    '/worker/report': '/worker/report',
-    '/api/*': '/api/requestFeature',
-    '/tutorialComment.html': '/tutorialComment.html'
+    '/worker/report': '/worker/report'
   }
 };
 // 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'},
+  '/mcp': {},
   '/reannotate.html': {authCode: 'invalid'},
+  '/recAction.html': {
+    target: 'https://smoketest.example.com\tSmoke Test Page', authCode: 'invalid'
+  },
   '/renewWCAG.html': {authCode: 'invalid'},
-  '/worker/job': {},
-  '/worker/report': {},
+  '/requestRetest.html/260101T0001/ct': {why: 'smoke test'},
+  '/requestTest.html': {what: 'Smoke Test Page', url: 'https://smoketest.example.com', why: 'smoke test'},
   '/tutorialComment.html': {content: 'smoke test'},
-  '/mcp': {}
+  '/worker/job': {},
+  '/worker/report': {}
 };
 
 // FUNCTIONS
@@ -65,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.

package/util.test.js

@@ -398,7 +398,7 @@ test('processTestRequest returns an error for a mismatched directory name', asyn
   assert.equal(result.message, 'Invalid recommendation');
 });
 
-test('processTestRequest succeeds and populates the template for a valid request', async () => {
+test('processTestRequest succeeds and populates the template for a valid request', {timeout: 500}, async () => {
   // Reset recs.json to empty before the test.
   await fs.writeFile(recsPath(), '{}\n');
   const result = await processTestRequest('test', requestTestDir, 'Example Page', 'https://example.com', 'because accessibility');
@@ -409,7 +409,7 @@ test('processTestRequest succeeds and populates the template for a valid request
   await fs.writeFile(recsPath(), '{}\n');
 });
 
-test('processTestRequest returns a duplicate error for a repeated request', async () => {
+test('processTestRequest returns a duplicate error for a repeated request', {timeout: 500}, async () => {
   // Reset recs.json to empty, then make a successful request.
   await fs.writeFile(recsPath(), '{}\n');
   await processTestRequest('test', requestTestDir, 'Example Page', 'https://example.com', 'because accessibility');

package/web/listReports/listReports.test.js

@@ -88,7 +88,7 @@ test('listReports includes a link to request testing a new page', async () => {
   assert.ok(testLink);
 });
 
-test('listReports shows recommendations when recs.json has entries', async () => {
+test('listReports shows recommendations when recs.json has entries', {timeout: 500}, async () => {
   const dbDir = path.join(__dirname, '..', '..', 'test', 'fixtures', 'db');
   const recsPath = path.join(dbDir, 'jobs', 'recs.json');
   const originalRecs = await fs.readFile(recsPath, 'utf8');

package/web/reannotate/reannotate.test.js

@@ -87,7 +87,7 @@ test('answer returns an error when no reports are available', async () => {
   }
 });
 
-test('answer returns an error when a report fails annotation', async () => {
+test('answer returns an error when a report fails annotation', {timeout: 2000}, async () => {
   // Back up all fixture reports, because annotateReport modifies good reports
   // in place before it reaches the bad one and returns an error.
   const backups = await backupReports();
@@ -122,7 +122,7 @@ test('answer returns an error when a report fails annotation', async () => {
   }
 });
 
-test('answer returns ok with an answer page when all reports annotate successfully', async () => {
+test('answer returns ok with an answer page when all reports annotate successfully', {timeout: 2000}, async () => {
   // Back up all fixture reports, because annotateReport modifies them in place.
   const backups = await backupReports();
   try {

package/web/requestTest/requestTest.test.js

@@ -61,7 +61,7 @@ after(async () => {
 
 // TESTS
 
-test('answer returns ok with a populated answer page for a valid test request', async () => {
+test('answer returns ok with a populated answer page for a valid test request', {timeout: 500}, async () => {
   // Require the module after DB_DIR is set.
   const {answer} = require('./index');
   const result = await answer(
@@ -81,7 +81,7 @@ test('answer returns ok with a populated answer page for a valid test request',
   assert.ok(h1.textContent.includes('Test Page'));
 });
 
-test('answer returns an error when the URL is already queued', async () => {
+test('answer returns an error when the URL is already queued', {timeout: 500}, async () => {
   const {answer} = require('./index');
   // Create a queued job with the target URL.
   const queueDir = path.join(fixtureDBDir, 'jobs', 'queue');
@@ -107,7 +107,7 @@ test('answer returns an error when the URL is already queued', async () => {
   }
 });
 
-test('answer returns an error for an invalid recommendation', async () => {
+test('answer returns an error for an invalid recommendation', {timeout: 500}, async () => {
   const {answer} = require('./index');
   const result = await answer('', 'not-a-url', 'why');
   assert.equal(result.status, 'error');

package/web/rewindReportsForm/rewindReportsForm.test.js

@@ -72,7 +72,7 @@ test('rewindReportsForm deletes a latest superseding report with valid auth code
   }
 });
 
-test('rewindReportsForm returns an error when a report file is corrupt', async () => {
+test('rewindReportsForm returns an error when a report file is corrupt', {timeout: 500}, async () => {
   const reportPath = path.join(reportsPath(), '260101T0001-ct.json');
   const backup = await fs.readFile(reportPath, 'utf8');
   try {

package/web/tutorial/tutorial.test.js

@@ -59,7 +59,7 @@ test('handleComment returns an error for content that is empty after sanitizatio
   assert.equal(result.message, 'Comment is empty after sanitization');
 });
 
-test('handleComment saves a sanitized comment and returns ok', async () => {
+test('handleComment saves a sanitized comment and returns ok', {timeout: 500}, async () => {
   // Replace comments with an empty array for a clean test.
   await fs.writeFile(commentsPath, '[]\n');
   const result = await handleComment('This is a <b>test</b> comment.');
@@ -70,7 +70,7 @@ test('handleComment saves a sanitized comment and returns ok', async () => {
   assert.ok(comments[0].timeStamp);
 });
 
-test('handleComment strips HTML tags and control characters', async () => {
+test('handleComment strips HTML tags and control characters', {timeout: 500}, async () => {
   await fs.writeFile(commentsPath, '[]\n');
   const result = await handleComment('<img src=x onerror=alert(1)>\x00\x07Hello');
   assert.equal(result.status, 'ok');
@@ -78,7 +78,7 @@ test('handleComment strips HTML tags and control characters', async () => {
   assert.equal(comments[0].content, 'Hello');
 });
 
-test('handleComment truncates content to 500 characters', async () => {
+test('handleComment truncates content to 500 characters', {timeout: 500}, async () => {
   await fs.writeFile(commentsPath, '[]\n');
   const longComment = 'x'.repeat(600);
   const result = await handleComment(longComment);
@@ -87,7 +87,7 @@ test('handleComment truncates content to 500 characters', async () => {
   assert.equal(comments[0].content.length, 500);
 });
 
-test('handleComment creates comments.json when it does not exist', async () => {
+test('handleComment creates comments.json when it does not exist', {timeout: 500}, async () => {
   await fs.unlink(commentsPath).catch(() => {});
   const result = await handleComment('Test comment for missing file');
   assert.equal(result.status, 'ok');