prompttest-mobile 1.5.1

package/dist/lib/prompt-runner.d.ts

@@ -0,0 +1,101 @@
+import { AndroidDriver } from './adb.js';
+import { QaReportData, Reporter } from './reporter.js';
+import { MemoryEngine } from './memory.js';
+import { CheckpointManager } from './checkpoint.js';
+import { BaselineManager } from './baseline.js';
+import { SemanticResolver } from './ai/index.js';
+import { type PromptStep, type PromptStepType, type RunOptions } from './runner-utils.js';
+export type { PromptStep, PromptStepType, RunOptions };
+/**
+ * Core engine responsible for parsing test specs and coordinating execution
+ * on an Android device using the provided driver and services.
+ */
+export declare class PromptRunner {
+    private driver;
+    private memory;
+    private reporter;
+    private checkpoints;
+    private baselines;
+    private lastHierarchy;
+    private screenDimensions;
+    private navBarHeight;
+    private targetPackage;
+    /**
+     * Initializes a new instance of the PromptRunner.
+     * Uses dependency injection for core services, defaulting to singletons if omitted.
+     *
+     * @param driver - The Android ADB driver for device communication.
+     * @param memory - The memory engine for storing and retrieving learned locators.
+     * @param reporter - The reporting engine for test results.
+     * @param checkpoints - Manager for test step checkpoints and resuming.
+     * @param baselines - Manager for visual baseline testing.
+     */
+    constructor(driver?: AndroidDriver, memory?: MemoryEngine, reporter?: Reporter, checkpoints?: CheckpointManager, baselines?: BaselineManager, semanticResolver?: SemanticResolver);
+    private semanticResolver;
+    private healEnabled;
+    private activeLocale;
+    private runtimeVariables;
+    private loopStack;
+    /**
+     * Recursively expands `INCLUDE '<path>'` directives within a spec file.
+     * Resolves paths relative to current spec directory and guards against circular recursion.
+     *
+     * @param specFilePath - Path to the root spec file.
+     * @param visitedFiles - Set of visited absolute file paths in the recursion stack.
+     * @returns The fully expanded spec string.
+     * @throws SpecRecursionError if circular spec inclusion is detected.
+     */
+    expandSpecIncludes(specFilePath: string, visitedFiles?: Set<string>): string;
+    /**
+     * Expands high-level macro steps in a test spec into concrete primitive actions.
+     *
+     * @param specText - Original spec text containing potential high-level intents.
+     * @param resolver - Optional custom semantic resolver.
+     * @returns The expanded specification string and count of expanded steps.
+     */
+    expandSpec(specText: string, resolver?: SemanticResolver): Promise<{
+        expanded: string;
+        stepsAdded: number;
+    }>;
+    /**
+     * Parses a multi-line, plain-English test specification into a structured array of actionable steps.
+     * Understands variable interpolation, optional steps, flow control blocks (IF, LOOP), and all action types.
+     *
+     * @param promptText - The raw plain-English spec to parse.
+     * @param customVars - Optional key-value pairs for string interpolation.
+     * @returns An array of parsed PromptStep objects structured into an execution AST.
+     */
+    parsePrompt(promptText: string, customVars?: Record<string, string>): PromptStep[];
+    /**
+     * Executes a plain-English test spec against the connected Android device.
+     * Handles device locking, memory loading, sequential execution, checkpointing,
+     * error recovery, and final report generation.
+     *
+     * @param specFilePath - The absolute or relative path to the plain-English spec file.
+     * @param pkgOrOptions - The target app package name (legacy) or a RunOptions configuration object.
+     * @param legacySerial - The target device serial number (legacy support).
+     * @returns A promise that resolves to the final QA report data upon completion or failure.
+     * @throws Error if the spec file does not exist.
+     */
+    runSpec(specFilePath: string, pkgOrOptions?: string | RunOptions, legacySerial?: string): Promise<QaReportData>;
+    private getCleanHierarchy;
+    /**
+     * Expectation-driven dynamic polling: waits for an element matching target to appear on screen.
+     * Proceeds as soon as the element exists without waiting for blind static sleeps.
+     */
+    private ensureInViewport;
+    private waitForTarget;
+    private buildDiagnosticError;
+    executeStep(step: PromptStep, serial?: string, upcomingSteps?: PromptStep[]): Promise<{
+        fastForwarded?: boolean;
+        reason?: string;
+        skipCount?: number;
+    } | void>;
+    private findTargetInputField;
+    private matchNodes;
+}
+/**
+ * A singleton instance of the PromptRunner.
+ * Pre-configured with default dependencies for convenient global usage across the framework.
+ */
+export declare const promptRunner: PromptRunner;

