@jrpool/kilotest 55.0.0 → 57.0.1

package/README.md

@@ -40,7 +40,7 @@ In the steps below, hosts `T` and `K` may be the same host or two different host
 
 ### Usage
 
-1. In the `testaro` directory, make Testaro start listening for jobs: `node call netWatch true nn true`, where `nn` is the number of seconds to wait between checks for new jobs.
+1. In the `testaro` directory, make Testaro start listening for jobs: `node call netWatch true nn true`, where `nn` is the number of seconds to wait between checks for new jobs. Note that Kilotest promises nearly immediate review and, on approval, immediate execution of “orders” for tests and retests, with typical total elapsed time about 2 minutes. That promise implies a promise to keep `nn` small. A reasonable value is between 10 and 20.
 1. In the `kilotest` directory, start the Kilotest service: `node index`.
 
 ### Contributing

package/api/awaitTest.test.ts

@@ -0,0 +1,114 @@
+/*
+  awaitTest.test.ts
+  Tests for api/awaitTest.ts using the fixture corpus.
+*/
+
+// IMPORTS
+
+import {test, before, after} from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {fixtureDBDir} from '../test/dbFixture.ts';
+
+for (const key of ['MANAGER_EMAIL', 'ALERT_API_HOST', 'ALERT_API_PATH', 'ALERT_API_KEY', 'ALERT_FROM']) {
+  process.env[key] = '';
+}
+// Keep the poll fast in this file, since these tests do not exercise timing edge cases
+// (those live in util.test.ts, closer to awaitJob itself); a short interval just keeps
+// this file's own tests quick.
+process.env.AWAIT_JOB_POLL_MS = '10';
+process.env.AWAIT_JOB_TIMEOUT_MS = '50';
+
+// SETUP AND TEARDOWN
+
+const savedDBDir = process.env.DB_DIR;
+
+before(() => {
+  process.env.DB_DIR = fixtureDBDir;
+});
+
+import {response} from './awaitTest.ts';
+
+after(() => {
+  delete process.env.AWAIT_JOB_POLL_MS;
+  delete process.env.AWAIT_JOB_TIMEOUT_MS;
+  if (savedDBDir !== undefined) {
+    process.env.DB_DIR = savedDBDir;
+  }
+  else {
+    delete process.env.DB_DIR;
+  }
+});
+
+// TESTS
+
+test('awaitTest rejects a malformed timestamp or job identifier', async () => {
+  const body = await response(['999999T9999', 'xyz']);
+  const details = body['response content']['details about your wait'] as any;
+  assert.ok(details.error.includes('malformed'));
+  assert.equal(body['response content']['disposition of your wait'], null);
+});
+
+test('awaitTest returns "completed" for an identifier with an already-available report', async () => {
+  const body = await response(['260101T0000', 'mix']);
+  const details = body['response content']['details about your wait'] as any;
+  assert.deepEqual(details['report identifier'], {timeStamp: '260101T0000', jobID: 'mix'});
+  const disposition = body['response content']['disposition of your wait'] as any;
+  assert.equal(disposition.outcome, 'completed');
+  assert.ok(disposition['how you can check for completion'].includes('listIssues'));
+});
+
+test('awaitTest returns an error for an identifier naming neither a report nor a pending job', async () => {
+  const body = await response(['260101T0000', 'zzz']);
+  const details = body['response content']['details about your wait'] as any;
+  assert.ok(details.error.includes('no report'));
+  assert.equal(body['response content']['disposition of your wait'], null);
+});
+
+test('awaitTest returns "failed" when the job has moved to the failed directory', async () => {
+  const failedPath = path.join(fixtureDBDir, 'jobs', 'failed', '260101T4444-flj.json');
+  await fs.mkdir(path.dirname(failedPath), {recursive: true});
+  await fs.writeFile(failedPath, JSON.stringify({target: {what: 'Failed Page', url: 'https://example.com/failed'}}));
+  try {
+    const body = await response(['260101T4444', 'flj']);
+    const disposition = body['response content']['disposition of your wait'] as any;
+    assert.equal(disposition.outcome, 'failed');
+    assert.equal(disposition['how you can check for completion'], 'Not applicable.');
+  }
+  finally {
+    await fs.unlink(failedPath);
+  }
+});
+
+test('awaitTest returns "timedOut" when a claimed job neither completes nor fails before the deadline', async () => {
+  const claimedPath = path.join(fixtureDBDir, 'jobs', 'claimed', '260101T5555-toj.json');
+  await fs.writeFile(claimedPath, JSON.stringify({target: {what: 'Stuck Page', url: 'https://example.com/stuck'}}));
+  try {
+    const body = await response(['260101T5555', 'toj']);
+    const disposition = body['response content']['disposition of your wait'] as any;
+    assert.equal(disposition.outcome, 'timedOut');
+    assert.ok(disposition['how you can check for completion'].includes('listIssues'));
+  }
+  finally {
+    await fs.unlink(claimedPath);
+  }
+});
+
+test('awaitTest response has no web UI equivalents for this request or its ancestors', async () => {
+  const body = await response(['260101T0000', 'mix']);
+  const similarWeb = body['URLs of similar requests for web users'] as any;
+  assert.equal(similarWeb['this request'], null);
+  assert.equal(similarWeb['closest ancestor request'], null);
+});
+
+test('awaitTest reports both orderNewTest and orderRetest as possible ancestors', async () => {
+  const body = await response(['260101T0000', 'mix']);
+  const ancestors = (body['this request'] as any)['closest ancestor request'];
+  assert.equal(ancestors.length, 2);
+  const names = ancestors.map((a: any) => a['tool name']).sort();
+  assert.deepEqual(names, ['orderNewTest', 'orderRetest']);
+  for (const ancestor of ancestors) {
+    assert.equal(ancestor.method, 'POST');
+  }
+});

