prompttest 1.3.0

package/dist/lib/enterprise.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @module enterprise
+ * @description
+ * Enterprise Quality Controls & Result Aggregation for PromptTest.
+ * Provides:
+ * 1. Release Confidence / Quality Scoring (inspired by Testsigma Atto).
+ * 2. Multi-Device Central Result Aggregator (merges per-device results into unified matrices).
+ * 3. Executive Summary HTML Dashboard generation.
+ */
+import type { QaReportData } from './reporter.js';
+export type ConfidenceGrade = 'A' | 'B' | 'C' | 'F';
+export interface ReleaseConfidence {
+    score: number;
+    grade: ConfidenceGrade;
+    verdict: 'READY_FOR_RELEASE' | 'PROCEED_WITH_CAUTION' | 'RELEASE_BLOCKER';
+    rationale: string;
+    metrics: {
+        passRate: number;
+        criticalFailures: number;
+        visualDefects: number;
+        totalSteps: number;
+        skippedSteps: number;
+    };
+}
+export interface DeviceRunSummary {
+    deviceId: string;
+    suiteName: string;
+    packageName: string;
+    totalSteps: number;
+    passedSteps: number;
+    failedSteps: number;
+    skippedSteps: number;
+    durationSeconds: number;
+    confidenceScore: number;
+    confidenceGrade: ConfidenceGrade;
+    sourceFile: string;
+}
+export interface AggregatedReport {
+    timestamp: string;
+    totalRuns: number;
+    uniqueDevices: string[];
+    totalSteps: number;
+    passedSteps: number;
+    failedSteps: number;
+    skippedSteps: number;
+    overallPassRate: number;
+    overallConfidence: ReleaseConfidence;
+    deviceSummaries: DeviceRunSummary[];
+}
+/**
+ * Calculates the Atto-inspired Release Confidence score and letter grade for a test execution report.
+ *
+ * @param report - Complete QaReportData from a test run.
+ * @returns ReleaseConfidence assessment.
+ */
+export declare function calculateReleaseConfidence(report: QaReportData): ReleaseConfidence;
+/**
+ * Merges multiple per-device test execution reports into an aggregated enterprise summary.
+ * Scans directories recursively for `*-results.json` or accepts explicit JSON file paths.
+ *
+ * @param input - Directory path to scan or array of JSON file paths.
+ * @returns Combined AggregatedReport.
+ */
+export declare function mergeReports(input?: string | string[]): AggregatedReport;
+/**
+ * Generates an executive-ready, standalone HTML dashboard summarizing multi-device regression passes.
+ *
+ * @param aggregated - The AggregatedReport data.
+ * @returns Full HTML string.
+ */
+export declare function generateAggregatedHtml(aggregated: AggregatedReport): string;

package/dist/lib/errors.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @module errors
+ * @description Standardized error taxonomy and process exit codes for PromptTest.
+ * Distinguishes infrastructure/device failures from test assertion failures and config errors.
+ */
+/**
+ * Standard process exit codes for CLI automation and CI/CD pipelines.
+ */
+export declare enum ExitCode {
+    /** All steps passed successfully */
+    SUCCESS = 0,
+    /** One or more test steps failed assertion/matching */
+    TEST_FAILED = 1,
+    /** Device is offline, unauthorized, or disconnected */
+    DEVICE_UNAVAILABLE = 2,
+    /** Invalid configuration, missing files, or bad CLI flags */
+    CONFIG_ERROR = 3,
+    /** Device lock contention or hardware mutex error */
+    LOCKED = 4
+}
+/**
+ * Base error class for all PromptTest-specific exceptions.
+ */
+export declare class PromptTestError extends Error {
+    readonly exitCode: ExitCode;
+    readonly phase?: string;
+    constructor(message: string, exitCode?: ExitCode, phase?: string);
+}
+/**
+ * Thrown when ADB or the target Android device cannot be reached or goes offline.
+ */
+export declare class DeviceError extends PromptTestError {
+    constructor(message: string, phase?: string);
+}
+/**
+ * Thrown when a UI element locator cannot be resolved or matched within the timeout.
+ */
+export declare class LocatorError extends PromptTestError {
+    readonly target?: string;
+    readonly candidateMatches?: {
+        text: string;
+        score: number;
+    }[];
+    constructor(message: string, target?: string, candidateMatches?: {
+        text: string;
+        score: number;
+    }[], phase?: string);
+}
+/**
+ * Thrown when a spec file is missing, syntax is corrupt, or invalid arguments are passed.
+ */
+export declare class ConfigError extends PromptTestError {
+    constructor(message: string, phase?: string);
+}
+/**
+ * Thrown when the target device is already locked by another active process.
+ */
+export declare class LockError extends PromptTestError {
+    readonly serial?: string;
+    constructor(message: string, serial?: string, phase?: string);
+}
+/**
+ * Thrown when circular references are detected in modular spec inclusion (INCLUDE/RUN_SPEC).
+ */
+export declare class SpecRecursionError extends PromptTestError {
+    readonly cycle?: string[];
+    constructor(message: string, cycle?: string[], phase?: string);
+}