package/dist/lib/quiescence.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @module quiescence
+ * @description Dynamic Screen Quiescence & Idling Sentinel for PromptTest.
+ *
+ * Implements self-synchronizing stability detection inspired by Playwright's networkidle
+ * and Android Espresso's IdlingResource. Replaces fragile static timers with dual-sample
+ * layout stabilization and active in-flight loading sentinel checks.
+ */
+import type { UiNode } from './crawler.js';
+import type { ExecutionContext } from './step-handlers.js';
+export interface QuiescenceResult {
+    /** Whether the screen reached verified stability before the timeout */
+    settled: boolean;
+    /** Milliseconds elapsed during stabilization */
+    durationMs: number;
+    /** Final structural hash of the quiescent screen */
+    finalHash: string;
+    /** Flattened UI nodes of the quiescent screen */
+    flat: UiNode[];
+}
+/**
+ * Inspects a flattened UI hierarchy to detect active in-flight network spinners,
+ * shimmers, progress bars, or server-waiting indicators.
+ *
+ * @param nodes - Flattened array of UiNodes
+ * @returns Status indicating whether loading is in progress and why.
+ */
+export declare function isLoadingInProgress(nodes: UiNode[]): {
+    loading: boolean;
+    reason?: string;
+};
+/**
+ * Dynamically waits until the application screen achieves 100% quiescence:
+ * 1. All active loading indicators and spinners have vanished.
+ * 2. Two consecutive UI hierarchy snapshots yield matching structural hashes.
+ *
+ * Exits immediately once settled, saving seconds on fast devices while providing
+ * dynamic patience for slow network requests or cloud emulators.
+ *
+ * @param ctx - Execution context providing driver and hierarchy access.
+ * @param timeoutMs - Maximum wait ceiling (defaults to 4500ms).
+ * @param sampleIntervalMs - Interval between stability probe samples (defaults to 150ms).
+ */
+export declare function waitForQuiescence(ctx: ExecutionContext, timeoutMs?: number, sampleIntervalMs?: number): Promise<QuiescenceResult>;

package/dist/lib/recorder.d.ts

