prompttest-mobile 1.5.1

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

@@ -0,0 +1,316 @@
+/**
+ * @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 { AndroidDriver } from './adb.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;
+    /** Real-time mobile performance & FPS profiler (PF-01). */
+    profile?: 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;
+    /** Healed replacement string chosen by self-healing */
+    healedTo?: 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;
+export interface FailureTriageParams {
+    outputDir: string;
+    specName: string;
+    currentSpecName: string;
+    stepNum: number;
+    step: PromptStep;
+    error: Error;
+    stepStartTime: number;
+    startTime: number;
+    errorShot?: Buffer;
+    lastHierarchy?: {
+        xml?: string;
+        flat?: UiNode[];
+    } | null;
+    driver: AndroidDriver;
+    serial?: string;
+}
+/**
+ * Assembles failure triage folder, logs, hierarchy XML, match scores, and a ZIP archive.
+ */
+export declare function createFailureTriageBundle(params: FailureTriageParams): Promise<string | undefined>;

package/dist/lib/scaffold.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @module scaffold
+ * @description
+ * Inspects an active Android screen (or raw XML hierarchy) and synthesizes
+ * a starter plain-English test spec (.txt) containing Launch, Wait, form Type,
+ * button Tap, and element Verify steps.
+ */
+import { AndroidDriver } from './adb.js';
+import { UiNode } from './crawler.js';
+export interface ScaffoldOptions {
+    /** Target package to scaffold. Defaults to active foreground app */
+    packageName?: string;
+    /** Specific device serial to connect to */
+    deviceSerial?: string;
+    /** Explicit output path for the generated spec. Defaults to specs/<pkg>_scaffold.txt */
+    outputPath?: string;
+    /** Driver instance for dependency injection */
+    driver?: AndroidDriver;
+    /** Whether to explore interconnected screens and generate a multi-screen journey spec */
+    journey?: boolean;
+}
+export interface ScaffoldResult {
+    packageName: string;
+    specContent: string;
+    specPath?: string;
+    stepsCount: number;
+    inputCount: number;
+    buttonCount: number;
+}
+/**
+ * Sanitizes node labels by stripping Private Use Area (PUA) icon font glyphs,
+ * special/non-printable unicode codepoints, and leading/trailing punctuation.
+ */
+export declare function sanitizeNodeLabel(label: string): string;
+/**
+ * Derives a human-readable clean label from a UiNode.
+ */
+export declare function getNodeLabel(node: UiNode): string;
+/**
+ * Synthesizes a valid PromptTest specification from a flat list of UiNodes.
+ */
+export declare function scaffoldSpecFromNodes(nodes: UiNode[], packageName?: string): string;
+/**
+ * Validates that every generated step in a spec string parses cleanly with the PromptTest DSL.
+ */
+export declare function validateScaffoldedSpec(specContent: string): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Connects to the device, retrieves screen hierarchy, and writes a scaffolded spec file.
+ */
+export declare function scaffoldSpec(options?: ScaffoldOptions): Promise<ScaffoldResult>;