@jrpool/kilotest 24.0.4

package/diagnoses/index.js

@@ -0,0 +1,140 @@
+/*
+  index.js
+  Answers the report-issues question.
+*/
+
+// IMPORTS
+
+const {
+  getPageDataStrings,
+  getReport,
+  getTextFragmentHref,
+  getWCAGLink,
+  getWeightName,
+  htmlSafe,
+  isHidden,
+  tools
+} = require('../util');
+const {issues} = require('testilo/procs/score/tic');
+const fs = require('fs/promises');
+const path = require('path');
+
+// FUNCTIONS
+
+// Adds parameters to a query for the answer page.
+const populateQuery = async (issueID, timeStamp, jobID, catalogIndex, pathID, query) => {
+  const pageDataStrings = await getPageDataStrings(timeStamp, jobID);
+  const {what, url, urlLink, testInfo} = pageDataStrings;
+  const report = await getReport(timeStamp, jobID);
+  const {acts, catalog} = report;
+  const catalogItem = catalog[catalogIndex] ?? {};
+  const {boxID, startTag, tagName, text} = catalogItem;
+  query.catalogIndex = catalogIndex;
+  const lines = [];
+  const margin = ' '.repeat(6);
+  if (catalogIndex && catalogItem.textLinkable) {
+    const href = getTextFragmentHref(text, url);
+    const label = `Take me to element ${catalogIndex} on the page (in a new tab)`;
+    const link = `<a href="${href}" target="_blank" aria-label="${label}">Take me there</a>`;
+    query.takeMeThere = `${margin}    <p>${link}</p>`;
+  }
+  else {
+    query.takeMeThere = '';
+  }
+  // Add facts about the issue to the query.
+  query.target = what;
+  query.urlLink = urlLink;
+  query.testInfo = testInfo;
+  query.issue = issues[issueID].summary;
+  const issue = issues[issueID];
+  const {wcag, weight, why} = issue;
+  query.why = why;
+  query.priority = getWeightName(weight);
+  query.wcag = `<a href="${getWCAGLink(wcag)}">${wcag}</a>`;
+  query.tagName = tagName || 'HTML';
+  if (text && ! ['HTML', 'BODY', 'HEAD', 'SCRIPT', 'STYLE', 'NOSCRIPT'].includes(tagName)) {
+    const textString = text.split('\n').join(' … ');
+    query.text = `<q>${htmlSafe(textString)}</q>`;
+  }
+  else {
+    query.text = '[not applicable]';
+  }
+  query.startTag = htmlSafe(startTag) || '[not obtained]';
+  query.pathID = pathID || '[not obtained]';
+  if (boxID) {
+    const dims = boxID.split(':');
+    query.box = `x = ${dims[0]}, y = ${dims[1]}, width = ${dims[2]}, height = ${dims[3]}`;
+  }
+  else {
+    query.box = '[not obtained]';
+  }
+  // Initialize an array of diagnoses.
+  let diagnoses = [];
+  const testActs = acts.filter(act => act.type === 'test');
+  // For each test act:
+  testActs.forEach(act => {
+    const {result, which} = act;
+    const caseInstances = result?.standardResult?.instances?.filter(
+      instance => instance.issueID === issueID && instance.catalogIndex === catalogIndex
+    ) ?? [];
+    // For each standard instance that pertains to this combination of issue and violator:
+    caseInstances.forEach(instance => {
+      const {ruleID, what} = instance;
+      // Add lines for it to the array.
+      diagnoses.push({
+        toolID: which,
+        ruleID,
+        what
+      });
+    });
+  });
+  // For each diagnosis:
+  diagnoses.forEach(diagnosis => {
+    const {toolID, ruleID, what} = diagnosis;
+    // Add lines.
+    lines.push(`${margin}<li>${htmlSafe(what)}`);
+    lines.push(`${margin}  <p>Tool: ${tools[toolID][0]} (${tools[toolID][1]})</p>`);
+    if (ruleID !== what) {
+      lines.push(`${margin}  <p>Rule: <code>${ruleID}</code></p>`);
+    }
+    lines.push(`${margin}</li>`);
+  });
+  // Add the lines to the query.
+  query.diagnoses = lines.join('\n');
+};
+// Returns a page answering the diagnoses question.
+exports.answer = async (pageArgs, search) => {
+  const [issueID, timeStamp, jobID, catalogIndex] = pageArgs.split('/');
+  const reportIsHidden = await isHidden(timeStamp, jobID);
+  // If the report is not available:
+  if (reportIsHidden) {
+    return {
+      status: 'error',
+      message: 'Report not available'
+    };
+  }
+  const params = new URLSearchParams(search);
+  const pathID = params.get('pathID');
+  const query = {};
+  // Create a query to replace the placeholders.
+  await populateQuery(issueID, timeStamp, jobID, catalogIndex, pathID, query);
+  // If the test specifications are valid:
+  if (query.testInfo) {
+    // Get the template.
+    let answerPage = await fs.readFile(path.join(__dirname, 'index.html'), 'utf8');
+    // Replace its placeholders.
+    Object.keys(query).forEach(param => {
+      answerPage = answerPage.replace(new RegExp(`__${param}__`, 'g'), query[param]);
+    });
+    // Return the populated page.
+    return {
+      status: 'ok',
+      answerPage
+    };
+  }
+  // Otherwise, report this.
+  return {
+    status: 'error',
+    error: 'Invalid report specification'
+  };
+};