@@ -0,0 +1,155 @@
+import { AndroidDriver } from './adb.js';
+/**
+ * Configuration options for the recording session.
+ */
+export interface RecordOptions {
+    /**
+     * If true, the recorder will append new captured steps to the existing test spec file
+     * rather than overwriting or creating a new file.
+     */
+    append?: boolean;
+}
+/**
+ * Represents a discrete user interaction event captured during the session.
+ */
+export interface RecordedEvent {
+    /** The generated plain-English instruction for this event. */
+    stepText: string;
+    /** The exact epoch timestamp (in milliseconds) when this event occurred. */
+    timestamp: number;
+}
+/**
+ * The core engine that listens to device input and transforms raw interaction telemetry
+ * into semantic PromptTest step instructions.
+ */
+export declare class AutonomousRecorder {
+    onStep?: (step: string) => void;
+    private driver;
+    private deviceLock;
+    private isRecording;
+    private recordedSteps;
+    private existingSteps;
+    private existingFileHeader;
+    private lastHierarchyFlat;
+    private lastScreenTitle;
+    private visitedScreens;
+    private targetPackage;
+    private isAppendMode;
+    private resolvedOutputPath;
+    private resolvedReportPath;
+    private activeInput;
+    private geteventProcess;
+    private isRefreshingHierarchy;
+    private targetSerial;
+    private touchMaxX;
+    private touchMaxY;
+    private displayWidth;
+    private displayHeight;
+    private activeTouchX;
+    private activeTouchY;
+    private touchDownTime;
+    private isTouchActive;
+    private isSwipeGesture;
+    private lastHierarchyTimestamp;
+    private lastTapTimestamp;
+    private lastRecordedTapTarget;
+    private inFlightTapQueue;
+    private inputDebounceTimer;
+    private logcatEventProcess;
+    private logcatCrashProcess;
+    private hierarchyCacheTime;
+    private hierarchyStale;
+    private lastScrollTimestamp;
+    private lastScrollDirection;
+    private currentScreenName;
+    private sessionScreenSections;
+    private sessionStartTime;
+    private screenshotDir;
+    private screenshotCounter;
+    private crashDetected;
+    private lastScreenTransitionTime;
+    /**
+     * Initializes a new AutonomousRecorder.
+     * @param driver An optional AndroidDriver instance to use. If omitted, the default singleton is used.
+     */
+    constructor(driver?: AndroidDriver);
+    /**
+     * Flushes recorded steps and markdown summary report immediately to disk.
+     * Ensures captured steps are never lost even if process terminates unexpectedly.
+     */
+    private flushToDisk;
+    /**
+     * Records a new test step, auto-flushes to disk immediately, and outputs to console.
+     */
+    private appendStep;
+    private extractBrandSlug;
+    /**
+     * Starts an interactive real-time recording session on the target Android device.
+     * Automatically detects the active app, starts capturing gestures and key events,
+     * monitors screen transitions, and writes out a plain-text spec.
+     *
+     * @param outputSpecPath Optional file path to save the generated test spec to.
+     * @param serial Optional serial number of the target device to record from.
+     * @param options Additional recording configuration options.
+     * @returns A promise that resolves when the recording session concludes.
+     */
+    /**
+     * Starts a non-blocking recording session (used by both CLI and Live Server).
+     */
+    startSession(outputSpecPath?: string, serial?: string, options?: RecordOptions): Promise<void>;
+    /**
+     * Stops an active recording session, terminates background processes,
+     * releases device lock, and returns the recorded steps and file paths.
+     */
+    stopSession(): Promise<{
+        steps: string[];
+        specPath: string;
+        reportPath: string;
+    }>;
+    /**
+     * Starts an interactive real-time recording session on the target Android device.
+     * Automatically detects the active app, starts capturing gestures and key events,
+     * monitors screen transitions, and writes out a plain-text spec.
+     *
+     * @param outputSpecPath Optional file path to save the generated test spec to.
+     * @param serial Optional serial number of the target device to record from.
+     * @param options Additional recording configuration options.
+     * @returns A promise that resolves when the recording session concludes.
+     */
+    startRecording(outputSpecPath?: string, serial?: string, options?: RecordOptions): Promise<void>;
+    private startEventStream;
+    private cleanLabel;
+    private handleScroll;
+    private handleSwipe;
+    private handleLongPressAt;
+    private handleTapAt;
+    private handleKeyPress;
+    private scheduleInputDebounce;
+    private flushActiveInput;
+    private syncActiveInputText;
+    private recordInputText;
+    private startLogcatScreenWatcher;
+    private startLogcatCrashWatcher;
+    private captureSessionScreenshot;
+    private triggerAsyncHierarchyRefresh;
+    private doHierarchyRefresh;
+    private detectAndLogTransientAlerts;
+    private refreshHierarchySync;
+    private isIconGlyph;
+    private cleanDialogOrCompoundLabel;
+    private isCardMetadataSubtitle;
+    private findPrimaryCardTitle;
+    private resolveActionLabel;
+    private getCurrentStepNumber;
+    private detectAndLogScreenHeader;
+    private resolveFieldLabel;
+    private isPlaceholderText;
+    private saveSpec;
+    private saveReport;
+    private printExitSummary;
+}
+/**
+ * Pre-instantiated global singleton instance of the AutonomousRecorder.
+ * Use this for starting recording sessions without managing class instances manually.
+ */
+export declare const autonomousRecorder: AutonomousRecorder;