package/dist/lib/explorer.d.ts

@@ -0,0 +1,121 @@
+import { AndroidDriver } from './adb.js';
+import { type SafetyMode, type UiNode } from './crawler.js';
+import { SemanticFormFiller } from './form-filler.js';
+import { QaReporter } from './reporter.js';
+import { MemoryEngine } from './memory.js';
+/**
+ * Configuration options for the AutonomousExplorer.
+ */
+export interface ExplorerOptions {
+    /** The target Android package name to explore (e.g., com.example.app) */
+    packageName: string;
+    /** Optional device serial number. If omitted, the default device is used. */
+    serial?: string;
+    /** Exploration strategy to use ('dfs' for universal hierarchical state-graph DFS, 'heuristic' for 5-step heuristic). Default is 'dfs'. */
+    strategy?: 'dfs' | 'heuristic';
+    /** Maximum number of bottom navigation tabs to traverse. Default is 15. */
+    maxTabs?: number;
+    /** Whether to explore master-detail list views. Default is true. */
+    exploreLists?: boolean;
+    /** Whether to fast-forward past previously crawled screens recorded in MemoryEngine (AX-07). Default is true. */
+    skipAlreadyCrawled?: boolean;
+    /** Safety mode enforcement policy (AX-10). Default is 'strict'. */
+    safetyMode?: SafetyMode;
+    /** Custom blacklist keywords to treat as destructive actions (AX-09). */
+    safetyBlacklist?: string[];
+    /** Maximum number of unique screen states to discover and index (AX-12). Default is 30. */
+    maxScreens?: number;
+    /** Maximum recursion depth for nested screen transitions (AX-12). Default is 5. */
+    maxDepth?: number;
+    /** Maximum number of interaction steps to execute in total (AX-12). Default is 100. */
+    stepBudget?: number;
+    /** Screenshot policy ('state-change', 'failure-only', 'all') (AX-16). Default is 'state-change'. */
+    screenshots?: 'state-change' | 'failure-only' | 'all';
+}
+/**
+ * AutonomousExplorer implements the heuristic mobile crawler.
+ * It coordinates ADB interactions, UI hierarchy analysis, and action execution
+ * to automatically test the application and discover crashes or errors.
+ */
+export declare class AutonomousExplorer {
+    private driver;
+    private formFiller;
+    private reporter;
+    private memory;
+    private safetyHitList;
+    private externalSkippedList;
+    private devDefectsList;
+    private visitedScreenHashes;
+    private executedStepCount;
+    /**
+     * Creates an instance of AutonomousExplorer.
+     *
+     * @param driver - The AndroidDriver instance for ADB commands (dependency injection).
+     * @param formFiller - The SemanticFormFiller instance for handling input forms.
+     * @param reporter - The QaReporter instance for logging test steps and generating the report.
+     * @param memory - The MemoryEngine instance for offline crawl coverage and learning (AX-07).
+     */
+    constructor(driver?: AndroidDriver, formFiller?: SemanticFormFiller, reporter?: QaReporter, memory?: MemoryEngine);
+    /**
+     * Retrieves the underlying MemoryEngine instance.
+     */
+    getMemory(): MemoryEngine;
+    /**
+     * Retrieves the list of destructive action labels prevented by the safety guard.
+     */
+    getSafetyHitList(): readonly string[];
+    /**
+     * Retrieves the list of external intent links bypassed by the jail guard.
+     */
+    getExternalSkippedList(): readonly string[];
+    /**
+     * Retrieves the list of development errors/LogBoxes triaged.
+     */
+    getDevDefectsList(): readonly string[];
+    /**
+     * Retrieves the count of unique screen states visited during exploration.
+     */
+    getVisitedScreensCount(): number;
+    /**
+     * Detects whether the active foreground app has escaped into an external application (AX-12),
+     * and executes containment recovery to restore the target application into the foreground.
+     */
+    packageJailGuard(packageName: string, serial?: string): Promise<boolean>;
+    /**
+     * Captures UI hierarchy globally, intercepting and triaging any development error consoles,
+     * LogBox overlays, warnings, info toasts, or ANRs before returning a clean app hierarchy.
+     */
+    getCleanUiHierarchy(packageName: string, serial?: string, maxTriageAttempts?: number): Promise<{
+        xml: string;
+        flat: UiNode[];
+    }>;
+    /**
+     * Scans and triages development error consoles, LogBox overlays, or ANRs (AX-13).
+     */
+    handleDevOverlays(nodes: UiNode[], packageName: string, serial?: string): Promise<boolean>;
+    /**
+     * Automatically lowers the on-screen soft keyboard after typing (AX-14).
+     */
+    dismissSoftKeyboard(serial?: string): Promise<void>;
+    /**
+     * Executes the heuristic exploration pipeline on the target application.
+     *
+     * @param options - The ExplorerOptions configuring the exploration.
+     * @returns A promise that resolves when the exploration and report generation are complete.
+     */
+    explore(options: ExplorerOptions): Promise<void>;
+    /**
+     * Executes the error sentinel which combines parallel logcat crash checking
+     * and UI hierarchy parsing for maximum speed and robust error detection.
+     *
+     * @param packageName - The target application package name.
+     * @param serial - The device serial number.
+     * @param context - A contextual string describing when the check occurred (e.g., 'Post-Launch').
+     * @returns An object indicating whether errors were detected and the list of error messages.
+     */
+    private runErrorSentinel;
+}
+/**
+ * Singleton instance of the AutonomousExplorer, ready for use.
+ */
+export declare const autonomousExplorer: AutonomousExplorer;