package/env.example

@@ -0,0 +1,21 @@
+# For a local development/test host, ENVIRONMENT=test.
+ENVIRONMENT=production
+# PROTOCOL must be http if a local dev/test host or reverse-proxied server, or otherwise https.
+PROTOCOL=__placeholder__
+# AUTH_CODE must be 3 characters long.
+AUTH_CODE=__placeholder__
+TESTARO_AGENT=testaro-agent
+# TESTARO_AGENT_PW must be identical to NETWATCH_AUTH in the Testaro .env.
+TESTARO_AGENT_PW=__placeholder__
+# Alert email configuration:
+MANAGER_EMAIL=__placeholder__
+ALERT_API_HOST=api.resend.com
+ALERT_API_PATH=/emails
+ALERT_API_KEY=__placeholder__
+ALERT_FROM=__placeholder__
+# Alert thresholds:
+WAVE_BALANCE_THRESHOLD=30
+AI_SERVICE0_BALANCE_THRESHOLD=10
+# Per-million-token prices (Claude Haiku 4.5) on 2026-05-01 were $1 in, $5 out.
+AI_MODEL0_INPUT_PRICE=0.000001
+AI_MODEL0_OUTPUT_PRICE=0.000005

package/env.testaro

@@ -0,0 +1,17 @@
+# You can get a WAVE API key at https://wave.webaim.org/api.
+WAVE_KEY=__placeholder__
+AGENT=testaro-agent
+HEADED_BROWSER=false
+DEBUG=false
+WAITS=0
+NODE_OPTIONS='--trace-uncaught --trace-warnings'
+PUPPETEER_DISABLE_HEADLESS_WARNING=true
+# Replace the next 2 placeholders with:
+# http://localhost:3000 if Kilotest and Testaro are on the same host.
+# the URL of the Kilotest server (e.g., https://kilotest.com) if they are on different hosts.
+NETWATCH_JOB=__placeholder__/api/testaro-agent/job
+NETWATCH_REPORT=__placeholder__/api/testaro-agent/report
+# NETWATCH_AUTH must be identical to TESTARO_AGENT_PW in the Kilotest .env.
+NETWATCH_AUTH=__placeholder__
+TIMEOUT_MULTIPLIER=1
+TMPDIRNAME=scratch

package/error.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en-US">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="publisher" content="Jonathan Robert Pool">
+    <meta name="creator" content="Jonathan Robert Pool">
+    <meta name="keywords" content="report,accessibility,a11y">
+    <title>Error | Kilotest</title>
+    <link rel="stylesheet" href="/style.css">
+  </head>
+  <body>
+    <main>
+      <h1><a href="/">Kilotest</a>: error</h1>
+      <p class="error">__error__</p>
+    </main>
+  </body>
+</html>

