prompttest 1.3.0

package/dist/lib/benchmark.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @module benchmark
+ * @description
+ * Performance benchmarking and diagnostic utilities for PromptTest.
+ * Measures latency and timing distributions (min, avg, p50, p95, max) for
+ * UI hierarchy dumping, screen captures, and fuzzy/spatial node matching.
+ */
+import { AndroidDriver } from './adb.js';
+import { UiNode } from './crawler.js';
+/**
+ * Statistical latency metrics computed over a series of benchmark iterations.
+ */
+export interface BenchmarkMetrics {
+    /** Minimum elapsed time in milliseconds */
+    minMs: number;
+    /** Maximum elapsed time in milliseconds */
+    maxMs: number;
+    /** Arithmetic average elapsed time in milliseconds */
+    avgMs: number;
+    /** 50th percentile (median) elapsed time in milliseconds */
+    p50Ms: number;
+    /** 95th percentile elapsed time in milliseconds */
+    p95Ms: number;
+    /** Number of recorded samples */
+    iterations: number;
+    /** Raw recorded durations in milliseconds */
+    durations: number[];
+}
+/**
+ * Complete benchmark report covering core device and engine operations.
+ */
+export interface BenchmarkReport {
+    /** ISO 8601 timestamp when the benchmark was executed */
+    timestamp: string;
+    /** Device identifier or model tested */
+    device: string;
+    /** Target package tested, if specified */
+    package?: string;
+    /** Screen capture latency metrics */
+    screencap: BenchmarkMetrics;
+    /** UI hierarchy dump and parsing latency metrics */
+    uiHierarchy: BenchmarkMetrics;
+    /** Natural language node matching latency metrics on 1,000-node layout */
+    nodeMatching: BenchmarkMetrics;
+    /** Total elapsed time of the benchmark suite in milliseconds */
+    totalDurationMs: number;
+}
+/**
+ * Configuration options for running performance benchmarks.
+ */
+export interface BenchmarkOptions {
+    /** Number of benchmark iterations per operation (default: 5) */
+    iterations?: number;
+    /** Target device serial number */
+    serial?: string;
+    /** Target application package name */
+    packageName?: string;
+    /** If true, executes against synthetic mock data even if device is present */
+    forceMock?: boolean;
+}
+/**
+ * Calculates a specific percentile (e.g. 50 for median, 95 for p95) from raw numbers.
+ *
+ * @param values - Array of numeric measurements.
+ * @param percentile - Target percentile in range [0, 100].
+ * @returns The calculated percentile value rounded to two decimal places.
+ */
+export declare function calculatePercentile(values: number[], percentile: number): number;
+/**
+ * Computes summary statistical metrics from an array of measured durations.
+ *
+ * @param durations - Array of measured durations in milliseconds.
+ * @returns Computed BenchmarkMetrics.
+ */
+export declare function summarizeMetrics(durations: number[]): BenchmarkMetrics;
+/**
+ * Generates a realistic synthetic 1,000-node UI hierarchy tree for benchmark matching.
+ * Models a complex mobile application screen containing headers, nested scroll lists,
+ * form inputs, action cards, and navigational tabs.
+ *
+ * @param nodeCount - Target number of nodes to generate (default: 1000).
+ * @returns An array of 1,000 structured UiNode elements.
+ */
+export declare function generateSyntheticHierarchy(nodeCount?: number): UiNode[];
+/**
+ * Runs the diagnostic benchmark across device screencap, hierarchy retrieval,
+ * and natural language node matching algorithms.
+ *
+ * @param driver - The AndroidDriver instance to benchmark against.
+ * @param options - Benchmark configuration options.
+ * @returns Completed BenchmarkReport.
+ */
+export declare function runBenchmark(driver?: AndroidDriver, options?: BenchmarkOptions): Promise<BenchmarkReport>;
+/**
+ * Formats a BenchmarkReport into an attractive CLI terminal summary table.
+ *
+ * @param report - The BenchmarkReport to format.
+ * @returns Multi-line formatted string.
+ */
+export declare function formatBenchmarkTable(report: BenchmarkReport): string;

