@jrpool/kilotest 30.0.3 → 31.0.1

package/index.js

@@ -14,6 +14,7 @@ const {
   getJobNames,
   getJSON,
   getLogPath,
+  getLogs,
   getObject,
   getPOSTData,
   getReport,
@@ -22,6 +23,7 @@ const {
   isHidden,
   isTimeStamp,
   isJobID,
+  isURL,
   jobsPath,
   logsPath,
   reportsPath,
@@ -198,7 +200,7 @@ const requestHandler = async (request, response) => {
     // Serve response headers, including one allowing requests from other applications.
     response.setHeader('Access-Control-Allow-Origin', '*');
     response.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-    response.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+    response.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
     response.statusCode = 204;
     response.end();
   }
@@ -568,10 +570,10 @@ const requestHandler = async (request, response) => {
       // Get the segments of the path after api.
       const segments = pathTail.split('/');
       // If the first segment is the ID of the Testaro agent and the agent is authenticated:
-      if (specs[0] === testaroAgent && postData.agentPW === testaroAgentPW) {
-        const agentID = specs[0];
+      if (segments[0] === testaroAgent && postData.agentPW === testaroAgentPW) {
+        const agentID = segments[0];
         // Get the requested service from the path.
-        const service = specs[1];
+        const service = segments[1];
         // If the service is job assignment:
         if (service === 'job') {
           let clean = true;
@@ -678,6 +680,41 @@ const requestHandler = async (request, response) => {
           );
         }
       }
+      // Otherwise, if the first segment is the test recommendation service:
+      else if (segments[0] === 'testRecForm') {
+        const {what, url, why} = postData;
+        const logs = await getLogs();
+        const whats = logs.map(log => log.what);
+        const urls = logs.map(log => log.url);
+        // If the payload is a valid test recommendation:
+        if (what && isURL(url) && why) {
+          // If an available report has the same URL or the same page description:
+          if (whats.includes(what) || urls.includes(url)) {
+            // Report this.
+            await serveError(
+              'ERROR: A report with the same page description or URL is already available',
+              response,
+              false
+            );
+          }
+          // Otherwise, i.e. if no report on the page is available:
+          else {
+            // Process the recommendation and get the response data.
+            const responseData = await require(path.join(__dirname, 'testRecForm', 'api'))
+            .response(what, url, why);
+            // Send them.
+            setHeaders('application/json', null, 'high');
+            response.end(JSON.stringify(responseData));
+          }
+        }
+      }
+      // Otherwise, i.e. if the request is invalid:
+      else {
+        // Report this.
+        await serveError(
+          {message: 'ERROR: Invalid API request'}, response, false
+        );
+      }
     }
     // Otherwise, if it is a tutorial comment:
     else if (pageName === 'tutorialComment.html') {

package/llms-full.txt

@@ -13,6 +13,7 @@ An LLM cannot produce for an AI agent thorough, accurate, and inexpensive inform
 - selects, as tools, an ensemble of 10 rule engines that implement tests for, in total, more than a thousand rules for front-end quality
 - runs the tests of the rule engines
 - combines the reports of the rule engines into a single integrated report
+- consolidates the 1000+ rules having 10 different naming systems into 300+ “issues” with a uniform naming system
 - extracts from the report statistics and details at the level of granularity required by an agent to fulfill any particular request
 
 ## How Kilotest integrates methods
@@ -30,11 +31,11 @@ LLMs that attempt to evaluate front-end quality with no delegation are likely to
 
 ## Kilotest versus other tools
 
-In the marketplace for MCPs that test for front-end quality, all tools other than Kilotest leverage at most 1 rule engine, typically `axe-core`. Kilotest leverages `axe-core` plus 9 other rule engines. This has these main effects:
+In the marketplace for MCP servers that test for front-end quality, all tools other than Kilotest leverage at most 1 rule engine, most often `axe-core`. Kilotest leverages `axe-core` plus 9 other rule engines. This has these main effects:
 
 - For pages that have not yet been tested, a single-tool MCP can provide faster results than Kilotest. A tool running only the `axe-core` tests can complete its work in about 5 seconds or less. Kilotest usually completes its work in 2 to 3 minutes, because some of the tests involve navigation and interaction with the page and LLM inference. Moreover, the Kilotest API feature suite is currently in an alpha phase, allowing agents, like human users, to **recommend** new pages for testing but allowing only managers to act on such recommendations. The wait for manager action can take up to a day. A feature permitting immediate testing ordered by AI agents is planned, but, until it is implemented, Kilotest will be useful for not-yet-tested pages only in long-running workflows.
-- For pages that have already been tested by Kilotest, Kilotest can provide faster results than a single-tool MCP, because Kilotest stores test results for subsequent retrieval. A retrieval from Kilotest can be completed in less than 2 seconds.
-- Kilotest results are more comprehensive than single-tool MCP results. Every rule engine provides limited coverage of front-end quality, so false negatives (missed defects) are more common with single-tool MCPs. This difference [has been documented in research](https://arxiv.org/pdf/2304.07591).
+- For pages that have already been tested by Kilotest, Kilotest can provide faster results than a single-tool MCP server, because Kilotest stores test results for subsequent retrieval. A retrieval from Kilotest can be completed in less than 2 seconds.
+- Kilotest results are more comprehensive than single-tool MCP server results. Every rule engine provides limited coverage of front-end quality, so false negatives (missed defects) are more common with single-tool MCP servers. This difference [has been documented in research](https://arxiv.org/pdf/2304.07591).
 
 ## How to use Kilotest
 
@@ -47,26 +48,42 @@ Kilotest offers a comprehensive suite of capabilities to users via its web UI:
 - Provide statistics about issues reported in one job: `https://kilotest.com/reportIssues.html/{timeStamp}/{jobID}`
 - Provide details about one issue reported in one job: `https://kilotest.com/reportIssue.html/{issueID}/{timeStamp}/{jobID}`
 - Provide diagnoses by tools of rule violations for one HTML element exhibiting one issue in one job: `https://kilotest.com/diagnoses.html/{issueID}/{timeStamp}/{jobID}/{catalogIndex}`
+- [Receive a recommendation to test a not-yet-tested page](`https://kilotest.com/testRecForm.html`)
+- Receive a recommendation to retest a previously tested page: `https://kilotest.com/retestRecForm.html/{timeStamp}/{jobID}`
 - [Provide statistics about frequently reported issues across all pages](https://kilotest.com/issues.html)
+- [List the operations that Kilotest managers are authorized to request](https://kilotest.com/manage.html)
 - [Tutorial, “Accessibility testing strategies”](https://kilotest.com/tutorial.html)
 - [Provide a list of features available for use of Kilotest managers](https://kilotest.com/manage.html)
 
 ### Agent API
 
-Kilotest is implementing a richer suite of capabilities optimized for AI agents, including direct immediate testing. The implementation is currently in an alpha phase and offers only two API endpoints, both for `GET` requests:
-
-- `targets`: [Summarize test results from all jobs](/api/targets) (a job is a session in which a web page is tested and a report is produced)
-- `reportIssues`: Provide statistics about issues reported in one job report: `/api/reportIssues/{timeStamp}/{jobID}` (the `timeStamp` and `jobID` parameters identify a particular report and are returned for each available report by the response to a `targets` request)
+Kilotest is implementing a richer suite of capabilities optimized for AI agents, including direct immediate testing. The implementation is currently in an alpha phase and offers 3 API endpoints:
+
+- `targets`
+  - method: `GET`
+  - purpose: summarize test results from all jobs (a job is a session in which a web page is tested and a report is produced)
+  - path: `/api/targets`
+- `reportIssues`
+  - method: `GET`
+  - purpose: provide statistics about issues reported in one job report
+  - path: `/api/reportIssues/{timeStamp}/{jobID}`
+  - parameters
+    - `timeStamp`: initial segment of job identifier
+    - `jobID`: final segment of job identifier
+  - source of parameters: response to a `targets` request
+- `testRecForm`
+  - method: `POST`
+  - purpose: receive a recommendation to test a not-yet-tested page
+  - path: `/api/testRecForm`
+  - payload properties
+    - `what`: description of the page to be tested
+    - `url`: URL of the page to be tested
+    - `why`: reason for testing the page
+  - how to verify disposition of the recommendation: submit a `targets` request and inspect the response to determine whether a report on the page is now available
 
 An [OpenAPI specification for Kilotest](https://kilotest.com/openapi.yaml) is available.
 
-Until direct immediate testing is available, an agent can recommend testing of a web page by either of two methods:
-
-- web UI: First verify that the page has not yet been tested, using the `targets` API endpoint. After that, complete and submit the [web UI recommendation form](https://kilotest.com/testRecForm.html).
-- email: Send a message to `info@kilotest.com`, identifying:
-  - the URL of the page to be tested
-  - a proper name for the page to be tested (e.g., “ABC Corporation contact page”)
-  - a reason for your recommendation (e.g., “Page users have reported accessibility problems”)
+Until direct immediate testing is available, an agent can recommend testing of a web page with a `testRecForm` request.
 
 ### More information
 

package/llms.txt

@@ -2,7 +2,7 @@
 
 Kilotest helps AI agents give thorough, accurate and truthful answers when users ask how accessible, usable, or standard conformant web pages are. Kilotest integrates ten independent rule engines to test web pages and report results with multipage, single-page, and element-level statistics and details.
 
-In the API section below, all endpoints require `GET` requests.
+In the API section below, all endpoints require `GET` requests except as noted.
 
 There is a [detailed explanation of Kilotest and its capabilities for AI agents](https://kilotest.com/llms-full.txt).
 
@@ -10,6 +10,7 @@ There is a [detailed explanation of Kilotest and its capabilities for AI agents]
 
 - [Summarize test results for all tested pages](/api/targets)
 - Provide statistics about issues reported in one job: `/api/reportIssues/{timeStamp}/{jobID}`
+- Recommend testing of a web page: `/api/testRecForm` (requires `POST` request)
 - [OpenAPI specification for Kilotest](https://kilotest.com/openapi.yaml)
 
 ## Web UI
@@ -19,4 +20,6 @@ There is a [detailed explanation of Kilotest and its capabilities for AI agents]
 - Provide details about one issue reported in one job: `https://kilotest.com/reportIssue.html/{issueID}/{timeStamp}/{jobID}`
 - Provide diagnoses about one issue exhibited by one HTML element in one job: `https://kilotest.com/diagnoses.html/{issueID}/{timeStamp}/{jobID}/{catalogIndex}`
 - [Provide statistics about frequently reported issues across all pages](https://kilotest.com/issues.html)
+- [Recommend testing of a web page](https://kilotest.com/testRecForm.html)
+- [List the operations that Kilotest managers are authorized to request](https://kilotest.com/manage.html)
 - [Tutorial, “Accessibility testing strategies”](https://kilotest.com/tutorial.html)

package/openapi.yaml

@@ -1,22 +1,42 @@
 openapi: 3.1.0
 info:
   title: Kilotest Agent API
-  description: Kilotest tests web pages for accessibility, usability, and standard conformity using an ensemble of ten independent tools that employ rule-based and machine-learning-based methods. This API enables AI agents to recommend web pages for testing (not yet implemented), discover available test reports, and retrieve data from reports at multiple levels of detail. For background on Kilotest and the advantages of ensemble testing, visit https://kilotest.com.
+  description: Kilotest tests web pages for accessibility, usability, and standard conformity using an ensemble of ten independent tools that employ rule-based and machine-learning-based methods. This API enables AI agents to recommend web pages for testing, discover available test reports, and retrieve data from reports. For background on Kilotest and the advantages of ensemble testing, visit https://kilotest.com.
   version: 1.0.0
   contact:
+    name: Kilotest
     url: https://kilotest.com
     email: info@kilotest.com
-    repository: https://github.com/jrpool/kilotest
 
 servers:
   - url: https://kilotest.com
     description: Kilotest production server
 
 paths:
-  /api/targets:
+  /api/testRecForm:
     post:
-      operationId: getReportSummaries
-      summary: Summarize all available reports
+      operationId: testRecForm
+      summary: Receives a testing recommendation
+      description: Receives a recommendation for Kilotest to test a particular web page.
+      requestBody:
+        description: Test recommendation specifications
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TestRecForm'
+      responses:
+        '200':
+          description: Acknowledgement of test recommendation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TestRecFormResponse'
+
+  /api/targets:
+    get:
+      operationId: targets
+      summary: Summarizes all available reports
       description: Returns summary data about every non-hidden report available from Kilotest, including the name and URL of the tested web page, when the testing was performed, how many issues were reported, and URLs for retrieving more detailed data from the report.
       responses:
         '200':
@@ -24,13 +44,13 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ReportSummariesResponse'
+                $ref: '#/components/schemas/TargetsResponse'
 
   /api/reportIssues/{timeStamp}/{jobID}:
-    post:
+    get:
       operationId: getReportIssues
-      summary: Get data on issues from a specific report
-      description: Returns data about the issues reported in a specific Kilotest report, grouped by priority. The data on each issue include the tools that reported it, the number of HTML elements exhibiting it, and URLs for retrieving element-level detail. The timeStamp and jobID components identify the report and are available in the getReportSummaries response.
+      summary: Gets data on issues from a specific report
+      description: Returns data about the issues reported in a specific Kilotest report, grouped by priority. The data on each issue include the tools that reported it, the number of HTML elements exhibiting it, and URLs for retrieving element-level detail. The timeStamp and jobID components identify the report and are available in the targets response.
       parameters:
         - name: timeStamp
           in: path
@@ -39,14 +59,16 @@ paths:
           schema:
             type: string
             pattern: '^\d{6}T\d{4}$'
-            example: '260503T0432'
+            examples:
+              - 260503T0432
         - name: jobID
           in: path
           required: true
           description: Job identifier component of the report identifier (e.g., xx0).
           schema:
             type: string
-            example: 'xx0'
+            examples:
+              - xx0
       responses:
         '200':
           description: Data on issues from the specified report
@@ -58,9 +80,9 @@ paths:
           description: No report with the specified identifier is available
 
   /api/reportIssue/{issueID}/{timeStamp}/{jobID}:
-    post:
+    get:
       operationId: getReportIssue
-      summary: Get details about a specific issue in a specific report (NOT YET IMPLEMENTED)
+      summary: Gets details about a specific issue in a specific report (NOT YET IMPLEMENTED)
       description: Returns details about a single issue within a specific report, including which HTML elements exhibit the issue and, for each such element, URLs for retrieving tool-by-tool diagnoses of the issue on the element. NOT YET IMPLEMENTED.
       parameters:
         - name: issueID
@@ -69,7 +91,8 @@ paths:
           description: Issue identifier (e.g., imageNoText). Available under "issues reported" > priority level > "identifier" in the getReportIssues response.
           schema:
             type: string
-            example: 'imageNoText'
+            examples:
+              - imageNoText
         - name: timeStamp
           in: path
           required: true
@@ -101,26 +124,47 @@ components:
           description: Natural-language description of this response and of Kilotest. Provides context for an agent encountering Kilotest for the first time.
         tool name:
           type: string
-          example: Kilotest
+          examples:
+            - Kilotest
         request:
           type: object
           properties:
-            requesting agent:
+            type of request:
               type: object
               properties:
                 identifier:
                   type: string
-                  example: research-agent
-                name:
+                description:
                   type: string
-                  example: Internal Research Agent
-            type of request:
+            method:
+              type: string
+              enum:
+                - GET
+                - POST
+            payload:
+              type: object
+              description: Present only for POST requests. The request payload.
+            URLs:
               type: object
               properties:
-                identifier:
+                'URL of your request':
                   type: string
-                description:
+                'equivalent URL for humans':
                   type: string
+            closest ancestor request:
+              oneOf:
+                - type: 'null'
+                - type: object
+                  properties:
+                    description:
+                      type: string
+                    URLs:
+                      type: object
+                      properties:
+                        'for you':
+                          type: string
+                        'for humans':
+                          type: string
         response metadata:
           type: object
           properties:
@@ -131,6 +175,22 @@ components:
               type: string
               format: date-time
 
+    TestRecForm:
+      type: object
+      properties:
+        what:
+          type: string
+          description: Description of the web page to be tested.
+        url:
+          type: string
+          description: URL of the web page to be tested.
+        why:
+          type: string
+          description: Reason for testing the page.
+
+    TestRecFormResponse:
+      $ref: '#/components/schemas/CommonResponseFields'
+
     ToolInfo:
       type: object
       description: An accessibility testing tool in the Kilotest ensemble.
@@ -138,15 +198,18 @@ components:
         identifier:
           type: string
           description: Short programmatic identifier for the tool.
-          example: alfa
+          examples:
+            - alfa
         name:
           type: string
           description: Display name of the tool.
-          example: Alfa
+          examples:
+            - Alfa
         sponsor:
           type: string
-          description: Organization that created or sponsors the tool.
-          example: Siteimprove
+          description: Organization that created, initially sponsored, or now sponsors the tool.
+          examples:
+            - Siteimprove
 
     ToolFailure:
       type: object
@@ -154,10 +217,12 @@ components:
       properties:
         name:
           type: string
-          example: WAVE
+          examples:
+            - WAVE
         reason for failure:
           type: string
-          example: Not enough credits.
+          examples:
+            - Not enough credits.
 
     ToolsSummary:
       type: object
@@ -183,13 +248,14 @@ components:
           format: uri
           description: URL for a human to view the next tier of detail.
 
-    ReportSummaryItem:
+    TargetsItem:
       type: object
       description: Summary data about a single available report.
       properties:
         identifier:
           type: string
-          example: 260504T1659-029
+          examples:
+            - 260504T1659-029
         creation date:
           type: string
           format: date-time
@@ -222,7 +288,7 @@ components:
           type: string
           format: uri
 
-    ReportSummariesResponse:
+    TargetsResponse:
       allOf:
         - $ref: '#/components/schemas/CommonResponseFields'
         - type: object
@@ -231,7 +297,7 @@ components:
               type: array
               description: One entry per available Kilotest report, in alphabetical order by page description and, in case of multiple reports per page, in order of creation date and time. Reports are matched by page description, not page URL, so, if only the URL of a page has changed between reports, the reports are treated as reports about the same page.
               items:
-                $ref: '#/components/schemas/ReportSummaryItem'
+                $ref: '#/components/schemas/TargetsItem'
 
     IssueEntry:
       type: object
@@ -239,22 +305,27 @@ components:
       properties:
         identifier:
           type: string
-          example: imageNoText
+          examples:
+            - imageNoText
         summary:
           type: string
           description: Brief natural-language label for the issue.
-          example: image not named
+          examples:
+            - image not named
         related WCAG 2.2 standard:
           type: object
           description: The WCAG 2.2 success criterion or guideline most closely related to this issue.
           properties:
             layer:
               type: string
-              enum: [guideline, success criterion]
+              enum:
+                - guideline
+                - success criterion
             'numeric identifier':
               type: string
               pattern: '^\d\.\d(\.\d+)?$'
-              example: '1.1.1'
+              examples:
+                - 1.1.1
         impact on a user:
           type: string
           description: How this issue is likely to affect users.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "30.0.3",
+  "version": "31.0.1",
   "description": "An ensemble testing service with a focus on accessibility",
   "main": "index.js",
   "scripts": {

package/reportIssues/api.js

@@ -62,7 +62,7 @@ exports.response = async args => {
   }));
   const thisHost = process.env.THIS_KILOTEST_HOST;
   // Get a response.
-  const response = {
+  const content = {
     summary: `This document fulfills a request made by an agent to the Kilotest service. The agent requested data from a Kilotest report about the accessibility, usability, and standard-conformity of a web page. Kilotest, with the help of Testaro, Testilo, and an ensemble of ten testing tools, performs tests on web pages, using a combination of rule- and machine-learning-based methods, and produces reports. Kilotest exposes several API endpoints for agents and several web UI URLs for humans to obtain information from Kilotest reports. To learn more about Kilotest and the advangages of testing with an ensemble of tools, visit the deployed instance of Kilotest (${process.env.DEPLOYED_KILOTEST_HOST}), which contains an introduction on its home page and a tutorial.`,
     'tool name': 'Kilotest',
     request: {
@@ -70,6 +70,7 @@ exports.response = async args => {
         identifier: 'reportIssues',
         description: 'What issues does the specified report describe?'
       },
+      method: 'GET',
       URLs: {
         'URL of your request': `${thisHost}/api/reportIssues/${timeStamp}/${jobID}`,
         'equivalent URL for humans': `${thisHost}/reportIssues.html/${timeStamp}/${jobID}`
@@ -122,5 +123,5 @@ exports.response = async args => {
       .map(issue => getIssueFacts(thisHost, timeStamp, jobID, issue))
     }
   };
-  return response;
+  return content;
 };

package/researchAgent.js

@@ -30,11 +30,11 @@ const port = hostParts[2] || (scheme === 'https' ? 443 : 80);
 
 // FUNCTIONS
 
-// Submits two request to a random Kilotest host.
+// Submits three request to a random Kilotest host.
 const requestService = async () => {
   const client = scheme === 'https' ? httpsClient : httpClient;
-  const getRequestOptions = path => ({
-    method: 'GET',
+  const getRequestOptions = (path, method = 'GET') => ({
+    method,
     host,
     port,
     path,
@@ -43,6 +43,7 @@ const requestService = async () => {
     }
   });
   const path = `/api/targets`;
+  console.log('======================');
   console.log(`About to submit ${scheme} request as JSON on port ${port} to ${host}${path}`);
   // Submit a targets request.
   client.request(getRequestOptions(path), response => {
@@ -65,15 +66,14 @@ const requestService = async () => {
       try {
         // Output it.
         const contentObj = JSON.parse(content);
-        console.log('======================');
         console.log(JSON.stringify(contentObj, null, 2));
         // Get the IDs of the available reports.
         const reportIDs = contentObj['available reports'].map(report => report.identifier);
         // Choose one at random.
         const [timeStamp, jobID] = reportIDs[Math.floor(Math.random() * reportIDs.length)]
         .split('-');
-        console.log('======================');
         const path = `/api/reportIssues/${timeStamp}/${jobID}`;
+  console.log('======================');
         console.log(`About to submit ${scheme} request as JSON on port ${port} to ${host}${path}`);
         const requestOptions = getRequestOptions(path);
         // Submit an issues request for it.
@@ -98,7 +98,47 @@ const requestService = async () => {
               // Output it.
               const contentObj = JSON.parse(content);
               console.log(JSON.stringify(contentObj, null, 2));
+              const testRecPath = `/api/testRecForm`;
               console.log('======================');
+              console.log(
+                `About to submit ${scheme} POST request as JSON on port ${port} to ${host}${testRecPath}`
+              );
+              const testRecOptions = getRequestOptions(testRecPath, 'POST');
+              // Submit a test recommendation.
+              client.request(testRecOptions, response => {
+                // Initialize a collection of data from the response.
+                const chunks = [];
+                response
+                // If the response throws an error:
+                .on('error', async error => {
+                  // Report it.
+                  console.log(error.message);
+                })
+                // If the response delivers data:
+                .on('data', chunk => {
+                  // Add them to the collection.
+                  chunks.push(chunk);
+                })
+                // When the response is completed:
+                .on('end', async () => {
+                  const content = chunks.join('');
+                  try {
+                    // Output it.
+                    const contentObj = JSON.parse(content);
+                    console.log(JSON.stringify(contentObj, null, 2));
+                  }
+                  catch (error) {
+                    console.log(error.message);
+                    console.log(`Test recommendation response content: ${content || 'No content'}`);
+                  }
+                });
+              })
+              // Finish sending the test recommendation request.
+              .end(JSON.stringify({
+                what: 'Page Not Already Tested',
+                url: 'https://pagenotalreadytested.info',
+                why: 'This is only a test'
+              }));
             }
             catch (error) {
               console.log(error.message);

package/sitemap.xml

@@ -3,6 +3,8 @@
   <url><loc>https://kilotest.com/</loc></url>
   <url><loc>https://kilotest.com/targets.html</loc></url>
   <url><loc>https://kilotest.com/issues.html</loc></url>
+  <url><loc>https://kilotest.com/testRecForm.html</loc></url>
+  <url><loc>https://kilotest.com/manage.html</loc></url>
   <url><loc>https://kilotest.com/tutorial.html</loc></url>
   <url><loc>https://kilotest.com/openapi.yaml</loc></url>
   <url><loc>https://kilotest.com/llms.txt</loc></url>

package/targets/api.js

@@ -82,10 +82,12 @@ exports.response = async () => {
         identifier: 'targets',
         description: 'Give me summary data about each available report.'
       },
+      method: 'GET',
       URLs: {
         'URL of your request': `${thisHost}/api/targets`,
         'equivalent URL for humans': `${thisHost}/targets.html`
-      }
+      },
+      'closest ancestor request': null
     },
     'response metadata': {
       identifier: `${getNowStamp()}-${getRandomString(3)}`,

package/testRecForm/api.js

@@ -0,0 +1,48 @@
+/*
+  api.js
+  Responds to the test-recommendation request.
+*/
+
+// IMPORTS
+
+const {
+  getNowStamp,
+  getRandomString,
+  updateRecs
+} = require('../util');
+
+// FUNCTIONS
+
+// Returns a response to a test-recommendation request.
+exports.response = async (what, url, why) => {
+  const thisHost = process.env.THIS_KILOTEST_HOST;
+  // Record the recommendation.
+  await updateRecs(what, url, why);
+  // Get a response.
+  const content = {
+    summary: `This response acknowledges a request made by an agent to the Kilotest service. The agent recommended that Kilotest test the ${what} web page at ${url} for accessibility, usability, and standard-conformity. A Kilotest manager usually approves a recommendation within a day. When the recommendation is approved, the testing will be performed and results will become available. You can check for the availability of the results at ${thisHost}/api/targets. Kilotest performs its testing with the help of Testaro, Testilo, and an ensemble of ten testing tools, using a combination of rule- and machine-learning-based methods. Kilotest exposes several API endpoints for agents and several web UI URLs for humans to obtain information from Kilotest reports. To learn more about Kilotest and the advangages of testing with an ensemble of tools, visit the deployed instance of Kilotest (${process.env.DEPLOYED_KILOTEST_HOST}), which contains an introduction on its home page and a tutorial.`,
+    'tool name': 'Kilotest',
+    request: {
+      'type of request': {
+        identifier: 'testRecForm',
+        description: 'I recommend that Kilotest test a particular web page.'
+      },
+      method: 'POST',
+      payload: {
+        'description of the web page': what,
+        'URL of the web page': url,
+        'reason for testing the web page': why
+      },
+      URLs: {
+        'URL of your request': `${thisHost}/api/testRecForm`,
+        'equivalent URL for humans': `${thisHost}/testRecForm.html`
+      },
+      'closest ancestor request': null
+    },
+    'response metadata': {
+      identifier: `${getNowStamp()}-${getRandomString(3)}`,
+      'date and time': new Date().toISOString()
+    }
+  };
+  return content;
+};

package/util.js

@@ -626,6 +626,20 @@ const getPlainText = string => string.replace(/&/g, '+').replace(/[<>"'&]/g, ' '
 const getNowStamp = exports.getNowStamp = () => {
   return getTimeStamp(new Date());
 };
+// Updates the test recommendations.
+const updateRecs = exports.updateRecs = async (what, url, why) => {
+  // Get the data on waiting recommendations.
+  const recs = await getRecs();
+  recs[url] ??= [];
+  // Add the recommendation to those for the target.
+  recs[url].push({
+    timeStamp: getNowStamp(),
+    what,
+    why
+  });
+  // Save the revised recommendations.
+  await fs.writeFile(recsPath, getJSON(recs));
+};
 // Processes a test or retest recommendation.
 exports.processRec = async (testType, dirName, what, url, why) => {
   // If the recommendation is valid:
@@ -638,17 +652,8 @@ exports.processRec = async (testType, dirName, what, url, why) => {
   ) {
     // Make the reason display-safe.
     const plainWhy = getPlainText(why);
-    // Get the data on waiting recommendations.
-    const recs = await getRecs();
-    recs[url] ??= [];
-    // Add the recommendation to those for the target.
-    recs[url].push({
-      timeStamp: getNowStamp(),
-      what,
-      why: plainWhy
-    });
-    // Save the revised recommendations.
-    await fs.writeFile(recsPath, getJSON(recs));
+    // Update the waiting recommendations.
+    await updateRecs(what, url, plainWhy);
     // Log the recommendation.
     console.log(`Test recommendation received for ${what}: ${plainWhy}`);
     // Alert a manager about it.