package/eslint.config.mjs

@@ -0,0 +1,53 @@
+import js from "@eslint/js";
+import globals from "globals";
+import json from "@eslint/json";
+import markdown from "@eslint/markdown";
+import css from "@eslint/css";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+  {
+    ignores: [
+      "DEVELOPMENT.md",
+      "package-lock.json"
+    ]
+  },
+  {
+    files: ["**/*.{js,mjs,cjs}"],
+    plugins: { js },
+    extends: ["js/recommended"],
+    languageOptions: {
+      globals: globals.node
+    }
+  },
+  {
+    files: ["**/*.js"],
+    languageOptions: {
+      sourceType: "commonjs"
+    }
+  },
+  {
+    files: ["**/*.json"],
+    plugins: {
+      json
+    },
+    language: "json/json",
+    extends: ["json/recommended"]
+  },
+  {
+    files: ["**/*.md"],
+    plugins: {
+      markdown
+    },
+    language: "markdown/gfm",
+    extends: ["markdown/recommended"]
+  },
+  {
+    files: ["**/*.css"],
+    plugins: {
+      css
+    },
+    language: "css/css",
+    extends: ["css/recommended"]
+  }
+]);

package/index.html

@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en-US">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="publisher" content="Jonathan Robert Pool">
+    <meta name="creator" content="Jonathan Robert Pool">
+    <meta name="keywords" content="report,accessibility,a11y">
+    <title>Kilotest</title>
+    <link rel="stylesheet" href="/style.css">
+  </head>
+  <body>
+    <main>
+      <h1>Kilotest</h1>
+      <p>Kilotest performs more than a thousand tests on a web page.</p>
+      <p><a href="/tutorial.html">New to accessibility testing? Start with the tutorial.</a></p>
+      <details>
+        <summary>More than a thousand? Really?</summary>
+        <h2>Ensemble testing</h2>
+        <p>Kilotest does <strong>ensemble testing</strong> of web pages for <a href="https://www.w3.org/mission/accessibility/">accessibility</a>, usability, and conformity to HTML standards.</p>
+        <p>Efficient testing <strong>first</strong> leverages <strong>automated tools</strong> and corrects the defects that they discover, <strong>then</strong> employs human testers.</p>
+        <p>Choosing an automated tool is hard, because they <a href="https://www.w3.org/WAI/test-evaluate/tools/list/">are numerous</a> and <a href="https://arxiv.org/pdf/2304.07591">vary in what and how they test</a>.</p>
+        <p><strong>Ensemble testing</strong>, instead of choosing a tool, combines multiple tools. It can discover more issues than single-tool testing, and the tools can check one another&rsquo;s quality.</p>
+        <h2>The tools</h2>
+        <p>The Kilotest ensemble is <a href="https://github.com/jrpool/testaro?tab=readme-ov-file#dependencies">10 tools</a> developed by teams in the USA, Canada, Denmark, Australia, and Portugal.</p>
+        <p>The tools 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 tools, tries to weed out invalid results, and distills the findings into about 350 <q>issues</q>.</p>
+        <h2>Status</h2>
+        <p>Kilotest is a proof of concept, launched in November 2025 and being actively developed. Your suggestions, bug reports, and collaboration proposals are welcome! Post them on <a href="https://github.com/jrpool/kilotest/issues">GitHub</a> or email them to <a href="mailto:info@kilotest.com">info@kilotest.com</a>.</p>
+        <p>In the current version, users can get results of already performed tests and can recommend new tests. Kilotest managers can approve recommendations.</p>
+      </details>
+      <h2>What do you want to know?</h2>
+      <ul class="nav">
+        <li><a href="targets.html">Which web pages have been tested?</a></li>
+        <li><a href="issues.html">Which issues have been reported?</a></li>
+        <li><a href="manage.html">What can Kilotest managers do?</a></li>
+      </ul>
+    </main>
+  </body>
+</html>