lighthouse 9.1.0-dev.20211129 → 9.1.0-dev.20211130

package/lighthouse-cli/test/smokehouse/frontends/lib.js

@@ -16,13 +16,13 @@
 import cloneDeep from 'lodash.clonedeep';
 
 import smokeTests from '../test-definitions/core-tests.js';
-import {runSmokehouse} from '../smokehouse.js';
+import {runSmokehouse, getShardedDefinitions} from '../smokehouse.js';
 
 /**
  * @param {Smokehouse.SmokehouseLibOptions} options
  */
 async function smokehouse(options) {
-  const {urlFilterRegex, skip, modify, ...smokehouseOptions} = options;
+  const {urlFilterRegex, skip, modify, shardArg, ...smokehouseOptions} = options;
 
   const clonedTests = cloneDeep(smokeTests);
   const modifiedTests = [];
@@ -41,7 +41,9 @@ async function smokehouse(options) {
     modifiedTests.push(test);
   }
 
-  return runSmokehouse(modifiedTests, smokehouseOptions);
+  const shardedTests = getShardedDefinitions(modifiedTests, shardArg);
+
+  return runSmokehouse(shardedTests, smokehouseOptions);
 }
 
 export {smokehouse};

package/lighthouse-cli/test/smokehouse/frontends/smokehouse-bin.js

@@ -13,7 +13,6 @@
 
 /* eslint-disable no-console */
 
-import {strict as assert} from 'assert';
 import path from 'path';
 import fs from 'fs';
 import url from 'url';
@@ -23,7 +22,7 @@ import yargs from 'yargs';
 import * as yargsHelpers from 'yargs/helpers';
 import log from 'lighthouse-logger';
 
-import {runSmokehouse} from '../smokehouse.js';
+import {runSmokehouse, getShardedDefinitions} from '../smokehouse.js';
 import {updateTestDefnFormat} from './back-compat-util.js';
 import {LH_ROOT} from '../../../../root.js';
 
@@ -80,52 +79,6 @@ function getDefinitionsToRun(allTestDefns, requestedIds, {invertMatch}) {
   return smokes;
 }
 
-/**
- * Parses the cli `shardArg` flag into `shardNumber/shardTotal`. Splits
- * `testDefns` into `shardTotal` shards and returns the `shardNumber`th shard.
- * Shards will differ in size by at most 1.
- * Shard params must be 1 ≤ shardNumber ≤ shardTotal.
- * @param {Array<Smokehouse.TestDfn>} testDefns
- * @param {string=} shardArg
- * @return {Array<Smokehouse.TestDfn>}
- */
-function getShardedDefinitions(testDefns, shardArg) {
-  if (!shardArg) return testDefns;
-
-  // eslint-disable-next-line max-len
-  const errorMessage = `'shard' must be of the form 'n/d' and n and d must be positive integers with 1 ≤ n ≤ d. Got '${shardArg}'`;
-  const match = /^(?<shardNumber>\d+)\/(?<shardTotal>\d+)$/.exec(shardArg);
-  assert(match && match.groups, errorMessage);
-  const shardNumber = Number(match.groups.shardNumber);
-  const shardTotal = Number(match.groups.shardTotal);
-  assert(shardNumber > 0 && Number.isInteger(shardNumber), errorMessage);
-  assert(shardTotal > 0 && Number.isInteger(shardTotal));
-  assert(shardNumber <= shardTotal, errorMessage);
-
-  // Array is sharded with `Math.ceil(length / shardTotal)` shards first
-  // and then the remaining `Math.floor(length / shardTotal) shards.
-  // e.g. `[0, 1, 2, 3]` split into 3 shards is `[[0, 1], [2], [3]]`.
-  const baseSize = Math.floor(testDefns.length / shardTotal);
-  const biggerSize = baseSize + 1;
-  const biggerShardCount = testDefns.length % shardTotal;
-
-  // Since we don't have tests for this file, construct all shards so correct
-  // structure can be asserted.
-  const shards = [];
-  let index = 0;
-  for (let i = 0; i < shardTotal; i++) {
-    const shardSize = i < biggerShardCount ? biggerSize : baseSize;
-    shards.push(testDefns.slice(index, index + shardSize));
-    index += shardSize;
-  }
-  assert.equal(shards.length, shardTotal);
-  assert.deepEqual(shards.flat(), testDefns);
-
-  const shardDefns = shards[shardNumber - 1];
-  console.log(`In this shard (${shardArg}), running: ${shardDefns.map(d => d.id).join(' ')}\n`);
-  return shardDefns;
-}
-
 /**
  * Prune the `networkRequests` from the test expectations when `takeNetworkRequestUrls`
  * is not defined. Custom servers may not have this method available in-process.

package/lighthouse-cli/test/smokehouse/smokehouse.js

@@ -32,6 +32,8 @@
  * @property {Run[]} runs
  */
 