package/dist/lib/form-filler.d.ts

@@ -0,0 +1,101 @@
+import { AndroidDriver } from './adb.js';
+import { UiNode } from './crawler.js';
+export interface TestDataPool {
+    auth?: {
+        phone?: string;
+        password?: string;
+        email?: string;
+        otp?: string;
+    };
+    profile?: {
+        name?: string;
+        firstName?: string;
+        lastName?: string;
+        phone?: string;
+        email?: string;
+        address?: string;
+        city?: string;
+        pincode?: string;
+    };
+    review?: {
+        text?: string;
+        rating?: number;
+        title?: string;
+    };
+    search?: {
+        query?: string;
+    };
+    payment?: {
+        upiId?: string;
+        card?: string;
+    };
+    [key: string]: Record<string, unknown> | string | number | boolean | undefined;
+}
+export interface FormFillResult {
+    filledFields: {
+        fieldId: string;
+        fieldLabel: string;
+        valueEntered: string;
+    }[];
+    submitted: boolean;
+    submitButtonText?: string;
+}
+/**
+ * Engine for semantically identifying and filling Android UI forms.
+ * It uses heuristics and keyword matching to map input fields to appropriate test data.
+ */
+export declare class SemanticFormFiller {
+    private testData;
+    private dataPath;
+    private isLoaded;
+    private driver;
+    /**
+     * Initializes the semantic form filler.
+     * @param customDataPath Optional absolute path to a custom test data JSON file. Defaults to test-data.json in cwd.
+     * @param driver Optional AndroidDriver instance for dependency injection. Defaults to the global androidDriver.
+     */
+    constructor(customDataPath?: string, driver?: AndroidDriver);
+    /**
+     * Directly sets the test data pool, bypassing file loading.
+     * @param data The TestDataPool object to use for form filling.
+     */
+    setTestData(data: TestDataPool): void;
+    /**
+     * Ensures that test data has been loaded from disk into memory.
+     * Does nothing if data is already loaded.
+     * @returns A promise that resolves when data is loaded (or immediately if already loaded).
+     */
+    ensureDataLoaded(): Promise<void>;
+    /**
+     * Force reloads test data from the specified path or the default path.
+     * @param customDataPath Optional new path to load test data from.
+     * @returns A promise that resolves with the loaded TestDataPool.
+     */
+    loadTestData(customDataPath?: string): Promise<TestDataPool>;
+    /**
+     * Semantically infers what value from test-data.json matches this input field.
+     * Uses field text, content description, resource ID, and nearby labels to deduce the field type.
+     *
+     * @param node The UI node representing the input field.
+     * @param allNodes The list of all UI nodes on the current screen to provide context.
+     * @returns The inferred string value to enter into the field.
+     * @throws Error if a required field type is detected but the corresponding data is missing in TestDataPool.
+     */
+    inferValueForNode(node: UiNode, allNodes: UiNode[]): string;
+    /**
+     * Detects form fields, enters values, and submits the form.
+     * Automatically clears existing content, types values, dismisses the keyboard,
+     * and attempts to find and tap a submit button.
+     *
+     * @param allNodes The list of all UI nodes on the current screen.
+     * @param serial Optional device serial number to target a specific connected device.
+     * @param autoSubmit Whether to attempt automatically finding and clicking a submit button. Defaults to true.
+     * @param overwriteExisting Whether to overwrite fields that already contain non-placeholder text. Defaults to false.
+     * @returns A promise that resolves to the FormFillResult containing details of the operation.
+     */
+    fillAndSubmitForm(allNodes: UiNode[], serial?: string, autoSubmit?: boolean, overwriteExisting?: boolean): Promise<FormFillResult>;
+}
+/**
+ * Singleton instance of the SemanticFormFiller ready for use.
+ */
+export declare const semanticFormFiller: SemanticFormFiller;