package/dist/lib/checkpoint.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Structure of the saved checkpoint JSON data.
+ */
+export interface CheckpointData {
+    /** The specification file name or identifier that was being executed. */
+    specFile: string;
+    /** The Android package name of the app under test. */
+    packageName: string;
+    /** The 0-based index of the last step that was successfully completed. */
+    lastPassedStep: number;
+    /** The total number of steps in the specification. */
+    totalSteps: number;
+    /** ISO 8601 timestamp of when the checkpoint was saved. */
+    savedAt: string;
+}
+/**
+ * Manages saving, loading, and clearing execution checkpoints for test runs.
+ */
+export declare class CheckpointManager {
+    private checkpointDir;
+    /**
+     * Initializes a new CheckpointManager.
+     *
+     * @param checkpointDir The directory where checkpoint files should be stored. Defaults to './output/checkpoints'.
+     */
+    constructor(checkpointDir?: string);
+    private filePath;
+    /**
+     * Persists the index of the last successfully completed step (0-based).
+     *
+     * @param specName The name of the test specification.
+     * @param packageName The Android package name.
+     * @param lastPassedStep The 0-based index of the step just completed.
+     * @param totalSteps The total number of steps in the test.
+     */
+    save(specName: string, packageName: string, lastPassedStep: number, totalSteps: number): Promise<void>;
+    /**
+     * Loads an existing checkpoint from disk.
+     *
+     * @param specName The name of the test specification.
+     * @returns A Promise resolving to the parsed CheckpointData, or null if no checkpoint exists or it's invalid.
+     */
+    load(specName: string): Promise<CheckpointData | null>;
+    /**
+     * Deletes a checkpoint for a given spec. Should be called after a fully successful run.
+     *
+     * @param specName The name of the test specification.
+     */
+    clear(specName: string): Promise<void>;
+    /**
+     * Returns the 0-based step index to resume from, based on the last saved checkpoint.
+     *
+     * @param specName The name of the test specification.
+     * @returns The 0-based step index to resume from, or 0 if no checkpoint is found.
+     */
+    getResumeIndex(specName: string): Promise<number>;
+}
+/**
+ * A globally accessible singleton instance of CheckpointManager.
+ */
+export declare const checkpointManager: CheckpointManager;

package/dist/lib/config-loader.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @module config-loader
+ * @description Discovers, parses, and merges PromptTest configuration from prompttest.config.json
+ * and environment variables (PROMPTTEST_*) over CONFIG defaults.
+ */
+export interface PromptTestConfig {
+    adb: {
+        commandTimeoutMs: number;
+        binaryTimeoutMs: number;
+        retryCount: number;
+        retryBaseDelayMs: number;
+    };
+    polling: {
+        intervalMs: number;
+        jitterMs: number;
+        defaultTimeoutMs: number;
+        extendedTimeoutMs: number;
+        hierarchyCacheTtlMs: number;
+        verifyCacheTtlMs: number;
+    };
+    settle: {
+        tapMs: number;
+        backMs: number;
+        launchMs: number;
+        stopMs: number;
+        keyboardDismissMs: number;
+        scrollMs: number;
+        toggleMs: number;
+        selectMs: number;
+        inputFocusMs: number;
+        inputClearMs: number;
+        inputDoneMs: number;
+        submitWaitMs: number;
+    };
+    gestures: {
+        swipeDurationMs: number;
+        longPressDurationMs: number;
+        bottomNavThresholdRatio: number;
+        tapTargetYRatio: number;
+    };
+    recorder: {
+        staleTapTimeoutMs: number;
+        asyncRefreshDelayMs: number;
+        heartbeatIntervalMs: number;
+    };
+    screen: {
+        fallbackWidth: number;
+        fallbackHeight: number;
+    };
+    visual: {
+        overlapRatio: number;
+    };
+    device: {
+        maxDeviceRetries: number;
+        autoReconnect: boolean;
+    };
+    flow: {
+        maxLoopIterations: number;
+        waitUntilTimeoutMs: number;
+        defaultRetryCount: number;
+    };
+    ai: {
+        provider: 'heuristic' | 'openai' | 'anthropic' | 'ollama' | 'mock';
+        model: string;
+        selfHealing: boolean;
+        confidenceThreshold: number;
+        maxHealingAttempts: number;
+        endpoint: string;
+    };
+    locale: string;
+}
+/**
+ * Loads configuration by merging CONFIG defaults, prompttest.config.json (if present),
+ * and PROMPTTEST_* environment variables.
+ *
+ * @param configFilePath - Optional explicit path to configuration JSON file.
+ * @returns The resolved PromptTestConfig object.
+ */
+export declare function loadConfig(configFilePath?: string): PromptTestConfig;
+/**
+ * Returns the currently active configuration, loading it if not yet initialized.
+ */
+export declare function getActiveConfig(): PromptTestConfig;
+/**
+ * Resets the active configuration cache (useful for testing).
+ */
+export declare function resetActiveConfig(): void;