+import {strict as assert} from 'assert';
+
 import log from 'lighthouse-logger';
 
 import {runLighthouse as cliLighthouseRunner} from './lighthouse-runners/cli.js';
@@ -227,6 +229,54 @@ function getAssertionLog(count) {
   return `${count} assertion${plural}`;
 }
 
+/**
+ * Parses the cli `shardArg` flag into `shardNumber/shardTotal`. Splits
+ * `testDefns` into `shardTotal` shards and returns the `shardNumber`th shard.
+ * Shards will differ in size by at most 1.
+ * Shard params must be 1 ≤ shardNumber ≤ shardTotal.
+ * @param {Array<Smokehouse.TestDfn>} testDefns
+ * @param {string=} shardArg
+ * @return {Array<Smokehouse.TestDfn>}
+ */
+function getShardedDefinitions(testDefns, shardArg) {
+  if (!shardArg) return testDefns;
+
+  // eslint-disable-next-line max-len
+  const errorMessage = `'shard' must be of the form 'n/d' and n and d must be positive integers with 1 ≤ n ≤ d. Got '${shardArg}'`;
+  const match = /^(?<shardNumber>\d+)\/(?<shardTotal>\d+)$/.exec(shardArg);
+  assert(match && match.groups, errorMessage);
+  const shardNumber = Number(match.groups.shardNumber);
+  const shardTotal = Number(match.groups.shardTotal);
+  assert(shardNumber > 0 && Number.isInteger(shardNumber), errorMessage);
+  assert(shardTotal > 0 && Number.isInteger(shardTotal));
+  assert(shardNumber <= shardTotal, errorMessage);
+
+  // Array is sharded with `Math.ceil(length / shardTotal)` shards first
+  // and then the remaining `Math.floor(length / shardTotal) shards.
+  // e.g. `[0, 1, 2, 3]` split into 3 shards is `[[0, 1], [2], [3]]`.
+  const baseSize = Math.floor(testDefns.length / shardTotal);
+  const biggerSize = baseSize + 1;
+  const biggerShardCount = testDefns.length % shardTotal;
+
+  // Since we don't have tests for this file, construct all shards so correct
+  // structure can be asserted.
+  const shards = [];
+  let index = 0;
+  for (let i = 0; i < shardTotal; i++) {
+    const shardSize = i < biggerShardCount ? biggerSize : baseSize;
+    shards.push(testDefns.slice(index, index + shardSize));
+    index += shardSize;
+  }
+  assert.equal(shards.length, shardTotal);
+  assert.deepEqual(shards.flat(), testDefns);
+
+  const shardDefns = shards[shardNumber - 1];
+  console.log(`In this shard (${shardArg}), running: ${shardDefns.map(d => d.id).join(' ')}\n`);
+  return shardDefns;
+}
+
+
 export {
   runSmokehouse,
+  getShardedDefinitions,
 };

package/lighthouse-core/computed/computed-artifact.js

@@ -11,20 +11,26 @@ const log = require('lighthouse-logger');
 /**
  * Decorate computableArtifact with a caching `request()` method which will
  * automatically call `computableArtifact.compute_()` under the hood.
- * @template {{name: string, compute_(artifacts: unknown, context: LH.Artifacts.ComputedContext): Promise<unknown>}} C
+ * @template {{name: string, compute_(dependencies: unknown, context: LH.Artifacts.ComputedContext): Promise<unknown>}} C
+ * @template {Array<keyof FirstParamType<C['compute_']>>} K
  * @param {C} computableArtifact
+ * @param {(K & ([keyof FirstParamType<C['compute_']>] extends [K[number]] ? unknown : never)) | null} keys List of properties of `dependencies` used by `compute_`; other properties are filtered out. Use `null` to allow all properties. Ensures that only required properties are used for caching result.
  */