package/dist/lib/repl.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module repl
+ * @description
+ * Interactive Live REPL (Playground) for PromptTest.
+ * Allows developers and QA engineers to drive connected Android devices interactively
+ * in real time using plain-English instructions with instant latency feedback, UI inspection,
+ * screenshot capturing, and spec file export.
+ */
+import { AndroidDriver } from './adb.js';
+import { PromptRunner } from './prompt-runner.js';
+export interface ReplOptions {
+    serial?: string;
+    packageName?: string;
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+}
+export interface ReplSession {
+    history: string[];
+    successfulSteps: string[];
+}
+/**
+ * Starts the interactive PromptTest live REPL session.
+ *
+ * @param driver - The AndroidDriver instance to communicate with the device.
+ * @param runner - The PromptRunner instance to execute steps.
+ * @param options - Configuration options for the REPL session.
+ * @returns Promise that resolves when the REPL session exits.
+ */
+export declare function startRepl(driver?: AndroidDriver, runner?: PromptRunner, options?: ReplOptions): Promise<ReplSession>;

package/dist/lib/reporter.d.ts

@@ -0,0 +1,269 @@
+/**
+ * PromptTest Reporting Engine
+ *
+ * This module serves as the test audit and reporting engine for PromptTest.
+ * It records step data, computes test execution metrics, and generates
+ * comprehensive reports in multiple formats including JSON, Markdown, and
+ * JUnit XML. It plays a critical role in providing observability and
+ * traceability for autonomous test executions.
+ */
+import type { PerformanceReport } from './profiler.js';
+/**
+ * Represents a single executed step or action during the test run.
+ */
+export interface AuditStep {
+    /** The sequential 1-based index of this step in the test run. */
+    stepIndex: number;
+    /** ISO 8601 timestamp of when the step was executed. */
+    timestamp: string;
+    /** The high-level test phase (e.g., 'Setup', 'Navigation', 'Assertion'). */
+    phase: string;
+    /** A human-readable description of what the step attempts to do. */
+    description: string;
+    /** The specific technical action taken (e.g., 'click', 'input', 'assert'). */
+    action: string;
+    /** The UI element or component targeted by this action, if any. */
+    target?: string;
+    /** The outcome of the step execution. */
+    status: 'PASS' | 'WARN' | 'FAIL' | 'SKIPPED';
+    /** Local file path or relative URL to the screenshot taken during this step, if any. */
+    screenshotPath?: string;
+    /** Elapsed execution time for this step in milliseconds. */
+    durationMs?: number;
+    /** Relative path to the failure triage bundle directory if step failed. */
+    triageBundle?: string;
+    /** Relative execution offset in milliseconds from start of run / video recording. */
+    videoOffsetMs?: number;
+    /** Additional diagnostic data or context about the step. */
+    details?: Record<string, unknown>;
+}
+/**
+ * Contains the aggregated data and metrics for a completed test run.
+ */
+export interface QaReportData {
+    /** The Android package name of the tested application. */
+    packageName: string;
+    /** The identifier of the device used for the test execution. */
+    deviceId: string;
+    /** ISO 8601 timestamp marking the start of the test run. */
+    startTime: string;
+    /** ISO 8601 timestamp marking the end of the test run. */
+    endTime: string;
+    /** Total duration of the test execution in seconds. */
+    durationSeconds: number;
+    /** The total number of steps executed during the run. */
+    totalSteps: number;
+    /** The number of steps that completed successfully. */
+    passedSteps: number;
+    /** The number of steps that failed. */
+    failedSteps: number;
+    /** The number of steps that were skipped. */
+    skippedSteps: number;
+    /** The number of steps that completed with warnings. */
+    warnSteps: number;
+    /** A list of critical error messages or sentinels detected during the run. */
+    errorsDetected: string[];
+    /** Optional relative path to screen recording video (MP4). */
+    videoPath?: string;
+    /** Optional performance profiler metrics (PF-01). */
+    performanceMetrics?: PerformanceReport;
+    /** Details of any locators auto-healed during the test run */
+    healsApplied?: Array<{
+        original: string;
+        healed: string;
+        stepNumber: number;
+    }>;
+    /** The chronological list of all audit steps executed. */
+    steps: AuditStep[];
+}
+/** Supported output report serialization formats. */
+export type ReportFormat = 'json' | 'md' | 'junit' | 'html';
+/**
+ * Options for configuring the QaReporter.
+ */
+export interface QaReporterOptions {
+    /** Directory where reports and artifacts are saved. */
+    outputDir?: string;
+    /** List of report formats to generate ('json', 'md', 'junit', 'html'). */
+    formats?: ReportFormat[];
+    /** Whether to embed screenshots directly into the HTML report as base64 data URIs. */
+    embedScreenshots?: boolean;
+}
+export type StepListener = (step: AuditStep) => void;
+export type CompleteListener = (report: QaReportData) => void;
+export type ErrorListener = (errorMsg: string) => void;
+/**
+ * Pluggable reporter interface (A-02).
+ * Implement this to add Slack, TestRail, Allure, or any custom sink.
+ * Pass an instance via `RunOptions.reporter` or the `--reporter` CLI flag.
+ */
+export interface Reporter {
+    /**
+     * Initializes the reporter for a new test run.
+     *
+     * @param packageName - The target app package name.
+     * @param deviceId - The ID of the target device.
+     */
+    init(packageName: string, deviceId: string): void;
+    /**
+     * Records a new step in the test run.
+     */
+    logStep(phase: string, description: string, action: string, status: 'PASS' | 'WARN' | 'FAIL' | 'SKIPPED', target?: string, screenshotBuffer?: Buffer, details?: Record<string, unknown>, durationMs?: number, triageBundle?: string): AuditStep;
+    /**
+     * Logs a critical error or anomaly detected during the run.
+     */
+    logError(errorMsg: string): void;
+    /**
+     * Attaches a video recording path to the report.
+     */
+    setVideoPath?(videoPath: string): void;
+    /**
+     * Sets whether screenshots should be embedded as base64 in HTML reports.
+     */
+    setEmbedScreenshots?(embed: boolean): void;
+    /**
+     * Sets active report formats.
+     */
+    setFormats?(formats: ReportFormat[]): void;
+    /**
+     * Subscribes to real-time step audit events.
+     */
+    onStep?(listener: StepListener): () => void;
+    /**
+     * Subscribes to test suite completion events.
+     */
+    onComplete?(listener: CompleteListener): () => void;
+    /**
+     * Subscribes to critical error events.
+     */
+    onError?(listener: ErrorListener): () => void;
+    /**
+     * Finalizes the execution and generates the final test reports.
+     */
+    generateReport(customFileName?: string): Promise<QaReportData>;
+}
+/**
+ * Default implementation of the Reporter interface.
+ * Generates local JSON, Markdown, and JUnit XML report files.
+ */
+export declare class QaReporter implements Reporter {
+    private outputDir;
+    private steps;
+    private errorsDetected;
+    private startTime;
+    private packageName;
+    private deviceId;
+    private pendingWrites;
+    private formats;
+    private videoPath?;
+    private embedScreenshots;
+    private performanceMetrics?;
+    private screenshotBuffers;
+    private stepListeners;
+    private completeListeners;
+    private errorListeners;
+    /**
+     * Sets the performance metrics collected by the profiler.
+     */
+    setPerformanceMetrics(metrics: PerformanceReport): void;
+    /**
+     * Constructs a new QaReporter.
+     *
+     * @param outputDirOrOptions - Optional path or QaReporterOptions configuration object.
+     * @param formats - Optional array of desired output report formats ('json', 'md', 'junit', 'html').
+     */
+    constructor(outputDirOrOptions?: string | QaReporterOptions, formats?: ReportFormat[]);
+    /**
+     * Enables or disables base64 screenshot embedding in HTML reports.
+     */
+    setEmbedScreenshots(embed: boolean): void;
+    /**
+     * Subscribes a listener to individual step execution events.
+     * Returns an unsubscribe function.
+     */
+    onStep(listener: StepListener): () => void;
+    /**
+     * Subscribes a listener to run completion events.
+     * Returns an unsubscribe function.
+     */
+    onComplete(listener: CompleteListener): () => void;
+    /**
+     * Subscribes a listener to error events.
+     * Returns an unsubscribe function.
+     */
+    onError(listener: ErrorListener): () => void;
+    /**
+     * Sets the desired output report formats.
+     */
+    setFormats(formats: ReportFormat[]): void;
+    /**
+     * Attaches a video recording path to the report.
+     */
+    setVideoPath(videoPath: string): void;
+    /**
+     * Initializes the reporter for a new test run, resetting all internal state.
+     *
+     * @param packageName - The target app package name.
+     * @param deviceId - The ID of the target device.
+     */
+    init(packageName: string, deviceId: string): void;
+    /**
+     * Releases in-memory screenshot buffers to bound process memory ceiling.
+     */
+    clearScreenshotBuffers(): void;
+    /**
+     * Records a new step in the test run and triggers background screenshot writing if provided.
+     *
+     * @param phase - The test phase of this step.
+     * @param description - Human-readable description of the step.
+     * @param action - The specific action taken.
+     * @param status - The execution status of the step.
+     * @param target - Optional target element identifier.
+     * @param screenshotBuffer - Optional image buffer of the screen state.
+     * @param details - Optional extra context data.
+     * @param durationMs - Optional elapsed execution time in milliseconds.
+     * @param triageBundle - Optional relative path to failure triage directory.
+     * @returns The generated AuditStep object.
+     */
+    logStep(phase: string, description: string, action: string, status: 'PASS' | 'WARN' | 'FAIL' | 'SKIPPED', target?: string, screenshotBuffer?: Buffer, details?: Record<string, unknown>, durationMs?: number, triageBundle?: string): AuditStep;
+    /**
+     * Logs a critical error or anomaly detected during the run.
+     *
+     * @param errorMsg - The error message to log.
+     */
+    logError(errorMsg: string): void;
+    /**
+     * Finalizes the execution, waits for pending I/O, and generates the requested test reports.
+     *
+     * @param customFileName - Optional base name for the report files.
+     * @returns A Promise resolving to the aggregated report data.
+     */
+    generateReport(customFileName?: string): Promise<QaReportData>;
+    private escapeXml;
+    private escapeHtml;
+    private formatJunitXml;
+    private formatMarkdownReport;
+    private resolveScreenshotData;
+    private formatHtmlReport;
+}
+/**
+ * Generates an interactive, standalone HTML report string from QaReportData.
+ *
+ * Features:
+ * - Executive dashboard with circular pass-rate gauge and summary metrics cards.
+ * - Live real-time search and status category filters.
+ * - Full-screen interactive Lightbox modal with zoom, previous/next, and keyboard navigation.
+ * - Visual baseline diff viewer for visual regression test steps.
+ * - Failure triage bundle explorer with direct links to artifacts.
+ * - Server-Sent Events (SSE) live monitoring integration when served over HTTP.
+ */
+export declare function generateHtmlReport(data: QaReportData, options?: {
+    suiteName?: string;
+    embedScreenshots?: boolean;
+    screenshotResolver?: (step: AuditStep) => string | undefined;
+}): string;
+/**
+ * A singleton instance of QaReporter provided for convenience.
+ * Can be used throughout the test execution for simplified reporting.
+ */
+export declare const qaReporter: QaReporter;