package/dist/lib/config.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @module config
+ * @description Centralized PromptTest Engine Configuration.
+ *
+ * Consolidates all magic numbers, timeouts, settle durations,
+ * gesture thresholds, and polling strategies across the codebase.
+ * This guarantees consistent timing and reliable execution behavior
+ * during natural language script execution, autonomous crawling,
+ * and ADB interactions.
+ */
+/**
+ * Helper to compute settle scaling factor from PROMPTTEST_SETTLE_FACTOR environment variable.
+ */
+export declare function getSettleFactor(): number;
+/**
+ * Scales a duration in milliseconds by the global settle factor, clamped to a minimum floor.
+ *
+ * @param ms - Target duration in milliseconds.
+ * @param minFloorMs - Minimum floor duration in milliseconds (default: 50).
+ * @returns Scaled millisecond duration.
+ */
+export declare function scaleSettle(ms: number, minFloorMs?: number): number;
+/**
+ * The global configuration settings for PromptTest.
+ */
+export declare const CONFIG: {
+    /** Configuration related to ADB command execution and retry behavior. */
+    readonly adb: {
+        readonly commandTimeoutMs: 20000;
+        readonly binaryTimeoutMs: 45000;
+        readonly retryCount: 2;
+        readonly retryBaseDelayMs: 200;
+    };
+    /** Configuration for UI hierarchy polling and caching mechanisms. */
+    readonly polling: {
+        readonly intervalMs: 200;
+        readonly jitterMs: 80;
+        readonly defaultTimeoutMs: 3000;
+        readonly extendedTimeoutMs: 3500;
+        readonly hierarchyCacheTtlMs: 3500;
+        readonly verifyCacheTtlMs: 2000;
+    };
+    /** Delays applied after various UI interactions to allow animations or state changes to settle. */
+    readonly settle: {
+        readonly tapMs: number;
+        readonly backMs: number;
+        readonly launchMs: number;
+        readonly stopMs: number;
+        readonly keyboardDismissMs: number;
+        readonly scrollMs: number;
+        readonly toggleMs: number;
+        readonly selectMs: number;
+        readonly inputFocusMs: number;
+        readonly inputClearMs: number;
+        readonly inputDoneMs: number;
+        readonly submitWaitMs: number;
+    };
+    /** Parameters for Android gesture generation, calculating bounds, and swipe physics. */
+    readonly gestures: {
+        readonly swipeDurationMs: 300;
+        readonly longPressDurationMs: 1000;
+        readonly bottomNavThresholdRatio: 0.88;
+        readonly tapTargetYRatio: 0.96;
+    };
+    /** Settings for the AutonomousRecorder component monitoring live device usage. */
+    readonly recorder: {
+        readonly staleTapTimeoutMs: 3000;
+        readonly asyncRefreshDelayMs: 80;
+        readonly heartbeatIntervalMs: 1500;
+    };
+    /** Screen geometry defaults when device cannot report dimensions. */
+    readonly screen: {
+        readonly fallbackWidth: 1080;
+        readonly fallbackHeight: 2400;
+    };
+    /** Visual defect detection thresholds and settings. */
+    readonly visual: {
+        readonly overlapRatio: 0.2;
+    };
+    /** Device connection and resilience parameters. */
+    readonly device: {
+        readonly maxDeviceRetries: 2;
+        readonly autoReconnect: true;
+    };
+    /** Programmatic flow control, loops, and conditional execution. */
+    readonly flow: {
+        readonly maxLoopIterations: 50;
+        readonly waitUntilTimeoutMs: 10000;
+        readonly defaultRetryCount: 3;
+    };
+    /** AI step expansion, semantic locator resolution, and self-healing. */
+    readonly ai: {
+        readonly provider: "heuristic" | "openai" | "anthropic" | "ollama" | "mock";
+        readonly model: "gpt-4o-mini";
+        readonly selfHealing: true;
+        readonly confidenceThreshold: 0.75;
+        readonly maxHealingAttempts: 2;
+        readonly endpoint: "";
+    };
+    /** Autonomous locator learning and persistent memory configuration. */
+    readonly memory: {
+        readonly staleThresholdDays: number;
+        readonly staleDecayAmount: 0.2;
+        readonly minConfidenceFloor: 0.2;
+        readonly maxHealedConfidence: 0.65;
+    };
+    /** UI Hierarchy XML parser configuration (SP-05). */
+    readonly parser: {
+        readonly mode: "regex" | "streaming";
+    };
+    /** Safety guard configuration for autonomous actions (AX-09, AX-10). */
+    readonly safety: {
+        readonly mode: "strict" | "moderate" | "interactive" | "disabled";
+        readonly customBlacklist: readonly string[];
+    };
+    /** Autonomous Explorer v3 settings (AX-12, AX-15, AX-16). */
+    readonly explorer: {
+        readonly strategy: "dfs" | "heuristic";
+        readonly maxTabs: number;
+        readonly maxScreens: number;
+        readonly maxDepth: number;
+        readonly stepBudget: number;
+        readonly screenshots: "state-change" | "failure-only" | "all";
+    };
+    /** Localization and multilingual taxonomy configuration. */
+    readonly locale: "en";
+};
+/**
+ * Returns a polling delay with random jitter to prevent thundering herd
+ * and reduce contention with the ADB daemon.
+ *
+ * @param baseMs The base delay in milliseconds. Defaults to CONFIG.polling.intervalMs.
+ * @param jitterMs The maximum jitter range in milliseconds. Defaults to CONFIG.polling.jitterMs.
+ * @returns A computed delay in milliseconds including base and jitter.
+ */
+export declare function getJitteredPollDelay(baseMs?: number, jitterMs?: number): number;