package/dist/lib/ios-driver.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @module ios-driver
+ * @description
+ * Cross-platform iOS Device Driver for PromptTest.
+ * Connects to iOS Simulators and physical devices via Apple's `xcrun simctl`,
+ * Facebook's `idb` (iOS Development Bridge), or WebDriverAgent HTTP endpoints.
+ * Implements the universal DeviceDriver interface.
+ */
+import { DeviceDriver, MobileDeviceInfo, ScreenDimensions } from './driver-interface.js';
+export interface IosDriverOptions {
+    udid?: string;
+    wdaBaseUrl?: string;
+    useMock?: boolean;
+}
+/**
+ * Controller for iOS Simulators and Devices.
+ */
+export declare class IosDriver implements DeviceDriver {
+    private defaultUdid?;
+    private wdaBaseUrl?;
+    private isMock;
+    private defaultDimensions;
+    constructor(options?: IosDriverOptions | string);
+    getDefaultDevice(): string | undefined;
+    ensureDefaultDevice(serial?: string): Promise<string>;
+    getConnectedDevices(): Promise<MobileDeviceInfo[]>;
+    getScreenDimensions(_serial?: string): Promise<ScreenDimensions>;
+    captureScreenshot(serial?: string): Promise<Buffer>;
+    getUiHierarchy(_serial?: string): Promise<string>;
+    tap(x: number, y: number, serial?: string): Promise<void>;
+    inputText(text: string, serial?: string): Promise<void>;
+    pressKey(key: string, serial?: string): Promise<void>;
+    swipe(x1: number, y1: number, x2: number, y2: number, durationMs?: number, serial?: string): Promise<void>;
+    launchApp(bundleId: string, serial?: string): Promise<void>;
+    forceStop(bundleId: string, serial?: string): Promise<void>;
+    isAppInstalled(bundleId: string, serial?: string): Promise<boolean>;
+    getForegroundPackage(_serial?: string): Promise<string | null>;
+}