-function makeComputedArtifact(computableArtifact) {
+function makeComputedArtifact(computableArtifact, keys) {
   // tsc (3.1) has more difficulty with template inter-references in jsdoc, so
   // give types to params and return value the long way, essentially recreating
   // polymorphic-this behavior for C.
   /**
    * Return an automatically cached result from the computed artifact.
-   * @param {FirstParamType<C['compute_']>} artifacts
+   * @param {FirstParamType<C['compute_']>} dependencies
    * @param {LH.Artifacts.ComputedContext} context
    * @return {ReturnType<C['compute_']>}
    */
-  const request = (artifacts, context) => {
+  const request = (dependencies, context) => {
+    const pickedDependencies = keys ?
+      Object.fromEntries(keys.map(key => [key, dependencies[key]])) :
+      dependencies;
+
     // NOTE: break immutability solely for this caching-controller function.
     const computedCache = /** @type {Map<string, ArbitraryEqualityMap>} */ (context.computedCache);
     const computedName = computableArtifact.name;
@@ -32,7 +38,8 @@ function makeComputedArtifact(computableArtifact) {
     const cache = computedCache.get(computedName) || new ArbitraryEqualityMap();
     computedCache.set(computedName, cache);
 
-    const computed = /** @type {ReturnType<C['compute_']>|undefined} */ (cache.get(artifacts));
+    /** @type {ReturnType<C['compute_']>|undefined} */
+    const computed = cache.get(pickedDependencies);
     if (computed) {
       return computed;
     }
@@ -41,8 +48,8 @@ function makeComputedArtifact(computableArtifact) {
     log.time(status, 'verbose');
 
     const artifactPromise = /** @type {ReturnType<C['compute_']>} */
-        (computableArtifact.compute_(artifacts, context));
-    cache.set(artifacts, artifactPromise);
+        (computableArtifact.compute_(pickedDependencies, context));
+    cache.set(pickedDependencies, artifactPromise);
 
     artifactPromise.then(() => log.timeEnd(status)).catch(() => log.timeEnd(status));
 

package/lighthouse-core/computed/critical-request-chains.js

@@ -143,4 +143,4 @@ class CriticalRequestChains {
   }
 }
 
-module.exports = makeComputedArtifact(CriticalRequestChains);
+module.exports = makeComputedArtifact(CriticalRequestChains, ['URL', 'devtoolsLog', 'trace']);

package/lighthouse-core/computed/image-records.js

@@ -59,5 +59,5 @@ class ImageRecords {
   }
 }
 
-module.exports = makeComputedArtifact(ImageRecords);
+module.exports = makeComputedArtifact(ImageRecords, ['ImageElements', 'networkRecords']);
 

package/lighthouse-core/computed/js-bundles.js

@@ -116,4 +116,4 @@ class JSBundles {
   }
 }
 
-module.exports = makeComputedArtifact(JSBundles);
+module.exports = makeComputedArtifact(JSBundles, ['ScriptElements', 'SourceMaps']);

package/lighthouse-core/computed/load-simulator.js

@@ -88,4 +88,4 @@ class LoadSimulator {
   }
 }
 
-module.exports = makeComputedArtifact(LoadSimulator);
+module.exports = makeComputedArtifact(LoadSimulator, ['devtoolsLog', 'settings']);

package/lighthouse-core/computed/main-resource.js

@@ -31,4 +31,4 @@ class MainResource {
   }
 }
 
-module.exports = makeComputedArtifact(MainResource);
+module.exports = makeComputedArtifact(MainResource, ['URL', 'devtoolsLog']);

package/lighthouse-core/computed/main-thread-tasks.js

@@ -21,4 +21,4 @@ class MainThreadTasks {
   }
 }
 
-module.exports = makeComputedArtifact(MainThreadTasks);
+module.exports = makeComputedArtifact(MainThreadTasks, null);

package/lighthouse-core/computed/manifest-values.js

@@ -132,4 +132,4 @@ class ManifestValues {
   }
 }
 
-module.exports = makeComputedArtifact(ManifestValues);
+module.exports = makeComputedArtifact(ManifestValues, ['InstallabilityErrors', 'WebAppManifest']);

package/lighthouse-core/computed/metrics/cumulative-layout-shift.js

@@ -126,4 +126,4 @@ class CumulativeLayoutShift {
   }
 }
 
