import { TestScenario, endpointAssetTransferMethod, endpointAuthCaptureCoverageBranch, endpointPathForCoverageMinimization, endpointPaymentScheme, } from './types'; import { log, verboseLog } from './logger'; /** * Fisher-Yates shuffle — returns a new shuffled copy without mutating the input. * * An optional seed (integer) makes the shuffle deterministic and reproducible; * omit it (or pass undefined) for a truly random shuffle on every run. */ export function shuffleScenarios(scenarios: TestScenario[], seed?: number): TestScenario[] { const arr = [...scenarios]; // Simple seeded LCG so that --seed produces a reproducible order. let rng: () => number; if (seed !== undefined) { let s = seed >>> 0; rng = () => { s = (Math.imul(1664525, s) + 1013904223) >>> 0; return s / 0x100000000; }; } else { rng = Math.random; } for (let i = arr.length - 1; i > 0; i--) { const j = Math.floor(rng() * (i + 1)); [arr[i], arr[j]] = [arr[j], arr[i]]; } return arr; } /** * Coverage tracker for minimizing test runs * * Tracks which components (client, server, facilitator) have been tested * with which protocol families and versions to skip redundant tests. */ export class CoverageTracker { private clientsCovered = new Set(); private serversCovered = new Set(); private facilitatorsCovered = new Set(); private endpointsCovered = new Set(); /** Each auth-capture catalog branch (self-sync, deferred, etc.) at least once per --min run. */ private authCaptureBranchesCovered = new Set(); /** * Generate a coverage key for a component * Format: "component-name-protocolFamily-vVersion" * * Args: * componentName: Name of the component * protocolFamily: Protocol family (e.g., 'evm', 'svm') * version: x402 version number * * Returns: * Coverage key string */ private getCoverageKey(componentName: string, protocolFamily: string, version: number): string { return `${componentName}-${protocolFamily}-v${version}`; } /** * Generate a coverage key for an endpoint * Format: "server-name-endpoint-path-protocolFamily-scheme-assetMethod-vVersion" * * This ensures each unique endpoint on a server is tested separately, * including different EVM schemes and asset transfer methods. */ private getEndpointCoverageKey( serverName: string, endpointPath: string, protocolFamily: string, version: number, scenario: TestScenario, ): string { const scheme = endpointPaymentScheme(scenario.endpoint); const method = protocolFamily === 'evm' ? `${scheme}-${endpointAssetTransferMethod(scenario.endpoint) ?? 'eip3009'}` : scheme; // One auth-capture permit2 scenario is enough to exercise the route across servers. if (scheme === 'auth-capture' && endpointAssetTransferMethod(scenario.endpoint) === 'permit2') { return `global-${endpointPath}-${protocolFamily}-${method}-v${version}`; } return `${serverName}-${endpointPath}-${protocolFamily}-${method}-v${version}`; } /** * Check if a scenario provides new coverage * * A scenario provides new coverage if ANY of its components haven't been * tested with this protocol family and version combination. * * Args: * scenario: Test scenario to evaluate * * Returns: * true if scenario provides new coverage, false if all components already covered */ isNewCoverage(scenario: TestScenario): boolean { const version = scenario.server.config.x402Version ?? 1; const protocolFamily = scenario.protocolFamily; const clientKey = this.getCoverageKey( scenario.client.name, protocolFamily, version ); const serverKey = this.getCoverageKey( scenario.server.name, protocolFamily, version ); const facilitatorKey = this.getCoverageKey( scenario.facilitator?.name || 'default', protocolFamily, version ); const endpointKey = this.getEndpointCoverageKey( scenario.server.name, endpointPathForCoverageMinimization(scenario.endpoint), protocolFamily, version, scenario, ); // Check if ANY component hasn't been covered yet const clientNew = !this.clientsCovered.has(clientKey); const serverNew = !this.serversCovered.has(serverKey); const facilitatorNew = !this.facilitatorsCovered.has(facilitatorKey); const endpointNew = !this.endpointsCovered.has(endpointKey); const authCaptureBranch = endpointPaymentScheme(scenario.endpoint) === 'auth-capture' ? endpointAuthCaptureCoverageBranch(scenario.endpoint) : undefined; const branchNew = authCaptureBranch !== undefined && authCaptureBranch !== 'other' && !this.authCaptureBranchesCovered.has(authCaptureBranch); const isNew = clientNew || serverNew || facilitatorNew || endpointNew || branchNew; if (isNew) { verboseLog( ` 📊 New coverage: ${clientNew ? `client(${clientKey})` : ''} ${serverNew ? `server(${serverKey})` : ''} ${facilitatorNew ? `facilitator(${facilitatorKey})` : ''} ${endpointNew ? `endpoint(${endpointKey})` : ''} ${branchNew ? `authCaptureBranch(${authCaptureBranch})` : ''}`, ); } return isNew; } /** * Mark a scenario's components as covered * * Args: * scenario: Test scenario to mark as covered */ markCovered(scenario: TestScenario): void { const version = scenario.server.config.x402Version ?? 1; const protocolFamily = scenario.protocolFamily; const clientKey = this.getCoverageKey( scenario.client.name, protocolFamily, version ); const serverKey = this.getCoverageKey( scenario.server.name, protocolFamily, version ); const facilitatorKey = this.getCoverageKey( scenario.facilitator?.name || 'default', protocolFamily, version ); const endpointKey = this.getEndpointCoverageKey( scenario.server.name, endpointPathForCoverageMinimization(scenario.endpoint), protocolFamily, version, scenario, ); this.clientsCovered.add(clientKey); this.serversCovered.add(serverKey); this.facilitatorsCovered.add(facilitatorKey); this.endpointsCovered.add(endpointKey); const authCaptureBranch = endpointPaymentScheme(scenario.endpoint) === 'auth-capture' ? endpointAuthCaptureCoverageBranch(scenario.endpoint) : undefined; if (authCaptureBranch !== undefined && authCaptureBranch !== 'other') { this.authCaptureBranchesCovered.add(authCaptureBranch); } } /** * Get coverage statistics * * Returns: * Object containing coverage counts for each component type */ getStats(): { clients: number; servers: number; facilitators: number; endpoints: number; authCaptureBranches: number; } { return { clients: this.clientsCovered.size, servers: this.serversCovered.size, facilitators: this.facilitatorsCovered.size, endpoints: this.endpointsCovered.size, authCaptureBranches: this.authCaptureBranchesCovered.size, }; } } /** * Filter scenarios based on coverage to minimize test runs. * * Shuffles the input before the greedy coverage pass so that equivalent * implementations (e.g. go / python / typescript facilitators, or * express / flask / gin servers) are distributed evenly rather than the * first alphabetical entry always being chosen for every coverage slot. * * Auth-capture EIP-3009 catalog paths share one endpoint slot per server * (`auth-capture~eip3009`), but each {@link endpointAuthCaptureCoverageBranch} * must run at least once. Permit2 uses a single global endpoint slot across * servers (`auth-capture~permit2`). * * Pass a numeric `seed` for a reproducible shuffle; omit it (default) for a * fresh random distribution on every run. * * Args: * scenarios: All test scenarios to filter * seed: Optional integer seed for reproducible shuffling * * Returns: * Filtered list of scenarios that provide new coverage */ export function minimizeScenarios(scenarios: TestScenario[], seed?: number): TestScenario[] { // Shuffle before the greedy pass to ensure random, even distribution // across equivalent implementations rather than always picking the first // alphabetical entry (e.g. "go" before "python"/"typescript"). const shuffled = shuffleScenarios(scenarios, seed); const seedLabel = seed !== undefined ? ` (seed=${seed})` : ' (random)'; verboseLog(` 🔀 Shuffled ${shuffled.length} scenarios before coverage pass${seedLabel}`); const tracker = new CoverageTracker(); const minimized: TestScenario[] = []; for (const scenario of shuffled) { if (tracker.isNewCoverage(scenario)) { minimized.push(scenario); tracker.markCovered(scenario); } else { verboseLog(` ⏭️ Skipping (covered): ${scenario.client.name} → ${scenario.server.name} → ${scenario.endpoint.path} [${scenario.facilitator?.name || 'default'}] (${scenario.protocolFamily}-v${scenario.server.config.x402Version})`); } } const stats = tracker.getStats(); const reductionPercent = ((1 - minimized.length / scenarios.length) * 100).toFixed(1); log(''); log('📊 Coverage-Based Minimization'); log('=============================='); log(`Total scenarios: ${scenarios.length}`); log(`Selected scenarios: ${minimized.length} (${reductionPercent}% reduction)`); log(`Skipped scenarios: ${scenarios.length - minimized.length}`); log(''); log('Coverage achieved:'); log(` • Clients: ${stats.clients} unique combinations`); log(` • Servers: ${stats.servers} unique combinations`); log(` • Facilitators: ${stats.facilitators} unique combinations`); log(` • Endpoints: ${stats.endpoints} unique combinations`); if (stats.authCaptureBranches > 0) { log(` • Auth-capture branches: ${stats.authCaptureBranches}`); } log(''); return minimized; }