@jrpool/kilotest 59.1.3 → 60.0.0

package/api/listIssues.ts

@@ -36,12 +36,12 @@ type ResponseContent = z.infer<typeof listIssuesResponseSchema>['response conten
 
 // Returns the response body.
 export const response = async (args: string[]) => {
-  const [timeStamp = '', jobID = ''] = args;
+  const [reportID = ''] = args;
   const thisHost = getThisHost();
   // Get the report.
-  const report = await getReport(timeStamp, jobID);
+  const report = await getReport(reportID);
   // Get the basics about the report (which may be only an error message).
-  const reportBasics = isReportError(report) ? report : await getReportBasics(timeStamp, jobID);
+  const reportBasics = isReportError(report) ? report : await getReportBasics(reportID);
   // Initialize the response content.
   const responseContent: ResponseContent = {
     'basics about the report': reportBasics,
@@ -68,21 +68,19 @@ export const response = async (args: string[]) => {
       const lastIndex = pageExtracts.length - 1;
       // Add the history of reports about the page to the response content.
       responseContent['history of reports about the page'] = pageExtracts.map((extract, index) => {
-        const extractTimeStamp = extract.timeStamp;
-        const extractJobID = extract.jobID;
+        const extractID = extract.id;
         return {
-          identifier: `${extractTimeStamp}-${extractJobID}`,
+          identifier: extractID,
           'completion date and time': extract.reportTime,
           'days since the report was completed': getAgoDays(new Date(extract.reportTime)),
           'whether it is the oldest report about the page': index === 0,
           'whether it is the latest report about the page': index === lastIndex,
-          'whether it is the report described in this response':
-          extractTimeStamp === timeStamp && extractJobID === jobID,
+          'whether it is the report described in this response': extractID === reportID,
           'how to get details about the report': {
             method: 'GET' as const,
-            URL: `${thisHost}/api/listIssues/${extractTimeStamp}/${extractJobID}`
+            URL: `${thisHost}/api/listIssues/${extractID}`
           },
-          'web users can get details about the report at': `${thisHost}/listIssues.html/${extractTimeStamp}/${extractJobID}`
+          'web users can get details about the report at': `${thisHost}/listIssues.html/${extractID}`
         };
       });
       // Get details about the job definition.
@@ -165,7 +163,7 @@ export const response = async (args: string[]) => {
         'number of elements reported as violators': violatorIndexes.size
       };
       // Get the size of the report.
-      const reportStats = await getReportStats(timeStamp, jobID);
+      const reportStats = await getReportStats(reportID);
       // If this succeeded:
       if (reportStats) {
         const {reportSize} = reportStats;
@@ -173,11 +171,11 @@ export const response = async (args: string[]) => {
         responseContent['how to get the full report in JSON'] = {
           'size of the report in bytes': reportSize,
           method: 'GET',
-          URL: `${thisHost}/api/getReport/${timeStamp}/${jobID}`
+          URL: `${thisHost}/api/getReport/${reportID}`
         };
         // Add instructions for web users to get the full report to the response content.
         responseContent['how a web user can get the full report in JSON'] = {
-          URL: `${thisHost}/fullReport.json/${timeStamp}/${jobID}`
+          URL: `${thisHost}/fullReport.json/${reportID}`
         };
       }
       // Add the details about the job and test results to the response content.
@@ -197,7 +195,7 @@ export const response = async (args: string[]) => {
         // Add instructions for a retest request to the response content.
         responseContent['how to request that the page be retested'] = {
           method: 'POST',
-          URL: `${thisHost}/api/requestRetest/${timeStamp}/${jobID}`,
+          URL: `${thisHost}/api/requestRetest/${reportID}`,
           'request body': {
             reason: '20- to 100-character reason why the page should be retested'
           },
@@ -206,7 +204,7 @@ export const response = async (args: string[]) => {
         };
         // Add instructions for a web user to request a retest.
         responseContent['how a web user can request that the page be retested'] = {
-          URL: `${thisHost}/requestRetestForm.html/${timeStamp}/${jobID}`
+          URL: `${thisHost}/requestRetestForm.html/${reportID}`
         };
       }
       // Sort the data about issues by summary.
@@ -223,9 +221,9 @@ export const response = async (args: string[]) => {
           .map(ruleEnginesFact => ruleEnginesFact.name),
           'how to get details about the issue': {
             method: 'GET' as const,
-            URL: `${thisHost}/api/listViolators/${id}/${timeStamp}/${jobID}`
+            URL: `${thisHost}/api/listViolators/${id}/${reportID}`
           },
-          'web users can get details about the issue at': `${thisHost}/listViolators.html/${id}/${timeStamp}/${jobID}`
+          'web users can get details about the issue at': `${thisHost}/listViolators.html/${id}/${reportID}`
         };
       });
       // Add the basics about the issues to the response content.
@@ -237,9 +235,9 @@ export const response = async (args: string[]) => {
     'tool collection': getToolsFacts(),
     'tool name': 'listIssues',
     'this request': {
-      description: 'Provide details about one report, including basics about the issues reported in it. The timeStamp and jobID parameters identify the report that I want details about. Those parameters were in the response to my earlier listPages request, or in the history of reports about the page in an earlier listIssues response.',
+      description: 'Provide details about one report, including basics about the issues reported in it. The reportID parameter identifies the report that I want details about. It was in the response to my earlier listPages request, or in the history of reports about the page in an earlier listIssues response.',
       method: 'GET',
-      URL: `${thisHost}/api/listIssues/${timeStamp}/${jobID}`,
+      URL: `${thisHost}/api/listIssues/${reportID}`,
       'closest ancestor request': {
         'tool name': 'listPages',
         description: 'Provide basics about all tested pages.',
@@ -248,7 +246,7 @@ export const response = async (args: string[]) => {
       }
     },
     'URLs of similar requests for web users': {
-      'this request': `${thisHost}/listIssues.html/${timeStamp}/${jobID}`,
+      'this request': `${thisHost}/listIssues.html/${reportID}`,
       'closest ancestor request': `${thisHost}/listPages.html`
     },
     'response metadata': getResponseMetadata(),

package/api/listPages.test.ts

@@ -63,8 +63,8 @@ test('listPages describes a multi-report page by its latest report and its repor
   assert.equal(latest['completion date and time'], '2026-02-02T00:10:00.000Z');
   assert.equal(typeof latest['days since the report was completed'], 'number');
   assert.equal(mixed['how to get details about the latest report'].method, 'GET');
-  assert.ok(mixed['how to get details about the latest report'].URL.endsWith('/api/listIssues/260202T0000/new'));
-  assert.ok(mixed['web users can get details about the latest report at'].endsWith('/listIssues.html/260202T0000/new'));
+  assert.ok(mixed['how to get details about the latest report'].URL.endsWith('/api/listIssues/260202T0000-new'));
+  assert.ok(mixed['web users can get details about the latest report at'].endsWith('/listIssues.html/260202T0000-new'));
 });
 
 test('listPages describes a single-report page', async () => {

package/api/listPages.ts

@@ -31,7 +31,7 @@ export const response = async () => {
   const pagesBasics: ResponseContent['basics about all tested pages'] = [];
   // For each report:
   reportExtracts.forEach(extract => {
-    const {description, jobID, reportTime, superseded, timeStamp, url} = extract;
+    const {description, id, reportTime, superseded, url} = extract;
     // If it is the latest report about its page:
     if (!superseded) {
       // Add basics about the page, with instructions for getting details, to the array.
@@ -42,15 +42,15 @@ export const response = async () => {
         },
         'number of reports about the page': reportCounts.get(description)!,
         'basics about the latest report': {
-          identifier: `${timeStamp}-${jobID}`,
+          identifier: id,
           'completion date and time': reportTime,
           'days since the report was completed': getAgoDays(new Date(reportTime))
         },
         'how to get details about the latest report': {
           method: 'GET',
-          URL: `${thisHost}/api/listIssues/${timeStamp}/${jobID}`
+          URL: `${thisHost}/api/listIssues/${id}`
         },
-        'web users can get details about the latest report at': `${thisHost}/listIssues.html/${timeStamp}/${jobID}`
+        'web users can get details about the latest report at': `${thisHost}/listIssues.html/${id}`
       });
     }
   });

package/api/listViolators.test.ts

@@ -29,7 +29,7 @@ after(() => {
 // TESTS
 
 test('listViolators returns 1 violator for linkNoText in the mixed report, excluding cantTell', async () => {
-  const body = await response(['linkNoText', '260101T0000', 'mix']);
+  const body = await response(['linkNoText', '260101T0000-mix']);
   const violators = body['response content']['basics about all elements exhibiting the issue'] as any;
   assert.equal(violators.length, 1);
   assert.equal(violators[0].identifier, '0');
@@ -39,32 +39,32 @@ test('listViolators returns 1 violator for linkNoText in the mixed report, exclu
 });
 
 test('listViolators returns 0 violators for an issue when all instances are cantTell', async () => {
-  const body = await response(['focusIndicationBad', '260101T0001', 'ct']);
+  const body = await response(['focusIndicationBad', '260101T0001-ct']);
   const violators = body['response content']['basics about all elements exhibiting the issue'] as any;
   assert.equal(violators.length, 0);
 });
 
 test('listViolators treats missing outcome as a violation', async () => {
-  const body = await response(['linkNoText', '260101T0002', 'no']);
+  const body = await response(['linkNoText', '260101T0002-no']);
   const violators = body['response content']['basics about all elements exhibiting the issue'] as any;
   assert.equal(violators.length, 1);
   assert.equal(violators[0].identifier, '0');
 });
 
 test('listViolators returns an error for an unknown issue ID', async () => {
-  const body = await response(['nonexistentIssue', '260101T0000', 'mix']);
+  const body = await response(['nonexistentIssue', '260101T0000-mix']);
   const basics = body['response content']['basics about the issue'] as any;
   assert.ok(basics.error);
 });
 
 test('listViolators returns an error for a nonexistent report', async () => {
-  const body = await response(['linkNoText', '999999T9999', 'xyz']);
+  const body = await response(['linkNoText', '999999T9999-xyz']);
   const basics = body['response content']['basics about the report'] as any;
   assert.ok(basics.error);
 });
 
 test('listViolators includes reporter facts for the issue', async () => {
-  const body = await response(['linkNoText', '260101T0000', 'mix']);
+  const body = await response(['linkNoText', '260101T0000-mix']);
   const details = body['response content']['details about the issue'] as any;
   const reporters = details['rule engines reporting violations belonging to the issue'];
   const names = reporters.map((r: any) => r.name).sort();
@@ -72,7 +72,7 @@ test('listViolators includes reporter facts for the issue', async () => {
 });
 
 test('listViolators sorts by catalogIndex when two violators have the same reporter count', async () => {
-  const body = await response(['linkNoText', '260101T0008', 'mul']);
+  const body = await response(['linkNoText', '260101T0008-mul']);
   const violators = body['response content']['basics about all elements exhibiting the issue'] as any;
   assert.equal(violators.length, 3);
   // The violator with 2 reporters (catalogIndex 2) sorts first.
@@ -86,13 +86,13 @@ test('listViolators sorts by catalogIndex when two violators have the same repor
 });
 
 test('listViolators returns guideline layer for an issue with a short WCAG code', async () => {
-  const body = await response(['duplicateID', '260101T0009', 'brd']);
+  const body = await response(['duplicateID', '260101T0009-brd']);
   const issueBasics = body['response content']['basics about the issue'] as any;
   assert.equal(issueBasics['related WCAG standard'].layer, 'guideline');
 });
 
 test('listViolators returns null tag name and text for a violator not in the catalog', async () => {
-  const body = await response(['duplicateID', '260101T0009', 'brd']);
+  const body = await response(['duplicateID', '260101T0009-brd']);
   const violators = body['response content']['basics about all elements exhibiting the issue'] as any;
   const orphan = violators.find((v: any) => v.identifier === '3');
   assert.ok(orphan);
@@ -101,7 +101,7 @@ test('listViolators returns null tag name and text for a violator not in the cat
 });
 
 test('listViolators returns an error for a falsy issue ID', async () => {
-  const body = await response(['', '260101T0009', 'brd']);
+  const body = await response(['', '260101T0009-brd']);
   const issueBasics = body['response content']['basics about the issue'] as any;
   assert.ok(issueBasics.error);
 });

package/api/listViolators.ts

@@ -26,13 +26,13 @@ type ResponseContent = z.infer<typeof listViolatorsResponseSchema>['response con
 
 // Returns the response body.
 export const response = async (args: string[]) => {
-  const [issueID = '', timeStamp = '', jobID = ''] = args;
+  const [issueID = '', reportID = ''] = args;
   const thisHost = getThisHost();
   // Get the report.
-  const report = await getReport(timeStamp, jobID);
+  const report = await getReport(reportID);
   // Initialize the response content.
   const responseContent: ResponseContent = {
-    'basics about the report': isReportError(report) ? report : await getReportBasics(timeStamp, jobID),
+    'basics about the report': isReportError(report) ? report : await getReportBasics(reportID),
     'basics about the issue': {
       'error': 'No information about the specified issue is available'
     },
@@ -105,10 +105,10 @@ export const response = async (args: string[]) => {
           'inner text': catalogItem?.text ?? null,
           'count of rule engines reporting that the element exhibited the issue': reporters.size,
           'how to get details about the element': {
-            URL: `${thisHost}/api/listDiagnoses/${catalogIndex}/${issueID}/${timeStamp}/${jobID}`,
+            URL: `${thisHost}/api/listDiagnoses/${catalogIndex}/${issueID}/${reportID}`,
             'request method': 'GET' as const
           },
-          'web users can get details about the element at': `${thisHost}/listDiagnoses.html/${issueID}/${timeStamp}/${jobID}/${catalogIndex}`
+          'web users can get details about the element at': `${thisHost}/listDiagnoses.html/${issueID}/${reportID}/${catalogIndex}`
         };
       });
       // Add basics about the violators to the response content.
@@ -120,19 +120,19 @@ export const response = async (args: string[]) => {
     'tool collection': getToolsFacts(),
     'tool name': 'listViolators',
     'this request': {
-      description: 'Provide details about one issue in one report, including basics about the elements of the tested page that exhibited the issue. The issueID, timeStamp, and jobID parameters identify the issue and report that I want details about. Those parameters were in the response to my earlier listIssues request.',
+      description: 'Provide details about one issue in one report, including basics about the elements of the tested page that exhibited the issue. The issueID and reportID parameters identify the issue and report that I want details about. Those parameters were in the response to my earlier listIssues request.',
       method: 'GET',
-      URL: `${thisHost}/api/listViolators/${issueID}/${timeStamp}/${jobID}`,
+      URL: `${thisHost}/api/listViolators/${issueID}/${reportID}`,
       'closest ancestor request': {
         'tool name': 'listIssues',
         description: 'Provide details about one report, including basics about the issues reported in it.',
         method: 'GET',
-        URL: `${thisHost}/api/listIssues/${timeStamp}/${jobID}`
+        URL: `${thisHost}/api/listIssues/${reportID}`
       }
     },
     'URLs of similar requests for web users': {
-      'this request': `${thisHost}/listViolators.html/${issueID}/${timeStamp}/${jobID}`,
-      'closest ancestor request': `${thisHost}/listIssues.html/${timeStamp}/${jobID}`
+      'this request': `${thisHost}/listViolators.html/${issueID}/${reportID}`,
+      'closest ancestor request': `${thisHost}/listIssues.html/${reportID}`
     },
     'response metadata': getResponseMetadata(),
     'response content': responseContent

package/api/orderNewTest.test.ts

@@ -194,8 +194,7 @@ test('orderNewTest accepts a valid new page order and enqueues a job directly',
   assert.equal(details['page to be tested'].description, 'Brand New Ordered Page');
   const disposition = body['response content']['disposition of your order'] as any;
   assert.ok(disposition['report identifier']);
-  assert.match(disposition['report identifier'].timeStamp, /^\d{6}T\d{4}$/);
-  assert.match(disposition['report identifier'].jobID, /^[a-z0-9]{3}$/);
+  assert.match(disposition['report identifier'], /^\d{6}T\d{4}-[a-z0-9]{3}$/);
   assert.ok(disposition['what happens next'].includes('Testing has begun.'));
   assert.ok(disposition['do you want to wait for completion'].includes('awaitTest'));
   const queuedFiles = await fs.readdir(queuePath);

package/api/orderNewTest.ts

@@ -88,12 +88,11 @@ export const response = async (args: string[]) => {
     };
     // Add information about the disposition of the order.
     if (orderResult.result === 'ok') {
-      const [timeStamp, reportJobID] = orderResult.jobID.split('-') as [string, string];
       requestDisposition = {
         'what happens next': 'Testing has begun. Once it finishes, the report will be available via the listIssues tool.',
-        'report identifier': {timeStamp, jobID: reportJobID},
-        'how you can check for completion': `Call the listIssues tool with timeStamp "${timeStamp}" and jobID "${reportJobID}" to learn whether the report is ready.`,
-        'do you want to wait for completion': 'Testing typically takes 2 to 4 minutes. Do you want to wait (and be notified of completion) instead of checking back later? If so, call the awaitTest tool with the same timeStamp and jobID.'
+        'report identifier': orderResult.reportID,
+        'how you can check for completion': `Call the listIssues tool with reportID "${orderResult.reportID}" to learn whether the report is ready.`,
+        'do you want to wait for completion': 'Testing typically takes 2 to 4 minutes. Do you want to wait (and be notified of completion) instead of checking back later? If so, call the awaitTest tool with the same reportID.'
       };
     }
     else {

package/api/orderRetest.test.ts

@@ -62,26 +62,26 @@ after(async () => {
 // TESTS
 
 test('orderRetest rejects a nonexistent report', async () => {
-  const body = await response(['251231T0000', 'zzz', 'A reason that is long enough.']);
+  const body = await response(['251231T0000-zzz', 'A reason that is long enough.']);
   const details = body['response content']['details about your order'] as any;
   assert.ok(details.error.includes('does not exist'));
 });
 
 test('orderRetest rejects a malformed timestamp or job identifier', async () => {
-  const body = await response(['999999T9999', 'xyz', 'A reason that is long enough.']);
+  const body = await response(['999999T9999-xyz', 'A reason that is long enough.']);
   const details = body['response content']['details about your order'] as any;
   assert.ok(details.error.includes('malformed'));
 });
 
 test('orderRetest rejects a reason shorter than 20 characters', async () => {
-  const body = await response(['260101T0004', 'ord', 'short']);
+  const body = await response(['260101T0004-ord', 'short']);
   const details = body['response content']['details about your order'] as any;
   assert.ok(details.error.includes('reason'));
 });
 
 test('orderRetest rejects a reason longer than 100 characters', async () => {
   const longReason = 'x'.repeat(101);
-  const body = await response(['260101T0004', 'ord', longReason]);
+  const body = await response(['260101T0004-ord', longReason]);
   const details = body['response content']['details about your order'] as any;
   assert.ok(details.error.includes('reason'));
 });
@@ -89,7 +89,7 @@ test('orderRetest rejects a reason longer than 100 characters', async () => {
 test('orderRetest rejects a superseded report', async () => {
   // 260101T0000-mix is an earlier report of "Mixed Outcomes" than 260202T0000-new,
   // so it is superseded.
-  const body = await response(['260101T0000', 'mix', 'A reason that is long enough.']);
+  const body = await response(['260101T0000-mix', 'A reason that is long enough.']);
   const details = body['response content']['details about your order'] as any;
   assert.equal(details.error, undefined);
   const disposition = body['response content']['disposition of your order'] as any;
@@ -105,7 +105,7 @@ test('orderRetest rejects a report matching a claimed job by description', async
     target: {what: 'Order Retest Fixture Page', url: 'https://example.com/unrelated'}
   }));
   try {
-    const body = await response(['260101T0004', 'ord', 'A reason that is long enough.']);
+    const body = await response(['260101T0004-ord', 'A reason that is long enough.']);
     const details = body['response content']['details about your order'] as any;
     assert.equal(details.error, undefined);
     const disposition = body['response content']['disposition of your order'] as any;
@@ -125,7 +125,7 @@ test('orderRetest rejects a report matching a queued job by URL', async () => {
     target: {what: 'Some Other Page', url: 'https://example.com/orderretestfixture'}
   }));
   try {
-    const body = await response(['260101T0004', 'ord', 'A reason that is long enough.']);
+    const body = await response(['260101T0004-ord', 'A reason that is long enough.']);
     const details = body['response content']['details about your order'] as any;
     assert.equal(details.error, undefined);
     const disposition = body['response content']['disposition of your order'] as any;
@@ -144,7 +144,7 @@ test('orderRetest rejects an order once the job queue is full', async () => {
   await fs.writeFile(fillerPath, JSON.stringify({target: {what: 'Filler', url: 'https://example.com/filler'}}));
   process.env.JOB_QUEUE_MAX = '1';
   try {
-    const body = await response(['260101T0004', 'ord', 'A reason that is long enough.']);
+    const body = await response(['260101T0004-ord', 'A reason that is long enough.']);
     const details = body['response content']['details about your order'] as any;
     assert.equal(details.error, undefined);
     const disposition = body['response content']['disposition of your order'] as any;
@@ -156,7 +156,7 @@ test('orderRetest rejects an order once the job queue is full', async () => {
 });
 
 test('orderRetest accepts a valid retest order and enqueues a job directly', async () => {
-  const body = await response(['260101T0004', 'ord', 'A reason that is long enough.']);
+  const body = await response(['260101T0004-ord', 'A reason that is long enough.']);
   const details = body['response content']['details about your order'] as any;
   assert.equal(details.error, undefined);
   assert.equal(details['page to be retested'].description, 'Order Retest Fixture Page');
@@ -172,7 +172,7 @@ test('orderRetest accepts a valid retest order and enqueues a job directly', asy
 });
 
 test('orderRetest response omits a web UI URL for this request but includes the ancestor', async () => {
-  const body = await response(['260101T0004', 'ord', 'A reason that is long enough.']);
+  const body = await response(['260101T0004-ord', 'A reason that is long enough.']);
   const similarWeb = body['URLs of similar requests for web users'] as any;
   assert.equal(similarWeb['this request'], null);
   assert.ok(similarWeb['closest ancestor request'].includes('listIssues.html'));

package/api/orderRetest.ts

@@ -7,7 +7,7 @@
 
 import {z} from 'zod';
 import {getRequestFailureReason, getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
-import {checkLength, isJobID, isTimeStamp, orderJob} from '../util.ts';
+import {checkLength, isReportID, orderJob} from '../util.ts';
 import {orderRetestResponseSchema} from './schemas.ts';
 
 // TYPES
@@ -19,16 +19,16 @@ type ResponseContent = z.infer<typeof orderRetestResponseSchema>['response conte
 
 // Returns the response body.
 export const response = async (args: string[]) => {
-  const [timeStamp = '', jobID = '', reason = ''] = args;
+  const [reportID = '', reason = ''] = args;
   const thisHost = getThisHost();
   const reasonCheck = checkLength(reason, 20, 100, 'reason');
   // Initialize the response-content properties.
   let requestDetails: ResponseContent['details about your order'];
   let requestDisposition: ResponseContent['disposition of your order'] = null;
-  // If the timestamp or job ID is not syntactically valid:
-  if (!isTimeStamp(timeStamp) || !isJobID(jobID)) {
+  // If the report identifier is not syntactically valid:
+  if (!isReportID(reportID)) {
     requestDetails = {
-      error: 'order invalid: the report timestamp or job identifier is malformed'
+      error: 'order invalid: the reportID is malformed'
     };
   }
   // Otherwise, if the encoded reason is too short or too long:
@@ -43,7 +43,7 @@ export const response = async (args: string[]) => {
     // no manual-approval step, gated only by the lightweight checks orderJob itself
     // performs (the target is not already claimed or queued, and the job queue is not
     // already full). This resolves the cited report's description and URL itself.
-    const orderResult = await orderJob({timeStamp, jobID}, reason);
+    const orderResult = await orderJob({reportID}, reason);
     // If the cited report does not exist:
     if (orderResult.result === 'nonreport') {
       requestDetails = {
@@ -63,12 +63,11 @@ export const response = async (args: string[]) => {
       };
       // Add information about the disposition of the order.
       if (orderResult.result === 'ok') {
-        const [reportTimeStamp, reportJobID] = orderResult.jobID.split('-') as [string, string];
         requestDisposition = {
           'what happens next': 'Testing has begun. Once it finishes, the report will be available via the listIssues tool.',
-          'report identifier': {timeStamp: reportTimeStamp, jobID: reportJobID},
-          'how you can check for completion': `Call the listIssues tool with timeStamp "${reportTimeStamp}" and jobID "${reportJobID}" to learn whether the report is ready.`,
-          'do you want to wait for completion': 'Testing typically takes 2 to 4 minutes. Do you want to wait (and be notified of completion) instead of checking back later? If so, call the awaitTest tool with the same timeStamp and jobID.'
+          'report identifier': orderResult.reportID,
+          'how you can check for completion': `Call the listIssues tool with reportID "${orderResult.reportID}" to learn whether the report is ready.`,
+          'do you want to wait for completion': 'Testing typically takes 2 to 4 minutes. Do you want to wait (and be notified of completion) instead of checking back later? If so, call the awaitTest tool with the same reportID.'
         };
       }
       else {
@@ -94,9 +93,9 @@ export const response = async (args: string[]) => {
     'tool collection': getToolsFacts(),
     'tool name': 'orderRetest',
     'this request': {
-      description: 'Process my order to retest a page, immediately and without manual approval. The timeStamp and jobID parameters identify the latest available report about the page. Those parameters were in the response to my earlier listIssues request. The reason property of the request body is the reason why the page should be retested.',
+      description: 'Process my order to retest a page, immediately and without manual approval. The reportID parameter identifies the latest available report about the page. It was in the response to my earlier listIssues request. The reason property of the request body is the reason why the page should be retested.',
       method: 'POST',
-      URL: `${thisHost}/api/orderRetest/${timeStamp}/${jobID}`,
+      URL: `${thisHost}/api/orderRetest/${reportID}`,
       body: {
         reason
       },
@@ -104,12 +103,12 @@ export const response = async (args: string[]) => {
         'tool name': 'listIssues',
         description: 'Provide details about one report, including basics about the issues reported in it.',
         method: 'GET',
-        URL: `${thisHost}/api/listIssues/${timeStamp}/${jobID}`
+        URL: `${thisHost}/api/listIssues/${reportID}`
       }
     },
     'URLs of similar requests for web users': {
       'this request': null,
-      'closest ancestor request': `${thisHost}/listIssues.html/${timeStamp}/${jobID}`
+      'closest ancestor request': `${thisHost}/listIssues.html/${reportID}`
     },
     'response metadata': getResponseMetadata(),
     'response content': responseContent

package/api/requestRetest.test.ts

@@ -71,14 +71,14 @@ after(async () => {
 // TESTS
 
 test('requestRetest rejects a nonexistent report', async () => {
-  const body = await response(['251231T0000', 'zzz', 'A reason that is long enough.']);
+  const body = await response(['251231T0000-zzz', 'A reason that is long enough.']);
   const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('does not exist'));
   assert.ok(!logged.some(line => line.includes('request for a retest awaits approval')));
 });
 
 test('requestRetest rejects a malformed timestamp or job identifier', async () => {
-  const body = await response(['999999T9999', 'xyz', 'A reason that is long enough.']);
+  const body = await response(['999999T9999-xyz', 'A reason that is long enough.']);
   const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('malformed'));
   assert.ok(!logged.some(line => line.includes('request for a retest awaits approval')));
@@ -88,7 +88,7 @@ test('requestRetest rejects a superseded report', async () => {
   // 260101T0000-mix is an earlier report of "Mixed Outcomes" than 260202T0000-new,
   // so it is superseded and processTestRequest returns 'superseded', reported via the
   // disposition rather than details.error.
-  const body = await response(['260101T0000', 'mix', 'A reason that is long enough.']);
+  const body = await response(['260101T0000-mix', 'A reason that is long enough.']);
   const details = body['response content']['details about your request'] as any;
   assert.equal(details.error, undefined);
   const disposition = body['response content']['disposition of your request'] as any;
@@ -99,7 +99,7 @@ test('requestRetest rejects a superseded report', async () => {
 });
 
 test('requestRetest rejects a reason shorter than 20 characters', async () => {
-  const body = await response(['260101T0003', 'ret', 'short']);
+  const body = await response(['260101T0003-ret', 'short']);
   const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('reason'));
   assert.ok(!logged.some(line => line.includes('request for a retest awaits approval')));
@@ -107,7 +107,7 @@ test('requestRetest rejects a reason shorter than 20 characters', async () => {
 
 test('requestRetest rejects a reason longer than 100 characters', async () => {
   const longReason = 'x'.repeat(101);
-  const body = await response(['260101T0003', 'ret', longReason]);
+  const body = await response(['260101T0003-ret', longReason]);
   const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('reason'));
   assert.ok(!logged.some(line => line.includes('request for a retest awaits approval')));
@@ -120,7 +120,7 @@ test('requestRetest rejects a report matching a claimed job by description', asy
     target: {what: 'Retest Fixture Page', url: 'https://example.com/unrelated'}
   }));
   try {
-    const body = await response(['260101T0003', 'ret', 'A reason that is long enough.']);
+    const body = await response(['260101T0003-ret', 'A reason that is long enough.']);
     const details = body['response content']['details about your request'] as any;
     assert.equal(details.error, undefined);
     const disposition = body['response content']['disposition of your request'] as any;
@@ -141,7 +141,7 @@ test('requestRetest rejects a report matching a queued job by URL', async () =>
     target: {what: 'Some Other Page', url: 'https://example.com/retestfixture'}
   }));
   try {
-    const body = await response(['260101T0003', 'ret', 'A reason that is long enough.']);
+    const body = await response(['260101T0003-ret', 'A reason that is long enough.']);
     const details = body['response content']['details about your request'] as any;
     assert.equal(details.error, undefined);
     const disposition = body['response content']['disposition of your request'] as any;
@@ -156,8 +156,8 @@ test('requestRetest rejects a report matching a queued job by URL', async () =>
 });
 
 test('requestRetest rejects a duplicate request', async () => {
-  await response(['260101T0003', 'ret', 'A reason that is long enough.']);
-  const body = await response(['260101T0003', 'ret', 'A reason that is long enough.']);
+  await response(['260101T0003-ret', 'A reason that is long enough.']);
+  const body = await response(['260101T0003-ret', 'A reason that is long enough.']);
   const details = body['response content']['details about your request'] as any;
   assert.equal(details.error, undefined);
   const disposition = body['response content']['disposition of your request'] as any;
@@ -165,7 +165,7 @@ test('requestRetest rejects a duplicate request', async () => {
 });
 
 test('requestRetest accepts a valid retest request for the latest report of a page', async () => {
-  const body = await response(['260202T0000', 'new', 'A reason that is long enough.']);
+  const body = await response(['260202T0000-new', 'A reason that is long enough.']);
   const details = body['response content']['details about your request'] as any;
   assert.equal(details.error, undefined);
   assert.equal(details['page to be retested'].description, 'Mixed Outcomes');
@@ -185,7 +185,7 @@ test('requestRetest rejects a request with a fallback channel when the queue is
     timeStamp: '260101T0000', description: `Filler Page ${i}`, reason: 'Filler reason.'
   }));
   await fs.writeFile(testRequestsPath, JSON.stringify({'https://example.com/filler': filler}));
-  const body = await response(['260101T0003', 'ret', 'A reason that is long enough.']);
+  const body = await response(['260101T0003-ret', 'A reason that is long enough.']);
   const details = body['response content']['details about your request'] as any;
   assert.equal(details.error, undefined);
   const disposition = body['response content']['disposition of your request'] as any;