-module.exports = makeComputedArtifact(CumulativeLayoutShift);
+module.exports = makeComputedArtifact(CumulativeLayoutShift, null);

package/lighthouse-core/computed/metrics/first-contentful-paint-all-frames.js

@@ -31,4 +31,7 @@ class FirstContentfulPaintAllFrames extends NavigationMetric {
   }
 }
 
-module.exports = makeComputedArtifact(FirstContentfulPaintAllFrames);
+module.exports = makeComputedArtifact(
+  FirstContentfulPaintAllFrames,
+  ['devtoolsLog', 'gatherContext', 'settings', 'simulator', 'trace']
+);

package/lighthouse-core/computed/metrics/first-contentful-paint.js

@@ -34,4 +34,7 @@ class FirstContentfulPaint extends NavigationMetric {
   }
 }
 
-module.exports = makeComputedArtifact(FirstContentfulPaint);
+module.exports = makeComputedArtifact(
+  FirstContentfulPaint,
+  ['devtoolsLog', 'gatherContext', 'settings', 'simulator', 'trace']
+);

package/lighthouse-core/computed/metrics/first-meaningful-paint.js

@@ -38,4 +38,7 @@ class FirstMeaningfulPaint extends NavigationMetric {
   }
 }
 
-module.exports = makeComputedArtifact(FirstMeaningfulPaint);
+module.exports = makeComputedArtifact(
+  FirstMeaningfulPaint,
+  ['devtoolsLog', 'gatherContext', 'settings', 'simulator', 'trace']
+);

package/lighthouse-core/computed/metrics/interactive.js

@@ -181,7 +181,10 @@ class Interactive extends NavigationMetric {
   }
 }
 
