prompttest 1.3.0

package/dist/constants/commands.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @module commands
+ * @description Defines standard ADB (Android Debug Bridge) command arrays used throughout PromptTest.
+ * This centralizes all shell syntax, flags, and arguments required to control Android devices,
+ * preventing scattered string-building logic in the driver classes.
+ */
+/**
+ * A collection of constants and factory functions for constructing ADB commands.
+ * All commands are represented as string arrays compatible with child_process.spawn.
+ */
+export declare const ADB_COMMANDS: {
+    /** Command to list all attached devices and emulators. */
+    readonly DEVICES: readonly ["devices", "-l"];
+    /** Command to capture a raw PNG screenshot directly to standard output. */
+    readonly SCREENCAP: readonly ["exec-out", "screencap", "-p"];
+    /** Command to dump window manager state (used to extract screen dimensions and density). */
+    readonly FOREGROUND_APP: readonly ["shell", "dumpsys", "window"];
+    /** Command to dump activity state (used to identify the currently focused app package). */
+    readonly CURRENT_FOCUS: readonly ["shell", "dumpsys", "activity", "activities"];
+    /**
+     * Generates a command to forcefully terminate an application.
+     * @param pkg The Android package name to stop.
+     * @returns Array of ADB command arguments.
+     */
+    readonly FORCE_STOP: (pkg: string) => readonly string[];
+    /**
+     * Generates a command to clear all application data and cache.
+     * @param pkg The Android package name to clear.
+     * @returns Array of ADB command arguments.
+     */
+    readonly CLEAR_APP: (pkg: string) => readonly string[];
+    /**
+     * Generates a command to launch the main launcher activity of an app.
+     * @param pkg The Android package name to launch.
+     * @returns Array of ADB command arguments.
+     */
+    readonly LAUNCH_APP: (pkg: string) => readonly string[];
+    /** Command to dump the current UI Automator hierarchy as compressed XML to standard output. */
+    readonly UIAUTOMATOR_DUMP: readonly ["exec-out", "uiautomator", "dump", "--compressed", "/dev/tty"];
+    /**
+     * Generates a command to simulate a single tap event.
+     * @param x The X coordinate on the screen.
+     * @param y The Y coordinate on the screen.
+     * @returns Array of ADB command arguments.
+     */
+    readonly INPUT_TAP: (x: number, y: number) => readonly string[];
+    /**
+     * Generates a command to input text via the keyboard. Note: spaces and special chars must be escaped.
+     * @param escapedText The text to input, properly escaped for the Android shell.
+     * @returns Array of ADB command arguments.
+     */
+    readonly INPUT_TEXT: (escapedText: string) => readonly string[];
+    /**
+     * Generates a command to simulate a physical or logical key press (e.g., BACK=4, ENTER=66).
+     * @param keyCode The Android KeyEvent code number or name.
+     * @returns Array of ADB command arguments.
+     */
+    readonly INPUT_KEY: (keyCode: number | string) => readonly string[];
+    /**
+     * Generates a command to simulate a swipe gesture across the screen.
+     * @param x1 The starting X coordinate.
+     * @param y1 The starting Y coordinate.
+     * @param x2 The ending X coordinate.
+     * @param y2 The ending Y coordinate.
+     * @param durationMs The duration of the swipe in milliseconds (default: 300).
+     * @returns Array of ADB command arguments.
+     */
+    readonly INPUT_SWIPE: (x1: number, y1: number, x2: number, y2: number, durationMs?: number) => readonly string[];
+    /**
+     * Generates a command to extract the most recent AndroidRuntime crash logs for a package.
+     * @param pkg The Android package name (used by callers to filter the output if needed).
+     * @returns Array of ADB command arguments.
+     */
+    readonly LOGCAT_CRASH: (_pkg: string) => readonly string[];
+    /**
+     * Generates a command to clear the AndroidRuntime crash log buffer.
+     * @returns Array of ADB command arguments.
+     */
+    readonly CLEAR_CRASH_LOGS: () => readonly string[];
+    /**
+     * Generates a command to grant a runtime permission to an application.
+     * @param pkg The Android package name.
+     * @param perm The permission name (will automatically prepend 'android.permission.' if omitted).
+     * @returns Array of ADB command arguments.
+     */
+    readonly GRANT_PERMISSION: (pkg: string, perm: string) => readonly string[];
+    /**
+     * Generates a command to install an APK file on the device, replacing any existing version.
+     * @param path The path to the APK file on the host machine.
+     * @returns Array of ADB command arguments.
+     */
+    readonly INSTALL_APK: (path: string) => readonly string[];
+    /**
+     * Generates a command to completely uninstall an application from the device.
+     * @param pkg The Android package name to uninstall.
+     * @returns Array of ADB command arguments.
+     */
+    readonly UNINSTALL_APP: (pkg: string) => readonly string[];
+    /**
+     * Generates a command to trigger a specific URI intent (deep link) on the device.
+     * @param uri The deep link URI (e.g., 'myapp://settings').
+     * @returns Array of ADB command arguments.
+     */
+    readonly DEEP_LINK: (uri: string) => readonly string[];
+    /**
+     * Generates a command to restart the adbd daemon listening on TCP for wireless debugging.
+     * @param port The TCP port to listen on (default: 5555).
+     * @returns Array of ADB command arguments.
+     */
+    readonly TCPIP: (port?: number) => readonly string[];
+    /**
+     * Generates a command to connect to a device over TCP/IP.
+     * @param target The target IP and optional port (e.g., '192.168.1.100:5555').
+     * @returns Array of ADB command arguments.
+     */
+    readonly CONNECT: (target: string) => readonly string[];
+    /**
+     * Generates a command to disconnect from a specific TCP/IP device or all devices.
+     * @param target The optional target IP to disconnect from.
+     * @returns Array of ADB command arguments.
+     */
+    readonly DISCONNECT: (target?: string) => readonly string[];
+    /** Command to retrieve the device's WLAN IP address. */
+    readonly GET_WLAN_IP: readonly ["shell", "ip", "-f", "inet", "addr", "show", "wlan0"];
+};

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+/**
+ * PromptTest — Ultra-fast, zero-code autonomous mobile testing & visual QA brain for Android
+ *
+ * Programmatic SDK & Core Engine Exports
+ *
+ * Architecture Overview:
+ * This module serves as the primary public SDK entry point for the PromptTest framework.
+ * It provides the building blocks (classes, types, and factory functions) to embed, extend,
+ * or orchestrate the testing engine in a multi-instance, parallelizable manner.
+ *
+ * NOTE: Singleton instances (promptRunner, androidDriver, etc.) are intentionally
+ * NOT exported from the public API. Use the factory functions below to create
+ * isolated instances with no shared state, which is required for parallel runs,
+ * programmatic embedding, and unit testing.
+ */
+import { PromptRunner } from './lib/prompt-runner.js';
+import { AndroidDriver } from './lib/adb.js';
+import { AutonomousExplorer } from './lib/explorer.js';
+import { MemoryEngine } from './lib/memory.js';
+import { QaReporter } from './lib/reporter.js';
+import { AutonomousRecorder } from './lib/recorder.js';
+import { SemanticFormFiller } from './lib/form-filler.js';
+import { BaselineManager } from './lib/baseline.js';
+/** Core engine classes and execution types for test runs. */
+export { PromptRunner, type PromptStep, type RunOptions } from './lib/prompt-runner.js';
+/** ADB wrapper for low-level Android device interaction. */
+export { AndroidDriver, type AndroidDevice } from './lib/adb.js';
+/** Autonomous crawler and UI discovery engine. */
+export { AutonomousExplorer } from './lib/explorer.js';
+/** Dynamic locator learning and UI mapping storage. */
+export { MemoryEngine, type LearnedMapping } from './lib/memory.js';
+/** Audit and visual report generation tools. */
+export { QaReporter, type QaReportData, type AuditStep, type ReportFormat } from './lib/reporter.js';
+/** Interactive test creation via manual recording. */
+export { AutonomousRecorder, type RecordedEvent } from './lib/recorder.js';
+/** AI-powered semantic data generation for form filling. */
+export { SemanticFormFiller, type TestDataPool, type FormFillResult } from './lib/form-filler.js';
+/** Framework logging utilities. */
+export { Logger, logger, type LogLevel } from './lib/logger.js';
+/** Concurrency management for device access. */
+export { acquireDeviceLock, releaseDeviceLock, type DeviceLock } from './lib/lock.js';
+/** Visual regression testing and baseline image management. */
+export { BaselineManager, baselineManager, type BaselineDiffResult, type MaskRegion, type BaselineCompareOptions, } from './lib/baseline.js';
+/** Standard error classes and CLI exit codes. */
+export { ExitCode, PromptTestError, DeviceError, LocatorError, ConfigError, LockError, SpecRecursionError, } from './lib/errors.js';
+/** Additional utility modules and types */
+export * from './lib/crawler.js';
+export * from './lib/patterns.js';
+export * from './lib/dictionary.js';
+export * from './lib/config.js';
+export * from './lib/config-loader.js';
+export * from './lib/step-handlers.js';
+export * from './lib/data-loader.js';
+export * from './lib/live-server.js';
+export * from './lib/runner-utils.js';
+export * from './lib/ai/index.js';
+export * from './lib/benchmark.js';
+export * from './lib/doctor.js';
+export * from './lib/repl.js';
+export * from './lib/driver-interface.js';
+export * from './lib/ios-driver.js';
+export * from './lib/enterprise.js';
+/**
+ * Factory functions to create isolated instances with no shared global state.
+ */
+/**
+ * Creates an isolated PromptRunner instance.
+ * @param driver - Optional custom AndroidDriver instance to use.
+ * @param memory - Optional MemoryEngine instance for locator resolution.
+ * @param reporter - Optional QaReporter instance to log test results.
+ * @returns A fresh PromptRunner instance.
+ * @example
+ * const driver = createAndroidDriver();
+ * const runner = createPromptRunner(driver);
+ * await runner.runFile('test.txt');
+ */
+export declare function createPromptRunner(driver?: AndroidDriver, memory?: MemoryEngine, reporter?: QaReporter): PromptRunner;
+/**
+ * Creates an isolated AutonomousExplorer instance.
+ * @param driver - Optional custom AndroidDriver to control the device.
+ * @param formFiller - Optional SemanticFormFiller for input generation.
+ * @param reporter - Optional QaReporter for visual and audit logs.
+ * @returns A fresh AutonomousExplorer instance.
+ * @example
+ * const explorer = createAutonomousExplorer();
+ * await explorer.explore('com.example.app');
+ */
+export declare function createAutonomousExplorer(driver?: AndroidDriver, formFiller?: SemanticFormFiller, reporter?: QaReporter): AutonomousExplorer;
+/**
+ * Creates an isolated AndroidDriver instance.
+ * @param serial - Optional device serial number to target a specific device.
+ * @returns A fresh AndroidDriver instance.
+ * @example
+ * const driver = createAndroidDriver('emulator-5554');
+ * await driver.init();
+ */
+export declare function createAndroidDriver(serial?: string): AndroidDriver;
+/**
+ * Creates an isolated MemoryEngine instance.
+ * @returns A fresh MemoryEngine instance.
+ * @example
+ * const memory = createMemoryEngine();
+ * await memory.load();
+ */
+export declare function createMemoryEngine(): MemoryEngine;
+/**
+ * Creates an isolated QaReporter instance.
+ * @param outputDir - Optional custom directory path to write reports.
+ * @returns A fresh QaReporter instance.
+ * @example
+ * const reporter = createQaReporter('./reports');
+ * reporter.logStep('Started run');
+ */
+export declare function createQaReporter(outputDir?: string): QaReporter;
+/**
+ * Creates an isolated AutonomousRecorder instance.
+ * @param driver - Optional custom AndroidDriver for recording events.
+ * @returns A fresh AutonomousRecorder instance.
+ * @example
+ * const recorder = createAutonomousRecorder();
+ * await recorder.start();
+ */
+export declare function createAutonomousRecorder(driver?: AndroidDriver): AutonomousRecorder;
+/**
+ * Creates an isolated SemanticFormFiller instance.
+ * @param customDataPath - Optional path to custom form data definitions.
+ * @param driver - Optional AndroidDriver instance.
+ * @returns A fresh SemanticFormFiller instance.
+ * @example
+ * const filler = createFormFiller('./custom-data.json');
+ * await filler.fillCurrentScreen();
+ */
+export declare function createFormFiller(customDataPath?: string, driver?: AndroidDriver): SemanticFormFiller;
+/**
+ * Creates an isolated BaselineManager instance.
+ * @param baselineDir - Optional directory path to store baseline images.
+ * @param threshold - Optional default threshold ratio.
+ * @returns A fresh BaselineManager instance.
+ */
+export declare function createBaselineManager(baselineDir?: string, threshold?: number): BaselineManager;