@jrpool/kilotest 52.0.0 → 57.0.1

package/util.test.ts

@@ -21,17 +21,20 @@ for (const key of ['MANAGER_EMAIL', 'ALERT_API_HOST', 'ALERT_API_PATH', 'ALERT_A
 
 import {
   annotateReportObject,
+  awaitJob,
   checkCommentDuplicate,
   checkCommentLength,
   checkLength,
   createLock,
   dbPath,
+  describeMax,
   getAgoDays,
   getAgoString,
   getCountString,
   getDateString,
   getDateTime,
   getEngineNamesString,
+  getEnvMax,
   getIssue,
   errorMessage,
   getJSON,
@@ -52,6 +55,7 @@ import {
   getWeightName,
   hiddenReportsPath,
   htmlSafe,
+  isAllowedRedirectTarget,
   isAllowedReport,
   isAllowedTarget,
   isJobID,
@@ -63,6 +67,7 @@ import {
   makeBreakable,
   minifyURL,
   objectSort,
+  orderJob,
   processTestRequest,
   testRequestsLock,
   testRequestsPath,
@@ -268,6 +273,46 @@ test('getDateTime returns null for an invalid time stamp', () => {
   assert.equal(getDateTime('invalid'), null);
 });
 
+test('getEnvMax returns the default when the variable is unset', () => {
+  delete process.env.TEST_ENV_MAX_VAR;
+  assert.equal(getEnvMax('TEST_ENV_MAX_VAR', 20), 20);
+});
+
+test('getEnvMax returns the default when the variable is empty', () => {
+  process.env.TEST_ENV_MAX_VAR = '';
+  assert.equal(getEnvMax('TEST_ENV_MAX_VAR', 20), 20);
+  delete process.env.TEST_ENV_MAX_VAR;
+});
+
+test('getEnvMax returns the configured value when it is a positive integer', () => {
+  process.env.TEST_ENV_MAX_VAR = '50';
+  assert.equal(getEnvMax('TEST_ENV_MAX_VAR', 20), 50);
+  delete process.env.TEST_ENV_MAX_VAR;
+});
+
+test('getEnvMax returns the default when the variable is not an integer', () => {
+  process.env.TEST_ENV_MAX_VAR = 'not-a-number';
+  assert.equal(getEnvMax('TEST_ENV_MAX_VAR', 20), 20);
+  delete process.env.TEST_ENV_MAX_VAR;
+});
+
+test('getEnvMax returns 0 when the variable is explicitly 0, meaning no limit', () => {
+  process.env.TEST_ENV_MAX_VAR = '0';
+  assert.equal(getEnvMax('TEST_ENV_MAX_VAR', 20), 0);
+  delete process.env.TEST_ENV_MAX_VAR;
+});
+
+test('getEnvMax returns the default when the variable is negative', () => {
+  process.env.TEST_ENV_MAX_VAR = '-5';
+  assert.equal(getEnvMax('TEST_ENV_MAX_VAR', 20), 20);
+  delete process.env.TEST_ENV_MAX_VAR;
+});
+
+test('describeMax returns "no limit" for a cap of 0 and the number otherwise', () => {
+  assert.equal(describeMax(0), 'no limit');
+  assert.equal(describeMax(20), '20');
+});
+
 test('getIssue returns an issue ID for a known engine and rule', () => {
   const issueID = getIssue('axe', 'link-name');
   assert.ok(typeof issueID === 'string' || issueID === null);
@@ -451,6 +496,66 @@ test('isAllowedTarget returns true for a URL resolving to a public IPv6 address'
   assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('2606:2800:220:1:248:1893:25c8:1946')), true);
 });
 
+test('isAllowedTarget returns false for a URL resolving to a TEST-NET-1 address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('192.0.2.1')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to a TEST-NET-2 address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('198.51.100.1')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to a TEST-NET-3 address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('203.0.113.1')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to a benchmarking (198.18/15) address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('198.18.0.1')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to a reserved 240/4 address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('240.0.0.1')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to the broadcast address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('255.255.255.255')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to a multicast address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('224.0.0.1')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to a deprecated IPv6 site-local address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('fec0::1')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to an IPv6 multicast address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('ff02::1')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to a 6to4 (2002::/16) address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('2002::1')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to a Teredo (2001::/32) address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('2001::1')), false);
+});
+
+test('isAllowedTarget returns false for a URL resolving to an NAT64 (64:ff9b::/96) address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(await isAllowedTarget('https://example.com/page', fakeLookup('64:ff9b::10.0.0.5')), false);
+});
+
 test('isAllowedTarget returns false for a URL resolving to an address family net.isIP does not recognize', async () => {
   delete process.env.ALLOW_INTERNAL_TARGETS;
   assert.equal(await isAllowedTarget('https://example.com/page', async () => [{address: 'not-an-ip', family: 0}]), false);
@@ -482,6 +587,118 @@ test('isAllowedTarget returns true for a private-address target when ALLOW_INTER
   assert.equal(await isAllowedTarget('https://192.168.1.1/page'), true);
 });
 
+// A fake fetch that returns a response whose url reflects any redirect,
+// so isAllowedRedirectTarget tests need no real network access.
+const fakeFetch = (finalURL: string) => async () => ({url: finalURL}) as Response;
+
+test('isAllowedRedirectTarget returns true when the final URL resolves to a public address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(
+    await isAllowedRedirectTarget('https://example.com/page', fakeFetch('https://example.com/page'), fakeLookup('93.184.216.34')),
+    true
+  );
+});
+
+test('isAllowedRedirectTarget returns false when a redirect leads to a private address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(
+    await isAllowedRedirectTarget('https://example.com/page', fakeFetch('https://10.0.0.5/page'), fakeLookup('93.184.216.34')),
+    false
+  );
+});
+
+test('isAllowedRedirectTarget returns false when the fetch throws', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  const fetchImpl = async () => { throw new Error('fetch failed'); };
+  assert.equal(await isAllowedRedirectTarget('https://example.com/page', fetchImpl), false);
+});
+
+test('isAllowedRedirectTarget returns true for any URL when ALLOW_INTERNAL_TARGETS is true, without fetching', async () => {
+  process.env.ALLOW_INTERNAL_TARGETS = 'true';
+  const fetchImpl = async () => { throw new Error('fetch should not be called'); };
+  assert.equal(await isAllowedRedirectTarget('https://192.168.1.1/page', fetchImpl), true);
+});
+
+test('isAllowedRedirectTarget returns false when a redirect leads to a TEST-NET-1 address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(
+    await isAllowedRedirectTarget('https://example.com/page', fakeFetch('https://192.0.2.1/page'), fakeLookup('93.184.216.34')),
+    false
+  );
+});
+
+test('isAllowedRedirectTarget returns false when a redirect leads to a TEST-NET-2 address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(
+    await isAllowedRedirectTarget('https://example.com/page', fakeFetch('https://198.51.100.1/page'), fakeLookup('93.184.216.34')),
+    false
+  );
+});
+
+test('isAllowedRedirectTarget returns false when a redirect leads to a TEST-NET-3 address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(
+    await isAllowedRedirectTarget('https://example.com/page', fakeFetch('https://203.0.113.1/page'), fakeLookup('93.184.216.34')),
+    false
+  );
+});
+
+test('isAllowedRedirectTarget returns false when a redirect leads to a benchmarking (198.18/15) address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(
+    await isAllowedRedirectTarget('https://example.com/page', fakeFetch('https://198.18.0.1/page'), fakeLookup('93.184.216.34')),
+    false
+  );
+});
+
+test('isAllowedRedirectTarget returns false when a redirect leads to a reserved 240/4 address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(
+    await isAllowedRedirectTarget('https://example.com/page', fakeFetch('https://240.0.0.1/page'), fakeLookup('93.184.216.34')),
+    false
+  );
+});
+
+test('isAllowedRedirectTarget returns false when a redirect leads to the broadcast address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(
+    await isAllowedRedirectTarget('https://example.com/page', fakeFetch('https://255.255.255.255/page'), fakeLookup('93.184.216.34')),
+    false
+  );
+});
+
+test('isAllowedRedirectTarget returns false when a redirect leads to a multicast address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(
+    await isAllowedRedirectTarget('https://example.com/page', fakeFetch('https://224.0.0.1/page'), fakeLookup('93.184.216.34')),
+    false
+  );
+});
+
+test('isAllowedRedirectTarget returns false when a redirect leads to a deprecated IPv6 site-local address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(
+    await isAllowedRedirectTarget('https://example.com/page', fakeFetch('https://[fec0::1]/page'), fakeLookup('93.184.216.34')),
+    false
+  );
+});
+
+test('isAllowedRedirectTarget returns false when a redirect leads to a 6to4 (2002::/16) address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(
+    await isAllowedRedirectTarget('https://example.com/page', fakeFetch('https://[2002::1]/page'), fakeLookup('93.184.216.34')),
+    false
+  );
+});
+
+test('isAllowedRedirectTarget returns false when a redirect leads to a Teredo (2001::/32) address', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  assert.equal(
+    await isAllowedRedirectTarget('https://example.com/page', fakeFetch('https://[2001::1]/page'), fakeLookup('93.184.216.34')),
+    false
+  );
+});
+
 test('isAllowedReport returns true when every act has a public actualURL', async () => {
   delete process.env.ALLOW_INTERNAL_TARGETS;
   const report = {
@@ -673,12 +890,69 @@ test('processTestRequest returns a duplicate error for a repeated request', {tim
   await fs.writeFile(testRequestsPath(), '{}\n');
 });
 
-test('processTestRequest returns a retest error when a report already exists for the page', async () => {
+test('processTestRequest returns a reportExists error when a report already exists for the page', async () => {
   // The fixture database already has a report for this description and URL.
   const {result} = await processTestRequest(
     'because accessibility', {description: 'Mixed Outcomes Page', url: 'https://example.com/mixed'}
   );
-  assert.equal(result, 'retest');
+  assert.equal(result, 'reportExists');
+});
+
+test('processTestRequest returns a queueFull error once the pending-request queue is full', {timeout: 500}, async () => {
+  // Fill testRequests.json with 20 pending requests, all for the same URL, so the total
+  // pending count (summed across all URLs' request arrays) reaches the cap directly,
+  // without needing 20 distinct URLs.
+  const filler = Array.from({length: 20}, (_, i) => ({
+    timeStamp: getNowStamp(), description: `Filler Page ${i}`, reason: 'because filler'
+  }));
+  await fs.writeFile(testRequestsPath(), getJSON({'https://example.com/filler': filler}));
+  // A further, distinct request is rejected as queueFull.
+  const {result} = await processTestRequest(
+    'because accessibility', {description: 'One Too Many Page', url: 'https://example.com/one-too-many'}
+  );
+  assert.equal(result, 'queueFull');
+  // Clean up testRequests.json.
+  await fs.writeFile(testRequestsPath(), '{}\n');
+});
+
+test('processTestRequest honors TEST_REQUEST_QUEUE_MAX when the cap is reached below the default', {timeout: 500}, async () => {
+  // With the cap lowered to 2, a single pending request already fills the queue.
+  process.env.TEST_REQUEST_QUEUE_MAX = '2';
+  try {
+    await fs.writeFile(testRequestsPath(), getJSON({
+      'https://example.com/filler': [
+        {timeStamp: getNowStamp(), description: 'Filler Page A', reason: 'because filler'},
+        {timeStamp: getNowStamp(), description: 'Filler Page B', reason: 'because filler'}
+      ]
+    }));
+    const {result} = await processTestRequest(
+      'because accessibility', {description: 'One Too Many Page', url: 'https://example.com/one-too-many'}
+    );
+    assert.equal(result, 'queueFull');
+  }
+  finally {
+    delete process.env.TEST_REQUEST_QUEUE_MAX;
+    await fs.writeFile(testRequestsPath(), '{}\n');
+  }
+});
+
+test('processTestRequest never returns queueFull when TEST_REQUEST_QUEUE_MAX is 0 (no limit)', {timeout: 500}, async () => {
+  // With the cap set to 0, a queue already past the default size is still not full.
+  process.env.TEST_REQUEST_QUEUE_MAX = '0';
+  try {
+    const filler = Array.from({length: 25}, (_, i) => ({
+      timeStamp: getNowStamp(), description: `Filler Page ${i}`, reason: 'because filler'
+    }));
+    await fs.writeFile(testRequestsPath(), getJSON({'https://example.com/filler': filler}));
+    const {result} = await processTestRequest(
+      'because accessibility', {description: 'One More Page', url: 'https://example.com/one-more'}
+    );
+    assert.equal(result, 'ok');
+  }
+  finally {
+    delete process.env.TEST_REQUEST_QUEUE_MAX;
+    await fs.writeFile(testRequestsPath(), '{}\n');
+  }
 });
 
 test('annotateReportObject annotates a report object in place without reading or writing a file', async () => {
@@ -1580,3 +1854,213 @@ test('getMetrics backfills every category, and generates a since stamp, from a b
     fsSync.rmSync(tmpDir, {recursive: true});
   }
 });
+
+// TESTS FOR orderJob AND awaitJob (GitHub issue #111)
+
+test('orderJob enqueues a new-page order directly into the job queue', async () => {
+  const {result, description, url, jobID} = await orderJob(
+    {description: 'Ordered Page', url: 'https://example.com/ordered'}, 'because accessibility matters here'
+  ) as any;
+  assert.equal(result, 'ok');
+  assert.equal(description, 'Ordered Page');
+  assert.equal(url, 'https://example.com/ordered');
+  assert.match(jobID, /^\d{6}T\d{4}-[a-z0-9]{3}$/);
+  const queuedPath = path.join(jobsPath(), 'queue', `${jobID}.json`);
+  try {
+    const job = JSON.parse(await fs.readFile(queuedPath, 'utf8'));
+    assert.equal(job.target.what, 'Ordered Page');
+    assert.equal(job.target.url, 'https://example.com/ordered');
+    assert.equal(job.sources.reason, 'because accessibility matters here');
+    // No pending-approval inbox entry is created; the job goes straight to the queue.
+    const testRequests = JSON.parse(await fs.readFile(testRequestsPath(), 'utf8'));
+    assert.equal(testRequests['https://example.com/ordered'], undefined);
+  }
+  finally {
+    await fs.unlink(queuedPath);
+  }
+});
+
+test('orderJob returns a reportExists error when a report already exists for the ordered page', async () => {
+  const {result} = await orderJob(
+    {description: 'Mixed Outcomes Page', url: 'https://example.com/mixed'}, 'because accessibility matters here'
+  );
+  assert.equal(result, 'reportExists');
+});
+
+test('orderJob returns "description" for a page matching a claimed job by description', async () => {
+  const claimedPath = path.join(jobsPath(), 'claimed', 'clm.json');
+  await fs.writeFile(claimedPath, getJSON({
+    target: {what: 'Claimed Order Page', url: 'https://example.com/claimed-order-job'}
+  }));
+  try {
+    const {result} = await orderJob(
+      {description: 'Claimed Order Page', url: 'https://example.com/some-other-order-url'},
+      'because accessibility matters here'
+    );
+    assert.equal(result, 'description');
+  }
+  finally {
+    await fs.unlink(claimedPath);
+  }
+});
+
+test('orderJob returns "url" for a page matching a queued job by URL', async () => {
+  const queuedPath = path.join(jobsPath(), 'queue', 'que.json');
+  await fs.writeFile(queuedPath, getJSON({
+    target: {what: 'Some Queued Order Page', url: 'https://example.com/queued-order-url'}
+  }));
+  try {
+    const {result} = await orderJob(
+      {description: 'A Different Order Page', url: 'https://example.com/queued-order-url'},
+      'because accessibility matters here'
+    );
+    assert.equal(result, 'url');
+  }
+  finally {
+    await fs.unlink(queuedPath);
+  }
+});
+
+test('orderJob throws when a job file in a category directory is defective', async () => {
+  const claimedPath = path.join(jobsPath(), 'claimed', 'bad.json');
+  await fs.writeFile(claimedPath, 'not valid json');
+  try {
+    await assert.rejects(
+      orderJob({description: 'Any Order Page', url: 'https://example.com/any-order'}, 'because accessibility matters here'),
+      /Failed to order test/
+    );
+  }
+  finally {
+    await fs.unlink(claimedPath);
+  }
+});
+
+test('orderJob returns "nonreport" when a retest order cites a report that does not exist', async () => {
+  const {result} = await orderJob({timeStamp: '999999T9999', jobID: 'xxx'}, 'because accessibility matters here');
+  assert.equal(result, 'nonreport');
+});
+
+test('orderJob returns "superseded" when a retest order cites a superseded report', async () => {
+  // 260101T0000-mix is an earlier report of "Mixed Outcomes Page" than 260202T0000-new,
+  // so it is superseded.
+  const {result} = await orderJob(
+    {timeStamp: '260101T0000', jobID: 'mix'}, 'because accessibility matters here'
+  );
+  assert.equal(result, 'superseded');
+});
+
+test('orderJob enqueues a retest order for the latest report of a page', async () => {
+  const {result, description, url, jobID} = await orderJob(
+    {timeStamp: '260202T0000', jobID: 'new'}, 'because accessibility matters here'
+  ) as any;
+  assert.equal(result, 'ok');
+  assert.equal(description, 'Mixed Outcomes Page');
+  assert.equal(url, 'https://example.com/mixed');
+  const queuedPath = path.join(jobsPath(), 'queue', `${jobID}.json`);
+  try {
+    const job = JSON.parse(await fs.readFile(queuedPath, 'utf8'));
+    assert.equal(job.target.what, 'Mixed Outcomes Page');
+  }
+  finally {
+    await fs.unlink(queuedPath);
+  }
+});
+
+test('orderJob honors JOB_QUEUE_MAX when the cap is reached', async () => {
+  process.env.JOB_QUEUE_MAX = '1';
+  const fillerPath = path.join(jobsPath(), 'queue', 'fil.json');
+  await fs.writeFile(fillerPath, getJSON({target: {what: 'Filler Queued Page', url: 'https://example.com/filler-queued'}}));
+  try {
+    const {result} = await orderJob(
+      {description: 'One Too Many Order Page', url: 'https://example.com/one-too-many-order'},
+      'because accessibility matters here'
+    );
+    assert.equal(result, 'queueFull');
+  }
+  finally {
+    delete process.env.JOB_QUEUE_MAX;
+    await fs.unlink(fillerPath);
+  }
+});
+
+test('orderJob never returns queueFull when JOB_QUEUE_MAX is 0 (no limit)', async () => {
+  process.env.JOB_QUEUE_MAX = '0';
+  const fillerPath = path.join(jobsPath(), 'queue', 'fi2.json');
+  await fs.writeFile(fillerPath, getJSON({target: {what: 'Filler Queued Page Two', url: 'https://example.com/filler-queued-2'}}));
+  try {
+    const {result, jobID} = await orderJob(
+      {description: 'One More Order Page', url: 'https://example.com/one-more-order'},
+      'because accessibility matters here'
+    ) as any;
+    assert.equal(result, 'ok');
+    await fs.unlink(path.join(jobsPath(), 'queue', `${jobID}.json`));
+  }
+  finally {
+    delete process.env.JOB_QUEUE_MAX;
+    await fs.unlink(fillerPath);
+  }
+});
+
+test('awaitJob returns "completed" immediately when a report already exists', async () => {
+  const outcome = await awaitJob('260101T0000', 'mix');
+  assert.equal(outcome, 'completed');
+});
+
+test('awaitJob returns "notFound" for an identifier naming neither a report nor a pending job', async () => {
+  const outcome = await awaitJob('999999T9999', 'xxx');
+  assert.equal(outcome, 'notFound');
+});
+
+test('awaitJob returns "failed" when the job has moved to the failed directory', async () => {
+  const failedPath = path.join(jobsPath(), 'failed', '260101T1111-flj.json');
+  await fs.mkdir(path.dirname(failedPath), {recursive: true});
+  await fs.writeFile(failedPath, getJSON({target: {what: 'Failed Await Page', url: 'https://example.com/failed-await'}}));
+  try {
+    const outcome = await awaitJob('260101T1111', 'flj');
+    assert.equal(outcome, 'failed');
+  }
+  finally {
+    await fs.unlink(failedPath);
+  }
+});
+
+test('awaitJob polls until a queued job completes, then returns "completed"', async () => {
+  process.env.AWAIT_JOB_POLL_MS = '20';
+  process.env.AWAIT_JOB_TIMEOUT_MS = '2000';
+  const jobName = '260101T2222-plj';
+  const queuedPath = path.join(jobsPath(), 'queue', `${jobName}.json`);
+  const reportPath = path.join(reportsPath(), `${jobName}.json`);
+  await fs.writeFile(queuedPath, getJSON({target: {what: 'Polled Page', url: 'https://example.com/polled'}}));
+  // Simulate the job completing shortly after the wait begins.
+  setTimeout(async () => {
+    await fs.unlink(queuedPath).catch(() => {});
+    await fs.writeFile(reportPath, getJSON({id: jobName, target: {what: 'Polled Page', url: 'https://example.com/polled'}}));
+  }, 50);
+  try {
+    const outcome = await awaitJob('260101T2222', 'plj');
+    assert.equal(outcome, 'completed');
+  }
+  finally {
+    delete process.env.AWAIT_JOB_POLL_MS;
+    delete process.env.AWAIT_JOB_TIMEOUT_MS;
+    await fs.unlink(queuedPath).catch(() => {});
+    await fs.unlink(reportPath).catch(() => {});
+  }
+});
+
+test('awaitJob returns "timedOut" when a claimed job neither completes nor fails before the deadline', async () => {
+  process.env.AWAIT_JOB_POLL_MS = '10';
+  process.env.AWAIT_JOB_TIMEOUT_MS = '50';
+  const jobName = '260101T3333-toj';
+  const claimedPath = path.join(jobsPath(), 'claimed', `${jobName}.json`);
+  await fs.writeFile(claimedPath, getJSON({target: {what: 'Stuck Page', url: 'https://example.com/stuck'}}));
+  try {
+    const outcome = await awaitJob('260101T3333', 'toj');
+    assert.equal(outcome, 'timedOut');
+  }
+  finally {
+    delete process.env.AWAIT_JOB_POLL_MS;
+    delete process.env.AWAIT_JOB_TIMEOUT_MS;
+    await fs.unlink(claimedPath);
+  }
+});