-module.exports = makeComputedArtifact(Interactive);
+module.exports = makeComputedArtifact(
+  Interactive,
+  ['devtoolsLog', 'gatherContext', 'settings', 'simulator', 'trace']
+);
 
 /**
  * @typedef TimePeriod

package/lighthouse-core/computed/metrics/lantern-first-contentful-paint.js

@@ -196,4 +196,7 @@ class LanternFirstContentfulPaint extends LanternMetric {
   }
 }
 
-module.exports = makeComputedArtifact(LanternFirstContentfulPaint);
+module.exports = makeComputedArtifact(
+  LanternFirstContentfulPaint,
+  ['devtoolsLog', 'gatherContext', 'settings', 'simulator', 'trace']
+);

package/lighthouse-core/computed/metrics/lantern-first-meaningful-paint.js

@@ -77,4 +77,7 @@ class LanternFirstMeaningfulPaint extends LanternMetric {
   }
 }
 
-module.exports = makeComputedArtifact(LanternFirstMeaningfulPaint);
+module.exports = makeComputedArtifact(
+  LanternFirstMeaningfulPaint,
+  ['devtoolsLog', 'gatherContext', 'settings', 'simulator', 'trace']
+);

package/lighthouse-core/computed/metrics/lantern-interactive.js

@@ -107,4 +107,7 @@ class LanternInteractive extends LanternMetric {
   }
 }
 
-module.exports = makeComputedArtifact(LanternInteractive);
+module.exports = makeComputedArtifact(
+  LanternInteractive,
+  ['devtoolsLog', 'gatherContext', 'settings', 'simulator', 'trace']
+);

package/lighthouse-core/computed/metrics/lantern-largest-contentful-paint.js

@@ -105,4 +105,7 @@ class LanternLargestContentfulPaint extends LanternMetric {
   }
 }
 
-module.exports = makeComputedArtifact(LanternLargestContentfulPaint);
+module.exports = makeComputedArtifact(
+  LanternLargestContentfulPaint,
+  ['devtoolsLog', 'gatherContext', 'settings', 'simulator', 'trace']
+);

package/lighthouse-core/computed/metrics/lantern-max-potential-fid.js

@@ -87,4 +87,7 @@ class LanternMaxPotentialFID extends LanternMetricArtifact {
   }
 }
 
-module.exports = makeComputedArtifact(LanternMaxPotentialFID);
+module.exports = makeComputedArtifact(
+  LanternMaxPotentialFID,
+  ['devtoolsLog', 'gatherContext', 'settings', 'simulator', 'trace']
+);

package/lighthouse-core/computed/metrics/lantern-speed-index.js

@@ -144,4 +144,7 @@ class LanternSpeedIndex extends LanternMetric {
   }
 }
 
-module.exports = makeComputedArtifact(LanternSpeedIndex);
+module.exports = makeComputedArtifact(
+  LanternSpeedIndex,
+  ['devtoolsLog', 'gatherContext', 'settings', 'simulator', 'trace']
+);

package/lighthouse-core/computed/metrics/lantern-total-blocking-time.js

@@ -120,4 +120,7 @@ class LanternTotalBlockingTime extends LanternMetric {
   }
 }
 
-module.exports = makeComputedArtifact(LanternTotalBlockingTime);
+module.exports = makeComputedArtifact(
+  LanternTotalBlockingTime,
+  ['devtoolsLog', 'gatherContext', 'settings', 'simulator', 'trace']
+);

package/lighthouse-core/computed/metrics/largest-contentful-paint-all-frames.js

@@ -39,4 +39,7 @@ class LargestContentfulPaintAllFrames extends NavigationMetric {
   }
 }
 
-module.exports = makeComputedArtifact(LargestContentfulPaintAllFrames);
+module.exports = makeComputedArtifact(
+  LargestContentfulPaintAllFrames,
+  ['devtoolsLog', 'gatherContext', 'settings', 'simulator', 'trace']
+);

package/lighthouse-core/computed/metrics/largest-contentful-paint.js

@@ -46,4 +46,7 @@ class LargestContentfulPaint extends NavigationMetric {
   }
 }
 
-module.exports = makeComputedArtifact(LargestContentfulPaint);
+module.exports = makeComputedArtifact(
+  LargestContentfulPaint,
+  ['devtoolsLog', 'gatherContext', 'settings', 'simulator', 'trace']
+);

package/lighthouse-core/computed/metrics/max-potential-fid.js

@@ -39,4 +39,7 @@ class MaxPotentialFID extends NavigationMetric {
   }
 }
 
-module.exports = makeComputedArtifact(MaxPotentialFID);
+module.exports = makeComputedArtifact(
+  MaxPotentialFID,
+  ['devtoolsLog', 'gatherContext', 'settings', 'simulator', 'trace']
+);

package/lighthouse-core/computed/metrics/speed-index.js

@@ -34,4 +34,7 @@ class SpeedIndex extends NavigationMetric {
   }
 }
 
-module.exports = makeComputedArtifact(SpeedIndex);
+module.exports = makeComputedArtifact(
+  SpeedIndex,
+  ['devtoolsLog', 'gatherContext', 'settings', 'simulator', 'trace']
+);

package/lighthouse-core/computed/metrics/timing-summary.js

@@ -144,4 +144,7 @@ class TimingSummary {
   }
 }
 
-module.exports = makeComputedArtifact(TimingSummary);
+module.exports = makeComputedArtifact(
+  TimingSummary,
+  ['devtoolsLog', 'gatherContext', 'settings', 'trace']
+);

package/lighthouse-core/computed/metrics/total-blocking-time.js

@@ -68,4 +68,7 @@ class TotalBlockingTime extends ComputedMetric {
   }
 }
 
-module.exports = makeComputedArtifact(TotalBlockingTime);
+module.exports = makeComputedArtifact(
+  TotalBlockingTime,
+  ['devtoolsLog', 'gatherContext', 'settings', 'simulator', 'trace']
+);

package/lighthouse-core/computed/module-duplication.js

@@ -74,7 +74,7 @@ class ModuleDuplication {
   }
 
   /**
-   * @param {LH.Artifacts} artifacts
+   * @param {Pick<LH.Artifacts, 'ScriptElements'|'SourceMaps'>} artifacts
    * @param {LH.Artifacts.ComputedContext} context
    */
   static async compute_(artifacts, context) {
@@ -133,4 +133,4 @@ class ModuleDuplication {
   }
 }
 
-module.exports = makeComputedArtifact(ModuleDuplication);
+module.exports = makeComputedArtifact(ModuleDuplication, ['ScriptElements', 'SourceMaps']);

package/lighthouse-core/computed/network-analysis.js

@@ -61,4 +61,4 @@ class NetworkAnalysis {
   }
 }
 
-module.exports = makeComputedArtifact(NetworkAnalysis);
+module.exports = makeComputedArtifact(NetworkAnalysis, null);

package/lighthouse-core/computed/network-records.js

@@ -18,4 +18,4 @@ class NetworkRecords {
   }
 }
 