package/api/awaitTest.ts

@@ -0,0 +1,108 @@
+/*
+  awaitTest.ts
+  Waits for a job ordered via orderNewTest or orderRetest to complete, and returns its outcome.
+*/
+
+// IMPORTS
+
+import {z} from 'zod';
+import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
+import {awaitJob, isJobID, isTimeStamp} from '../util.ts';
+import {awaitTestResponseSchema} from './schemas.ts';
+
+// TYPES
+
+// The response content defined by the response schema.
+type ResponseContent = z.infer<typeof awaitTestResponseSchema>['response content'];
+
+// FUNCTIONS
+
+// Returns the response body.
+export const response = async (args: string[]) => {
+  const [timeStamp = '', jobID = ''] = args;
+  const thisHost = getThisHost();
+  // Initialize the response-content properties.
+  let requestDetails: ResponseContent['details about your wait'];
+  let requestDisposition: ResponseContent['disposition of your wait'] = null;
+  // If the timestamp or job ID is not syntactically valid:
+  if (!isTimeStamp(timeStamp) || !isJobID(jobID)) {
+    requestDetails = {
+      error: 'wait invalid: the report timeStamp or jobID is malformed'
+    };
+  }
+  // Otherwise, i.e. if the identifier is syntactically valid:
+  else {
+    requestDetails = {
+      'report identifier': {timeStamp, jobID}
+    };
+    // Wait for the job to complete, fail, or time out. No progress notices are sent
+    // during this wait; the caller receives only this one, final response.
+    const outcome = await awaitJob(timeStamp, jobID);
+    if (outcome === 'notFound') {
+      requestDetails = {
+        error: `wait invalid: no report with timeStamp "${timeStamp}" and jobID "${jobID}" is completed, pending, or in progress`
+      };
+    }
+    else if (outcome === 'completed') {
+      requestDisposition = {
+        outcome: 'completed',
+        'what happened': 'The report is ready.',
+        'how you can check for completion': `Call the listIssues tool with timeStamp "${timeStamp}" and jobID "${jobID}" to retrieve the report.`
+      };
+    }
+    else if (outcome === 'failed') {
+      requestDisposition = {
+        outcome: 'failed',
+        'what happened': 'The job failed, so no report will be produced.',
+        'how you can check for completion': 'Not applicable.'
+      };
+    }
+    else {
+      requestDisposition = {
+        outcome: 'timedOut',
+        'what happened': 'The job was not completed within the maximum wait time, but it may still be running.',
+        'how you can check for completion': `Call the listIssues tool with timeStamp "${timeStamp}" and jobID "${jobID}" after a few minutes to check whether the report is ready.`
+      };
+    }
+  }
+  // Create the response content.
+  const responseContent: ResponseContent = {
+    'details about your wait': requestDetails,
+    'disposition of your wait': requestDisposition
+  };
+  // Create a response body.
+  const body = {
+    'tool collection': getToolsFacts(),
+    'tool name': 'awaitTest',
+    'this request': {
+      description: 'Wait for a job ordered via the orderNewTest or orderRetest tool to complete. The timeStamp and jobID parameters are the report identifier that orderNewTest or orderRetest returned. This call blocks until the report is ready, the job fails, or a maximum wait time elapses.',
+      method: 'POST',
+      URL: `${thisHost}/api/awaitTest/${timeStamp}/${jobID}`,
+      // awaitTest's own parameters do not say whether the job was ordered via orderNewTest
+      // or orderRetest, so both are reported as possible ancestors, rather than
+      // arbitrarily naming just one.
+      'closest ancestor request': [
+        {
+          'tool name': 'orderNewTest',
+          description: 'Fulfill or reject my order to test a page about which no report is available yet.',
+          method: 'POST',
+          URL: `${thisHost}/api/orderNewTest`
+        },
+        {
+          'tool name': 'orderRetest',
+          description: 'Fulfill or reject my order to retest a page.',
+          method: 'POST',
+          URL: `${thisHost}/api/orderRetest`
+        }
+      ]
+    },
+    'URLs of similar requests for web users': {
+      'this request': null,
+      'closest ancestor request': null
+    },
+    'response metadata': getResponseMetadata(),
+    'response content': responseContent
+  };
+  // Return it.
+  return body;
+};

