prompttest 1.3.0

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,253 @@
+/**
+ * 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.
+ */
+/**
+ * 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;
+    /** 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;
+    /** 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 screenshotBuffers;
+    private stepListeners;
+    private completeListeners;
+    private errorListeners;
+    /**
+     * 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;

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

@@ -0,0 +1,290 @@
+/**
+ * @module runner-utils
+ * @description
+ * Modular helper utilities for PromptTest runner orchestration.
+ * Encapsulates spec inclusion expansion, natural language prompt parsing,
+ * AST block hierarchy assembly, fuzzy/spatial/ordinal node matching,
+ * and diagnostic error generation.
+ */
+import { UiNode } from './crawler.js';
+import { MemoryEngine } from './memory.js';
+import type { QaReportData, Reporter, ReportFormat } from './reporter.js';
+/**
+ * Valid action and flow control verbs supported by PromptTest.
+ */
+export type PromptStepType = 'TAP' | 'LONG_PRESS' | 'TYPE' | 'CLEAR' | 'VERIFY' | 'BACK' | 'SCROLL' | 'SWIPE' | 'TOGGLE' | 'SELECT' | 'LAUNCH_APP' | 'RESTART_APP' | 'TERMINATE_APP' | 'CLEAR_DATA' | 'GRANT_PERMISSION' | 'DEEP_LINK' | 'WAIT' | 'IF_VISIBLE' | 'LOOP' | 'WAIT_UNTIL' | 'SET_VARIABLE' | 'DEVICE_STATE' | 'RUN_JS' | 'ENTER_OTP' | 'API_REQUEST' | 'EMAIL_ASSERT';
+/**
+ * Configuration options for executing a test specification.
+ */
+export interface RunOptions {
+    /** The target Android application package name. */
+    packageName?: string;
+    /** The serial number of the target Android device/emulator. */
+    serial?: string;
+    /** Policy for when to capture screenshots. */
+    screenshotMode?: 'on-failure' | 'all';
+    /** If true, execution proceeds even after a non-optional step fails. */
+    continueOnError?: boolean;
+    /** If true, clears app data before running the spec. */
+    fresh?: boolean;
+    /** Local path to the APK if installation is needed. */
+    apkPath?: string;
+    /** Variables for interpolation within the spec text. */
+    variables?: Record<string, string>;
+    /** Resume from last checkpoint if one exists for this spec. */
+    resume?: boolean;
+    /** Save a screenshot baseline after every passing step. */
+    saveBaseline?: boolean;
+    /** Compare screenshots against saved baselines on every step. */
+    compareBaseline?: boolean;
+    /** Visual diff threshold (0–1). Defaults to 0.02 (2%). */
+    baselineThreshold?: number;
+    /** If true, records screen to an MP4 video during spec execution. */
+    video?: boolean;
+    /** Specific report formats to emit ('json', 'md', 'junit', 'html'). */
+    reporters?: ReportFormat[];
+    /** Custom reporter instance (A-02). Defaults to the built-in QaReporter. */
+    reporter?: Reporter;
+    /** Enable automatic locator self-healing on failure. */
+    heal?: boolean;
+    /** Disable AI resolution (force pure heuristic mode). */
+    noAi?: boolean;
+    /** Path to external CSV or JSON dataset for data-driven testing. */
+    dataFile?: string;
+    /** Total number of data-driven iterations to execute. */
+    iterations?: number;
+    /** Execute only a specific 1-indexed data row from dataset. */
+    onlyRow?: number;
+    /** Active language/locale for UI taxonomy and matching (e.g. 'en', 'es', 'hi'). */
+    locale?: string;
+    /** Whether to inline screenshots as base64 in the generated HTML report. */
+    embedScreenshots?: boolean;
+    /** Start a live streaming monitor HTTP server (boolean or port number). */
+    serve?: boolean | number;
+    /** Enable benchmark mode to output and log per-step latency metrics. */
+    benchmark?: boolean;
+    /** Dry-run parse and validate spec without device interaction. */
+    dryRun?: boolean;
+    /** Print parsed steps table and exit without executing. */
+    listSteps?: boolean;
+    /** Filter execution to specific step indices or ranges (e.g. '1-3,5'). */
+    only?: string;
+    /** Filter execution to specs matching specific tags (e.g. 'smoke'). */
+    tags?: string;
+    /** Emit machine-readable JSON execution summary to stdout. */
+    json?: boolean;
+}
+/**
+ * Represents a single parsed action step in a plain-English test spec.
+ */
+export interface PromptStep {
+    /** The original unparsed text from the spec file. */
+    originalText: string;
+    /** The action type resolved from the text. */
+    type: PromptStepType;
+    /** The primary target node or element text to interact with. */
+    target?: string;
+    /** The value to input or select (e.g., text to type). */
+    value?: string;
+    /** Wait duration in milliseconds (used for WAIT steps). */
+    durationMs?: number;
+    /** Direction for swipe or scroll steps. */
+    direction?: 'left' | 'right' | 'up' | 'down';
+    /** The desired boolean state (e.g., for toggles or checkboxes). */
+    desiredState?: boolean;
+    /** Ordinal indicator for differentiating multiple matching targets. */
+    ordinal?: '1st' | '2nd' | '3rd' | '4th' | '5th' | 'first' | 'last';
+    /** Text of another element this target is relative to (spatial matching). */
+    relativeTo?: string;
+    /** The expected state of the target (e.g., 'visible', 'exists', 'absent', 'hidden') for verifications. */
+    expectedState?: 'visible' | 'exists' | 'enabled' | 'disabled' | 'absent' | 'hidden';
+    /** If true, asserts that the target element is NOT present. */
+    negative?: boolean;
+    /** If true, the test will not fail if this step fails. */
+    optional?: boolean;
+    /** Target text or locator checked by conditional statements (IF_VISIBLE). */
+    conditionTarget?: string;
+    /** Steps executed when a condition evaluates to true. */
+    thenSteps?: PromptStep[];
+    /** Steps executed when a condition evaluates to false. */
+    elseSteps?: PromptStep[];
+    /** Steps executed repeatedly inside a loop. */
+    childSteps?: PromptStep[];
+    /** Total iterations for fixed-count loops. */
+    loopCount?: number;
+    /** Name of variable populated during iterations (e.g. for-each). */
+    loopVariable?: string;
+    /** Variable identifier set during SET_VARIABLE actions. */
+    variableName?: string;
+    /** Expression or literal string assigned to a variable. */
+    variableExpression?: string;
+    /** Hardware or connectivity state toggled (DEVICE_STATE). */
+    deviceAction?: 'wifi' | 'airplane' | 'orientation' | 'notifications';
+    /** Target state value ('on', 'off', 'portrait', 'landscape', etc.). */
+    deviceStateValue?: string | boolean;
+    /** Sandboxed JavaScript code snippet (RUN_JS). */
+    jsCode?: string;
+    /** Tracked source file and line number for modular spec reporting. */
+    sourceLocation?: {
+        file: string;
+        line: number;
+    };
+    /** API HTTP Method (GET, POST, etc.) */
+    apiMethod?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** API endpoint URL */
+    apiUrl?: string;
+    /** Request body JSON string */
+    apiBody?: string;
+    /** JSON response path to extract into a variable */
+    apiStorePath?: string;
+    /** Variable identifier to store API response value */
+    apiStoreVariable?: string;
+    /** Expected HTTP response status code */
+    apiExpectedStatus?: number;
+    /** Recipient email address for email assertions */
+    emailRecipient?: string;
+    /** Expected email subject line */
+    emailSubject?: string;
+    /** Expected substring inside email body */
+    emailBodyContains?: string;
+    /** Healed locator provenance (original target string) */
+    healedFrom?: string;
+}
+/**
+ * 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.
+ */
+export declare function expandSpecIncludes(specFilePath: string, visitedFiles?: Set<string>): string;
+/**
+ * Assembles a flat list of parsed prompt steps into a hierarchical execution AST.
+ * Scopes IF_VISIBLE blocks with thenSteps and elseSteps, and LOOP blocks with childSteps.
+ */
+export declare function assembleAstBlocks(flatSteps: Array<PromptStep & {
+    _isControl?: 'ELSE' | 'END';
+}>): PromptStep[];
+/**
+ * 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.
+ */
+export declare function parsePrompt(promptText: string, customVars?: Record<string, string>): PromptStep[];
+/**
+ * Generates an error message augmented with actionable suggestions of closest visible nodes.
+ */
+export declare function buildDiagnosticError(target: string, flat: UiNode[], context: string): Error;
+/**
+ * Heuristically finds the most relevant EditText input field for a given target label or intent.
+ */
+export declare function findTargetInputField(nodes: UiNode[], target: string, value?: string, memory?: MemoryEngine): UiNode | null;
+/**
+ * Matches UI nodes against a query string using exact matching, memory, self-healing, spatial, and ordinal rules.
+ */
+export declare function matchNodes(nodes: UiNode[], query: string, memory: MemoryEngine, activeLocale?: string, step?: PromptStep, screenHash?: string): UiNode[];
+/**
+ * Result of comparing two UI hierarchy snapshots.
+ */
+export interface HierarchyDiff {
+    /** True if the structural content or visible element count changed */
+    hasChanged: boolean;
+    /** Previous hierarchy fingerprint hash */
+    previousHash: string;
+    /** Current hierarchy fingerprint hash */
+    currentHash: string;
+    /** Difference in total node count */
+    nodeCountDelta: number;
+}
+/**
+ * Computes a fast 32-bit FNV-1a polynomial hash of a flattened UI node hierarchy.
+ * Encodes text, contentDesc, resourceId, and spatial coordinates to detect screen shifts.
+ *
+ * @param nodes - Flattened array of UiNode elements.
+ * @returns Hexadecimal fingerprint string.
+ */
+export declare function computeHierarchyHash(nodes: UiNode[]): string;
+/**
+ * Patterns matching volatile real-time data that changes without representing a new screen state:
+ * - Timestamps and clocks (e.g. "10:45 AM", "12:00:30", "14:30")
+ * - Relative time spans (e.g. "2 mins ago", "yesterday", "3 days ago")
+ * - Currency and price figures (e.g. "$14.99", "₹500", "€10.00")
+ * - Dynamic booking / order / serial IDs (e.g. "#ORD-12345", "ID: 981723")
+ * - Battery percentage and status bars (e.g. "85%", "100%")
+ */
+export declare const VOLATILE_DATA_PATTERNS: readonly RegExp[];
+/**
+ * Normalizes a text string by stripping volatile dynamic data (clocks, timestamps, prices, IDs).
+ *
+ * @param text - Raw element text or content description.
+ * @returns Canonicalized stable string.
+ */
+export declare function normalizeSemanticText(text: string): string;
+/**
+ * Computes a canonical semantic hash representing the structural route and layout of a screen,
+ * immune to volatile data (clock ticks, prices, dynamic order IDs, or minor status bar changes).
+ *
+ * @param nodes - Array of UI nodes representing the screen.
+ * @param screenDims - Optional screen dimensions to exclude system status bar.
+ * @returns Stable hexadecimal fingerprint.
+ */
+export declare function computeCanonicalSemanticHash(nodes: UiNode[], screenDims?: {
+    width: number;
+    height: number;
+}): string;
+/**
+ * Compares two sets of UI hierarchy nodes to determine whether a meaningful screen transition occurred.
+ *
+ * @param previousNodes - The earlier hierarchy snapshot.
+ * @param currentNodes - The newly retrieved hierarchy snapshot.
+ * @returns HierarchyDiff analysis.
+ */
+export declare function compareHierarchyNodes(previousNodes: UiNode[], currentNodes: UiNode[]): HierarchyDiff;
+/**
+ * Parses a comma-separated step index range string (e.g., "1-3,5,8-10") into a set of 1-based step numbers.
+ *
+ * @param rangeStr - Raw range string provided via `--only`.
+ * @returns Set of 1-based step indices.
+ */
+export declare function parseStepRange(rangeStr: string): Set<number>;
+/**
+ * Extracts metadata tags from comments in a test specification file.
+ * Supports patterns like `# @tags: smoke, auth`, `# @tag smoke`, and `# @smoke`.
+ *
+ * @param specContent - Raw text content of the spec file.
+ * @returns Array of unique lowercase tag strings.
+ */
+export declare function extractSpecTags(specContent: string): string[];
+/**
+ * Renders a structured CLI table listing all parsed PromptStep objects.
+ * Used by the `--list-steps` CLI flag.
+ *
+ * @param steps - Array of parsed PromptStep objects.
+ * @returns Multi-line formatted ASCII table string.
+ */
+export declare function formatStepTable(steps: PromptStep[]): string;
+/**
+ * Creates a synthetic QaReportData object for early-exit execution modes like dry-run, list-steps, or skipped specs.
+ *
+ * @param packageName - Target package identifier.
+ * @param deviceId - Active device identifier.
+ * @param steps - Array of PromptSteps to include in report.
+ * @param stepStatus - Status to assign to each step ('PASS' | 'SKIPPED').
+ * @param phaseName - High-level phase name.
+ * @returns Fully formed QaReportData.
+ */
+export declare function createSyntheticReport(packageName: string, deviceId: string, steps?: PromptStep[], stepStatus?: 'PASS' | 'SKIPPED', phaseName?: string): QaReportData;
+/**
+ * Automatically masks sensitive input values (passwords, PINs, auth tokens, API keys)
+ * for safe logging and report generation.
+ *
+ * @param value - The input text value to check.
+ * @param target - The element target label or description.
+ * @returns Sanitized or masked string.
+ */
+export declare function maskSensitiveValue(value: string, target?: string): string;