-module.exports = makeComputedArtifact(NetworkRecords);
+module.exports = makeComputedArtifact(NetworkRecords, null);

package/lighthouse-core/computed/page-dependency-graph.js

@@ -467,7 +467,7 @@ class PageDependencyGraph {
   }
 }
 
-module.exports = makeComputedArtifact(PageDependencyGraph);
+module.exports = makeComputedArtifact(PageDependencyGraph, ['devtoolsLog', 'trace']);
 
 /**
  * @typedef {Object} NetworkNodeOutput

package/lighthouse-core/computed/processed-navigation.js

@@ -18,4 +18,4 @@ class ProcessedNavigation {
   }
 }
 
-module.exports = makeComputedArtifact(ProcessedNavigation);
+module.exports = makeComputedArtifact(ProcessedNavigation, null);

package/lighthouse-core/computed/processed-trace.js

@@ -18,4 +18,4 @@ class ProcessedTrace {
   }
 }
 
-module.exports = makeComputedArtifact(ProcessedTrace);
+module.exports = makeComputedArtifact(ProcessedTrace, null);

package/lighthouse-core/computed/resource-summary.js

@@ -111,4 +111,4 @@ class ResourceSummary {
   }
 }
 
-module.exports = makeComputedArtifact(ResourceSummary);
+module.exports = makeComputedArtifact(ResourceSummary, ['URL', 'devtoolsLog', 'budgets']);

package/lighthouse-core/computed/screenshots.js

@@ -26,4 +26,4 @@ class Screenshots {
   }
 }
 
-module.exports = makeComputedArtifact(Screenshots);
+module.exports = makeComputedArtifact(Screenshots, null);

package/lighthouse-core/computed/speedline.js

@@ -51,4 +51,4 @@ class Speedline {
   }
 }
 
-module.exports = makeComputedArtifact(Speedline);
+module.exports = makeComputedArtifact(Speedline, null);

package/lighthouse-core/computed/trace-of-tab.js

@@ -26,5 +26,5 @@ class TraceOfTab {
 }
 
 log.warn(`trace-of-tab`, `trace-of-tab is deprecated, use processed-trace / processed-navigation instead`); // eslint-disable-line max-len
-module.exports = makeComputedArtifact(TraceOfTab);
+module.exports = makeComputedArtifact(TraceOfTab, null);
 

package/lighthouse-core/computed/unused-css.js

@@ -151,4 +151,4 @@ class UnusedCSS {
   }
 }
 
-module.exports = makeComputedArtifact(UnusedCSS);
+module.exports = makeComputedArtifact(UnusedCSS, ['CSSUsage', 'URL', 'devtoolsLog']);

package/lighthouse-core/computed/unused-javascript-summary.js

@@ -169,4 +169,7 @@ class UnusedJavascriptSummary {
   }
 }
 
-module.exports = makeComputedArtifact(UnusedJavascriptSummary);
+module.exports = makeComputedArtifact(
+  UnusedJavascriptSummary,
+  ['bundle', 'scriptCoverages', 'url']
+);

package/lighthouse-core/computed/user-timings.js

@@ -80,4 +80,4 @@ class UserTimings {
   }
 }
 
-module.exports = makeComputedArtifact(UserTimings);
+module.exports = makeComputedArtifact(UserTimings, null);

package/lighthouse-core/computed/viewport-meta.js

@@ -46,7 +46,7 @@ class ViewportMeta {
   }
 }
 
-module.exports = makeComputedArtifact(ViewportMeta);
+module.exports = makeComputedArtifact(ViewportMeta, null);
 
 /**
  * @typedef {object} ViewportMetaResult

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lighthouse",
-  "version": "9.1.0-dev.20211129",
+  "version": "9.1.0-dev.20211130",
   "description": "Automated auditing, performance metrics, and best practices for the web.",
   "main": "./lighthouse-core/index.js",
   "bin": {

package/types/smokehouse.d.ts

@@ -70,6 +70,8 @@ declare global {
       urlFilterRegex?: RegExp;
       skip?: (test: TestDfn, expectation: ExpectedRunnerResult) => string | false;
       modify?: (test: TestDfn, expectation: ExpectedRunnerResult) => void;
+      /** String of form `shardNumber/shardTotal`, e.g. `'1/4'`. */
+      shardArg: string | undefined;
     }
   }
 }