Document WPT capability runner functions

Author: andrewiggins

packages/wpt-runner/scripts/capabilities.ts

@@ -13,6 +13,7 @@ export interface CapabilityRow {
 
 const VALID_STATUSES: ReadonlySet<string> = new Set(['supported', 'deferred']);
 
+/** Reads a capability table and rejects content that is not canonical. */
 export async function readCapabilities(file: string): Promise<CapabilityRow[]> {
   const source = await fs.readFile(file, 'utf8');
   const rows = parseCapabilities(source, file);
@@ -27,6 +28,7 @@ export async function readCapabilities(file: string): Promise<CapabilityRow[]> {
   return rows;
 }
 
+/** Parses and validates capability rows from escaped TSV source. */
 export function parseCapabilities(
   source: string,
   label = 'capabilities.tsv',
@@ -89,6 +91,7 @@ export function parseCapabilities(
   return rows;
 }
 
+/** Sorts and serializes capability rows as canonical escaped TSV. */
 export function serializeCapabilities(rows: readonly CapabilityRow[]): string {
   const sorted = [...rows].sort(compareCapabilityRows);
   const lines = [
@@ -119,6 +122,7 @@ export function compareCodeUnits(left: string, right: string): number {
   return left < right ? -1 : 1;
 }
 
+/** Groups capability rows by their WPT file while preserving row order. */
 export function rowsByPath(
   rows: readonly CapabilityRow[],
 ): Map<string, CapabilityRow[]> {
@@ -143,6 +147,7 @@ function escapeField(value: string): string {
     .replaceAll('\r', '\\r');
 }
 
+/** Decodes supported TSV escapes and rejects malformed sequences. */
 function unescapeField(
   value: string,
   label: string,

packages/wpt-runner/scripts/run-wpt.ts

@@ -113,6 +113,7 @@ try {
   await server?.close().catch(() => {});
 }
 
+/** Parses CLI flags and chooses the default capability enforcement mode. */
 function parseArguments(arguments_: string[]): RunnerOptions {
   const normalizedArguments =
     arguments_[0] === '--' ? arguments_.slice(1) : arguments_;
@@ -147,6 +148,7 @@ function parseArguments(arguments_: string[]): RunnerOptions {
   };
 }
 
+/** Resolves deduplicated WPT paths and verifies enforced paths are classified. */
 function selectPaths(
   options: RunnerOptions,
   groupedCapabilities: ReadonlyMap<string, readonly CapabilityRow[]>,
@@ -167,6 +169,7 @@ function selectPaths(
   return paths;
 }
 
+/** Runs one WPT file and converts page evaluation errors into a run record. */
 async function runWpt(
   browserPage: Page,
   testPath: string,
@@ -189,6 +192,7 @@ async function runWpt(
   }
 }
 
+/** Reports an unclassified run and returns whether any result failed. */
 function printExploratoryResult(run: WptRunRecord): boolean {
   const tests = run.result?.tests ?? [];
   const failedTests = tests.filter((test) => test.status !== 0);
@@ -206,6 +210,7 @@ function printExploratoryResult(run: WptRunRecord): boolean {
   return failed;
 }
 
+/** Evaluates and reports classified results, drift, and promotion candidates. */
 function printCapabilityResult(
   run: WptRunRecord,
   rows: readonly CapabilityRow[],
@@ -263,6 +268,7 @@ function printTestFailure(test: WptHarnessTestResult, prefix: string): void {
   if (test.stack) console.log(indent(test.stack, '    '));
 }
 
+/** Prints a run error and its most recent captured browser logs. */
 function printRunError(run: WptRunRecord): void {
   if (run.error) console.log(indent(run.error, '  '));
   if (run.state === 'error' && run.logs?.length > 0) {