package/dist/lib/live-server.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @module live-server
+ * @description
+ * Lightweight, zero-dependency HTTP and Server-Sent Events (SSE) server for PromptTest.
+ * Powers the real-time test execution monitor, allowing developers and CI observers
+ * to watch live test execution events, inspect step screenshots, and view final
+ * HTML audit reports in real time without refreshing the browser.
+ */
+import http from 'http';
+import { AuditStep, QaReportData } from './reporter.js';
+export interface LiveServerOptions {
+    /** The port number to listen on. Defaults to 4040 (or 0 for random available port). */
+    port?: number;
+    /** Host interface to bind to. Defaults to '127.0.0.1'. */
+    host?: string;
+    /** Directory where screenshots, recordings, and report artifacts are located. */
+    outputDir?: string;
+    /** Name of the test suite being executed. */
+    suiteName?: string;
+    /** Initial report data if available. */
+    initialReport?: QaReportData;
+}
+export interface LiveServerHandle {
+    /** The underlying Node.js HTTP server instance. */
+    server: http.Server;
+    /** The bound port number. */
+    port: number;
+    /** The base URL of the live server (e.g., http://localhost:4040). */
+    url: string;
+    /** Broadcasts a step completion event to all connected SSE clients. */
+    broadcastStep: (step: AuditStep) => void;
+    /** Broadcasts the final test report and updates the root HTML document. */
+    broadcastComplete: (report: QaReportData) => void;
+    /** Broadcasts an error event to connected clients. */
+    broadcastError: (errorMsg: string) => void;
+    /** Updates the cached report served at the root URL. */
+    updateReport: (report: QaReportData) => void;
+    /** Gracefully terminates the server and closes all active client connections. */
+    close: () => Promise<void>;
+}
+/**
+ * Starts a live HTTP and SSE monitoring server.
+ *
+ * @param options - Server configuration options.
+ * @returns A Promise resolving to a LiveServerHandle.
+ */
+export declare function startLiveServer(options?: LiveServerOptions): Promise<LiveServerHandle>;

package/dist/lib/lock.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Represents the state of a device lock.
+ */
+export interface DeviceLock {
+    /** The Android device serial number */
+    serial: string;
+    /** The absolute path to the lock file on the filesystem */
+    lockFilePath: string;
+    /** Whether the lock was successfully acquired */
+    acquired: boolean;
+    /** The process ID that holds the lock */
+    pid: number;
+}
+/**
+ * Acquires an exclusive file-based mutex lock for a specific Android device serial.
+ * Prevents multiple PromptTest processes from sending conflicting ADB commands to the same device.
+ * Automatically reclaims stale locks if the previous process crashed or terminated.
+ *
+ * @param serial The Android device serial number to lock.
+ * @returns A DeviceLock object representing the acquired lock.
+ * @throws {Error} If the device is currently locked by another active process.
+ * @throws {Error} If a concurrent process acquires the lock during the check-and-set window.
+ */
+export declare function acquireDeviceLock(serial: string): DeviceLock;
+/**
+ * Releases a previously acquired device lock.
+ *
+ * @param lock The DeviceLock object returned by acquireDeviceLock, or null/undefined.
+ */
+export declare function releaseDeviceLock(lock: DeviceLock | null | undefined): void;

package/dist/lib/logger.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Defines the available log severity levels.
+ * Priority increases from DEBUG to SILENT.
+ */
+export type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'SILENT';
+/**
+ * A utility class for handling formatted, level-filtered console output.
+ */
+export declare class Logger {
+    private currentLevel;
+    /**
+     * Initializes a new Logger instance.
+     * If an initialLevel is not provided, it falls back to the LOG_LEVEL environment variable,
+     * or defaults to 'INFO'.
+     *
+     * @param initialLevel An optional initial log level to override the default.
+     */
+    constructor(initialLevel?: LogLevel);
+    /**
+     * Updates the current log level threshold.
+     *
+     * @param level The new log level to apply.
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Gets the current log level threshold.
+     *
+     * @returns The currently active LogLevel.
+     */
+    getLevel(): LogLevel;
+    /**
+     * Determines if a specific log level is currently enabled based on the threshold.
+     *
+     * @param level The log level to check.
+     * @returns true if messages of this level should be output, false otherwise.
+     */
+    isLevelEnabled(level: LogLevel): boolean;
+    private isJsonMode;
+    private emitJson;
+    /**
+     * Logs a debug message to stdout. Formatted in gray or structured JSON.
+     *
+     * @param args The message or variables to log.
+     */
+    debug(...args: unknown[]): void;
+    /**
+     * Logs an informational message to stdout. No special formatting applied or structured JSON.
+     *
+     * @param args The message or variables to log.
+     */
+    info(...args: unknown[]): void;
+    /**
+     * Logs a warning message to stderr. Formatted in yellow or structured JSON.
+     *
+     * @param args The message or variables to log.
+     */
+    warn(...args: unknown[]): void;
+    /**
+     * Logs an error message to stderr. Formatted in red or structured JSON.
+     *
+     * @param args The message or variables to log.
+     */
+    error(...args: unknown[]): void;
+}
+/**
+ * A globally accessible singleton instance of Logger for use throughout the PromptTest codebase.
+ */
+export declare const logger: Logger;