package/api/listReports.ts

@@ -53,7 +53,7 @@ export const response = async () => {
     'basics about all available reports': reportsBasics,
     'how to request that a page with no report be tested': {
       method: 'POST',
-      URL: `${thisHost}/api/requestTest`,
+      URL: `${thisHost}/api/requestNewTest`,
       'request body': {
         description: '10- to 100-character description of the page conforming to the naming convention used in this list of reports',
         URL: '12- to 300-character URL of the page, including the https:// scheme and any query',
@@ -62,7 +62,7 @@ export const response = async () => {
       'how to check whether the request has been fulfilled': 'use this listReports tool to determine whether a report about the page has become available (typical wait time: 1 hour to 1 day)'
     },
     'how a web user can request that the page be tested': {
-      URL: `${thisHost}/requestTestForm.html`
+      URL: `${thisHost}/requestNewTestForm.html`
     }
   };
   // Create a response body.

package/api/orderNewTest.test.ts

@@ -0,0 +1,213 @@
+/*
+  orderNewTest.test.ts
+  Tests for api/orderNewTest.ts using the fixture corpus.
+*/
+
+// IMPORTS
+
+import {test, before, beforeEach, after} from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {fixtureDBDir} from '../test/dbFixture.ts';
+
+// Blank the alert configuration unconditionally, before ./orderNewTest.ts (whose orderJob
+// calls no alert directly, but whose redirect-rejection branch does) is ever imported
+// below, so this file sends no real alert emails even when run directly rather than via
+// `npm test`.
+for (const key of ['MANAGER_EMAIL', 'ALERT_API_HOST', 'ALERT_API_PATH', 'ALERT_API_KEY', 'ALERT_FROM']) {
+  process.env[key] = '';
+}
+// Allow internal targets by default, so tests that submit an ordinary https://example.com/...
+// URL do not depend on real DNS/network access to pass the resolution check that
+// isAllowedTarget performs.
+process.env.ALLOW_INTERNAL_TARGETS = 'true';
+
+// SETUP AND TEARDOWN
+
+const savedDBDir = process.env.DB_DIR;
+const queuePath = path.join(fixtureDBDir, 'jobs', 'queue');
+let logged: any[] = [];
+const originalLog = console.log;
+
+before(() => {
+  process.env.DB_DIR = fixtureDBDir;
+});
+
+// Empty the job queue and capture console.log before each test, so tests are
+// order-independent and any queued jobs a test creates do not leak into later tests.
+beforeEach(async () => {
+  for (const fileName of await fs.readdir(queuePath)) {
+    await fs.unlink(path.join(queuePath, fileName));
+  }
+  logged = [];
+  console.log = (...args) => logged.push(args.join(' '));
+});
+
+import {response} from './orderNewTest.ts';
+
+after(() => {
+  console.log = originalLog;
+  if (savedDBDir !== undefined) {
+    process.env.DB_DIR = savedDBDir;
+  }
+  else {
+    delete process.env.DB_DIR;
+  }
+});
+
+// TESTS
+
+test('orderNewTest rejects an empty description', async () => {
+  const body = await response(['', 'https://example.com/test', 'A reason that is long enough.']);
+  assert.ok((body['response content']['details about your order'] as any).error);
+});
+
+test('orderNewTest rejects a reason shorter than 20 characters', async () => {
+  const body = await response(['Ordered Page', 'https://example.com/ordered', 'short']);
+  const details = body['response content']['details about your order'] as any;
+  assert.ok(details.error.includes('reason'));
+});
+
+test('orderNewTest rejects a reason longer than 100 characters', async () => {
+  const longReason = 'x'.repeat(101);
+  const body = await response(['Ordered Page', 'https://example.com/ordered', longReason]);
+  const details = body['response content']['details about your order'] as any;
+  assert.ok(details.error.includes('reason'));
+});
+
+test('orderNewTest rejects a URL shorter than 12 characters', async () => {
+  const body = await response(['Test Page', 'short', 'A reason that is long enough.']);
+  assert.ok((body['response content']['details about your order'] as any).error);
+});
+
+test('orderNewTest rejects a syntactically invalid URL with the correct length', async () => {
+  const body = await response(['Test Page', 'not-a-valid-url', 'A reason that is long enough.']);
+  const details = body['response content']['details about your order'] as any;
+  assert.ok(details.error.includes('invalid URL'));
+});
+
+test('orderNewTest rejects a private-address URL unless internal targets are allowed', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  try {
+    const body = await response(['Internal Page', 'https://192.168.1.1/page', 'A reason that is long enough.']);
+    const details = body['response content']['details about your order'] as any;
+    assert.ok(details.error.includes('does not resolve to a page that this deployment can test'));
+  } finally {
+    process.env.ALLOW_INTERNAL_TARGETS = 'true';
+  }
+});
+
+test('orderNewTest rejects a URL that redirects to a disallowed target, and alerts a manager', async (t) => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  t.mock.method(globalThis, 'fetch', async () => ({url: 'https://10.0.0.5/page'}) as Response);
+  try {
+    const body = await response(['Redirecting Page', 'https://example.com/redirector', 'A reason that is long enough.']);
+    const details = body['response content']['details about your order'] as any;
+    assert.ok(details.error.includes('does not resolve to a page that this deployment can test'));
+    assert.ok(logged.some(line =>
+      line.includes('WARNING (Kilotest: instant-test order rejected for redirecting to a disallowed target)')
+      && line.includes('https://example.com/redirector')
+    ));
+  } finally {
+    process.env.ALLOW_INTERNAL_TARGETS = 'true';
+  }
+});
+
+test('orderNewTest rejects an already-tested page', async () => {
+  const body = await response(['Mixed Outcomes Page', 'https://example.com/mixed', '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;
+  assert.ok(
+    disposition['what happens next']
+    .includes('a report about a page with the same description and URL is available.')
+  );
+  assert.equal(disposition['report identifier'], null);
+});
+
+test('orderNewTest rejects a page matching a claimed job by description', async () => {
+  const claimedPath = path.join(fixtureDBDir, 'jobs', 'claimed', 'clm.json');
+  await fs.writeFile(claimedPath, JSON.stringify({
+    target: {what: 'Claimed Test Page', url: 'https://example.com/claimed-job'}
+  }));
+  try {
+    const body = await response(['Claimed Test Page', 'https://example.com/other-url', '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;
+    assert.ok(
+      disposition['what happens next']
+      .includes('a request to test a page with the same description is already approved.')
+    );
+  }
+  finally {
+    await fs.unlink(claimedPath);
+  }
+});
+
+test('orderNewTest rejects a page matching a queued job by URL', async () => {
+  const queuedPath = path.join(fixtureDBDir, 'jobs', 'queue', 'que.json');
+  await fs.writeFile(queuedPath, JSON.stringify({
+    target: {what: 'Some Other Page', url: 'https://example.com/queued-url'}
+  }));
+  try {
+    const body = await response(['A Different Page', 'https://example.com/queued-url', '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;
+    assert.ok(
+      disposition['what happens next']
+      .includes('a request to test a page with the same URL is already approved.')
+    );
+  }
+  finally {
+    await fs.unlink(queuedPath);
+  }
+});
+
+test('orderNewTest rejects an order once the job queue is full', async () => {
+  process.env.JOB_QUEUE_MAX = '0';
+  const fillerPaths = await Promise.all(Array.from({length: 1}, async (_, i) => {
+    const fillerPath = path.join(fixtureDBDir, 'jobs', 'queue', `fil${i}.json`);
+    await fs.writeFile(fillerPath, JSON.stringify({target: {what: `Filler ${i}`, url: `https://example.com/filler${i}`}}));
+    return fillerPath;
+  }));
+  delete process.env.JOB_QUEUE_MAX;
+  process.env.JOB_QUEUE_MAX = '1';
+  try {
+    const body = await response(['One Too Many Page', 'https://example.com/one-too-many', '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;
+    assert.ok(disposition['what happens next'].includes('too many requests are awaiting approval right now.'));
+  } finally {
+    delete process.env.JOB_QUEUE_MAX;
+    await Promise.all(fillerPaths.map(p => fs.unlink(p)));
+  }
+});
+
+test('orderNewTest accepts a valid new page order and enqueues a job directly', async () => {
+  const body = await response(['Brand New Ordered Page', 'https://example.com/brandnewordered', '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 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.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);
+  assert.equal(queuedFiles.length, 1);
+  const job = JSON.parse(await fs.readFile(path.join(queuePath, queuedFiles[0]!), 'utf8'));
+  assert.equal(job.target.what, 'Brand New Ordered Page');
+  assert.equal(job.sources.reason, 'A reason that is long enough.');
+});
+
+test('orderNewTest response omits a web UI URL for this request but includes the ancestor', async () => {
+  const body = await response(['Brand New Ordered Page 2', 'https://example.com/brandnewordered2', '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('listReports.html'));
+});

package/api/orderNewTest.ts

@@ -0,0 +1,145 @@
+/*
+  orderNewTest.ts
+  Processes an order to test an untested page immediately, without manual approval, and returns an acknowledgement.
+*/
+
+// IMPORTS
+
+import {z} from 'zod';
+import {getRequestFailureReason, getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
+import {checkLength, isAllowedRedirectTarget, isAllowedTarget, isURL, orderJob} from '../util.ts';
+import {orderNewTestResponseSchema} from './schemas.ts';
+import {sendAlert} from '../alerts.ts';
+
+// TYPES
+
+// The response content defined by the response schema.
+type ResponseContent = z.infer<typeof orderNewTestResponseSchema>['response content'];
+
+// FUNCTIONS
+
+// Returns the response body.
+export const response = async (args: string[]) => {
+  const [description = '', url = '', reason = ''] = args;
+  const thisHost = getThisHost();
+  // Initialize the response-content properties.
+  let requestDetails: ResponseContent['details about your order'];
+  let requestDisposition: ResponseContent['disposition of your order'] = null;
+  const descriptionCheck = checkLength(description, 1, 100, 'description of the page');
+  const reasonCheck = checkLength(reason, 20, 100, 'reason');
+  // If the description is invalid:
+  if (descriptionCheck.status === 'error') {
+    requestDetails = {
+      error: `order invalid: your ${descriptionCheck.message}`
+    };
+  }
+  // Otherwise, if the reason is too short or too long:
+  else if (reasonCheck.status === 'error') {
+    requestDetails = {
+      error: `order invalid: your ${reasonCheck.message}`
+    };
+  }
+  // Otherwise, i.e. if the URL is too short or too long:
+  else if (url.length < 12 || url.length > 300) {
+    requestDetails = {
+      error: 'order invalid: you specified a URL for the page that is not between 12 and 300 characters long'
+    };
+  }
+  // Otherwise, i.e. if the URL is invalid:
+  else if (!isURL(url)) {
+    requestDetails = {
+      error: 'order invalid: you specified an invalid URL for the page'
+    };
+  }
+  // Otherwise, i.e. if the URL does not resolve to an allowed target:
+  else if (!(await isAllowedTarget(url))) {
+    requestDetails = {
+      error: 'order invalid: the URL you specified does not resolve to a page that this deployment can test'
+    };
+  }
+  // Otherwise, i.e. if the URL redirects to a target this deployment does not allow:
+  else if (!(await isAllowedRedirectTarget(url))) {
+    requestDetails = {
+      error: 'order invalid: the URL you specified does not resolve to a page that this deployment can test'
+    };
+    // Alert a manager, since a redirect to a disallowed target on an order that
+    // itself named an allowed hostname suggests an attempted or accidental SSRF,
+    // rather than an ordinary mistake by a legitimate submitter.
+    await sendAlert(
+      'Kilotest: instant-test order rejected for redirecting to a disallowed target',
+      `An order to test ${url} (described as "${description}") was rejected because it redirects to a target this deployment does not allow (e.g. a private, loopback, or link-local address).`
+    );
+  }
+  // Otherwise, i.e. if the description and URL are valid:
+  else {
+    // Order the test. Unlike processTestRequest, this enqueues the job directly, with no
+    // manual-approval step, gated only by the lightweight checks orderJob itself performs
+    // (the target is not already claimed, queued, or reported, and the job queue is not
+    // already full).
+    const orderResult = await orderJob({description, url}, reason);
+    // Add details about the order.
+    requestDetails = {
+      'date and time received': new Date().toISOString(),
+      'page to be tested': {
+        description,
+        URL: url
+      },
+      'reason why the page should be tested': reason
+    };
+    // 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 about 2 minutes and occasionally up 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.'
+      };
+    }
+    else {
+      requestDisposition = {
+        'what happens next': `Your order will not be processed, because ${getRequestFailureReason(
+          orderResult.result,
+          {result: 'reportExists', reason: 'a report about a page with the same description and URL is available.'}
+        )}`,
+        'report identifier': null,
+        'how you can check for completion': 'Not applicable.',
+        'do you want to wait for completion': 'Not applicable.'
+      };
+    }
+  }
+  // Create the response content.
+  const responseContent: ResponseContent = {
+    'details about your order': requestDetails,
+    'disposition of your order': requestDisposition
+  };
+  // Create a response body.
+  const body = {
+    'tool collection': getToolsFacts(),
+    'tool name': 'orderNewTest',
+    'this request': {
+      description: 'Process my order to test a page about which no report is available yet, immediately and without manual approval. I have provided a description and the URL of the page and a reason why it should be tested.',
+      method: 'POST',
+      URL: `${thisHost}/api/orderNewTest`,
+      body: {
+        description,
+        URL: url,
+        reason
+      },
+      'closest ancestor request': {
+        'tool name': 'listReports',
+        description: 'Provide basics about all available reports.',
+        method: 'GET',
+        URL: `${thisHost}/api/listReports`
+      }
+    },
+    'URLs of similar requests for web users': {
+      'this request': null,
+      'closest ancestor request': `${thisHost}/listReports.html`
+    },
+    'response metadata': getResponseMetadata(),
+    'response content': responseContent
+  };
+  // Return it.
+  return body;
+};