prompttest 1.4.0 → 1.5.1

package/README.md

@@ -13,7 +13,21 @@
 
 ---
 
+### 🖥️ Prefer a Visual Desktop IDE? Try PromptTest Studio
+
+If you prefer an intuitive desktop application over the command line, check out **[PromptTest Studio](https://shriramsingh.github.io/prompttest-studio-site/)**:
+- 📱 **Real-Time Device Mirroring**: Low-latency screen streaming with instant click, drag, and hardware navigation.
+- 🎯 **Visual Element Inspector**: Point and click to inspect native views with instant auto-generated plain-English assertions.
+- 📸 **Visual Regression & Exclude Masks**: Pixel-level baseline comparisons with draggable exclude masks for dynamic areas (clocks, battery, banners).
+- 🚀 **100% Local-First & Air-Gapped**: Runs entirely on your machine over local ADB with zero cloud dependencies.
+
+👉 **[Download PromptTest Studio for Windows](https://shriramsingh.github.io/prompttest-studio-site/downloads.html)** *(macOS & Linux coming soon)*
+
+---
+
 ### 📑 Quick Navigation
+
+- [🖥️ PromptTest Studio (Desktop IDE)](#️-prefer-a-visual-desktop-ide-try-prompttest-studio)
 - [🚀 Quick Start & CLI Workflows](#-quick-start--cli-workflows)
 - [📂 Outputs, Reports & Screenshots](#-outputs-reports--screenshots)
 - [✍️ Writing Plain-English Tests](#️-writing-plain-english-tests)
@@ -42,51 +56,66 @@
 ## 🚀 Quick Start & CLI Workflows
 
 ### Prerequisites
+
 - **Node.js 18.0.0+**
 - **Android ADB** installed and accessible in your system `PATH`
 - An Android device (USB or Wi-Fi) or emulator with **USB Debugging** enabled
 
 ### Install in Your Mobile Project
+
 You can run PromptTest instantly with `npx` or install it as a dev dependency:
+
 ```bash
 # In your React Native, Expo, Flutter, or Android project:
 npm install --save-dev prompttest
 ```
 
-> **⚖️ Licensing note**: PromptTest is source-available under **BSL 1.1** — free for personal, educational, open-source, and small-team use (< $100k revenue *and* < 10 employees). Larger organizations and commercial QA agencies need a [commercial license](#-license). It converts to Apache 2.0 in 2030. See [License](#-license).
+> **⚖️ Licensing note**: PromptTest is source-available under **BSL 1.1** — free for personal, educational, open-source, and small-team use (< $100k revenue _and_ < 10 employees). Larger organizations and commercial QA agencies need a [commercial license](#-license). It converts to Apache 2.0 in 2030. See [License](#-license).
 
 ---
 
 ### 5 Core CLI Workflows
 
 #### 1. Environment Diagnostic Check
+
 Before running tests, verify your ADB connectivity, connected devices, and permissions:
+
 ```bash
 npx prompttest doctor
 ```
 
 #### 2. Zero-Code Autonomous Exploration (AI App Crawl)
+
 Crawl bottom tabs, lists, and forms automatically to discover bugs, crashes, or React Native red-screens without writing a single line of test code:
+
 ```bash
 npx prompttest explore com.yourcompany.app
 ```
-*Tip: `explore` is its own top-level command. Pass `--max-screens=30` or `--safety-mode=strict` to customize.*
+
+_Tip: `explore` is its own top-level command. Pass `--max-screens=30` or `--safety-mode=strict` to customize._
 
 #### 3. Interactive Record & Replay
+
 Record your natural interactions on a physical phone directly into a reusable test spec:
+
 ```bash
 npx prompttest record specs/login.txt
 ```
+
 - Tap buttons and type in input fields on your phone; PromptTest auto-generates conversational English test steps.
 - **Append mode**: Add `--append` to add more steps to an existing spec without overwriting.
 - **Safety backup**: If the target file already exists, PromptTest automatically creates a `.bak` backup before modifying.
 
 #### 4. Run Plain-English Test Specs
+
 Execute test specifications with fail-fast validation and locator self-healing:
+
 ```bash
 npx prompttest run specs/login.txt com.yourcompany.app
 ```
+
 Power flags:
+
 - `--heal`: Automatically self-heal altered counts and dynamic locators.
 - `--video`: Record an MP4 video of the execution session.
 - `--screenshots`: Capture high-resolution visual evidence at every step.
@@ -94,7 +123,9 @@ Power flags:
 - `--embed-screenshots`: Embed screenshots directly into a standalone, shareable HTML report.
 
 #### 5. Interactive Live REPL Playground
+
 Experiment with commands live in your terminal against your connected device:
+
 ```bash
 npx prompttest repl com.yourcompany.app
 ```
@@ -105,19 +136,20 @@ npx prompttest repl com.yourcompany.app
 
 To avoid common syntax errors, remember that `explore`, `record`, and `repl` are **standalone commands**:
 
-| Goal | ✅ Correct CLI Command | ❌ Common Mistake |
-| :--- | :--- | :--- |
-| **Autonomous App Crawling** | `npx prompttest explore <pkg>` | `npx prompttest run explore` |
-| **Record from Phone Touches** | `npx prompttest record <spec.txt>` | `npx prompttest run record` |
-| **Run Existing Spec File** | `npx prompttest run <spec.txt> [pkg]` | `npx prompttest <spec.txt>` |
-| **Interactive Live Terminal** | `npx prompttest repl [pkg]` | `npx prompttest run repl` |
-| **Diagnostic Health Check** | `npx prompttest doctor` | `npx prompttest run doctor` |
+| Goal                          | ✅ Correct CLI Command                | ❌ Common Mistake            |
+| :---------------------------- | :------------------------------------ | :--------------------------- |
+| **Autonomous App Crawling**   | `npx prompttest explore <pkg>`        | `npx prompttest run explore` |
+| **Record from Phone Touches** | `npx prompttest record <spec.txt>`    | `npx prompttest run record`  |
+| **Run Existing Spec File**    | `npx prompttest run <spec.txt> [pkg]` | `npx prompttest <spec.txt>`  |
+| **Interactive Live Terminal** | `npx prompttest repl [pkg]`           | `npx prompttest run repl`    |
+| **Diagnostic Health Check**   | `npx prompttest doctor`               | `npx prompttest run doctor`  |
 
 ---
 
 ### 📦 Recommended `package.json` Scripts
 
 Add these convenient shortcuts to your project's `package.json`:
+
 ```json
 "scripts": {
   "test:mobile": "prompttest run specs/smoke.txt com.yourcompany.app --heal",
@@ -149,6 +181,7 @@ your-mobile-project/
 ```
 
 ### Viewing & Sharing Reports:
+
 - **Interactive HTML Dashboard (`output/<spec>-report.html`)**: Double-click to open in any browser. Features step-by-step audit timelines, latency timings, and failure triage bundles.
 - **CI/CD Integration (`output/<spec>-junit.xml`)**: Standard JUnit format natively recognized by GitHub Actions, GitLab CI, Jenkins, and CircleCI.
 - **Zero-Dependency Sharing (`--embed-screenshots`)**: Generates a single standalone HTML report with all images inlined via Base64 data URIs. Email or Slack it directly to teammates without missing image links!
@@ -188,6 +221,7 @@ Test specifications are simple text files containing numbered steps written in c
 ```
 
 ### Run the Spec:
+
 ```bash
 npx prompttest run specs/login_and_dashboard.txt com.yourcompany.app
 ```
@@ -196,18 +230,18 @@ npx prompttest run specs/login_and_dashboard.txt com.yourcompany.app
 
 ## 📖 Syntax Reference
 
-| Category | Command Syntax | Description |
-| :--- | :--- | :--- |
-| **Tap / Click** | `Tap 'Sign In'` | Taps button, icon, link, or tab matching label or text. |
-| **Input Fields** | `Type 'user@test.com' into 'Email'` | Auto-focuses field, clears existing text, and enters string safely. |
-| **Assertions** | `Verify 'Dashboard' is visible` | Polls until the element appears on screen (sub-second resolution). |
-| **Absence Check** | `Verify 'Loading...' is not visible` | Confirms an element, dialog, or spinner has dismissed. |
-| **Spatial Tap** | `Tap 'Delete' next to 'Order #12'` | Disambiguates duplicate elements using directional proximity. |
-| **Gestures** | `Scroll down`, `Scroll up`, `Swipe left` | Performs viewport-proportional touch flings. |
-| **Hardware Keys** | `Press back`, `Press home` | Dispatches physical Android keycodes (`KEYCODE_BACK`, etc.). |
-| **Delays** | `Wait 2s` or `Wait 1500ms` | Pauses execution for custom animation settling. |
-| **Conditionals** | `Tap 'Dismiss' (if present)` | Executes step only if element exists, without failing the suite. |
-| **Generators** | `$random.email`, `$date.now`, `$uuid` | Inlines dynamic synthetic data into input fields. |
+| Category          | Command Syntax                           | Description                                                         |
+| :---------------- | :--------------------------------------- | :------------------------------------------------------------------ |
+| **Tap / Click**   | `Tap 'Sign In'`                          | Taps button, icon, link, or tab matching label or text.             |
+| **Input Fields**  | `Type 'user@test.com' into 'Email'`      | Auto-focuses field, clears existing text, and enters string safely. |
+| **Assertions**    | `Verify 'Dashboard' is visible`          | Polls until the element appears on screen (sub-second resolution).  |
+| **Absence Check** | `Verify 'Loading...' is not visible`     | Confirms an element, dialog, or spinner has dismissed.              |
+| **Spatial Tap**   | `Tap 'Delete' next to 'Order #12'`       | Disambiguates duplicate elements using directional proximity.       |
+| **Gestures**      | `Scroll down`, `Scroll up`, `Swipe left` | Performs viewport-proportional touch flings.                        |
+| **Hardware Keys** | `Press back`, `Press home`               | Dispatches physical Android keycodes (`KEYCODE_BACK`, etc.).        |
+| **Delays**        | `Wait 2s` or `Wait 1500ms`               | Pauses execution for custom animation settling.                     |
+| **Conditionals**  | `Tap 'Dismiss' (if present)`             | Executes step only if element exists, without failing the suite.    |
+| **Generators**    | `$random.email`, `$date.now`, `$uuid`    | Inlines dynamic synthetic data into input fields.                   |
 
 ---
 
@@ -287,31 +321,33 @@ npx prompttest memory <package>
 
 To maintain honest expectations, here is what PromptTest currently supports, what is under active development, and its architectural boundaries:
 
-| Platform / Framework | Supported? | Notes |
-| :--- | :---: | :--- |
-| **Android (Physical & Emulators)** | **✅ Production Ready** | React Native, Expo, Flutter, Native Views, Jetpack Compose. |
-| **iOS / iPhone & iPad** | **🚧 Under Development** | Native iOS engine is in active development; not supported in v1.3.x. |
-| **Websites / Desktop Browsers** | **❌ Not Supported** | Dedicated strictly to mobile apps. For web, use Playwright or Cypress. |
-| **Standard UI Hierarchy** | **✅ Full** | Operates 100% via native ADB hierarchy stream (`uiautomator dump`). |
-| **Self-Healing Dynamic Locators** | **✅ Full** | Auto-resolves modified counts and labels dynamically via `--heal`. |
-| **Bottom-Tab Discovery** | **✅ Full** | Explores hubs, nested master-detail views, and backtracks cleanly. |
-| **Game Engines & Canvas** | **⚠️ Not Supported** | Fully custom OpenGL/Vulkan/Unity games lack accessible UI nodes. |
-| **Biometrics / OS Dialogs** | **⚠️ Limited** | System-level biometric prompts require hardware-level mocks. |
+| Platform / Framework               |        Supported?        | Notes                                                                  |
+| :--------------------------------- | :----------------------: | :--------------------------------------------------------------------- |
+| **Android (Physical & Emulators)** | **✅ Production Ready**  | React Native, Expo, Flutter, Native Views, Jetpack Compose.            |
+| **iOS / iPhone & iPad**            | **🚧 Under Development** | Native iOS engine is in active development; not supported in v1.3.x.   |
+| **Websites / Desktop Browsers**    |   **❌ Not Supported**   | Dedicated strictly to mobile apps. For web, use Playwright or Cypress. |
+| **Standard UI Hierarchy**          |       **✅ Full**        | Operates 100% via native ADB hierarchy stream (`uiautomator dump`).    |
+| **Self-Healing Dynamic Locators**  |       **✅ Full**        | Auto-resolves modified counts and labels dynamically via `--heal`.     |
+| **Bottom-Tab Discovery**           |       **✅ Full**        | Explores hubs, nested master-detail views, and backtracks cleanly.     |
+| **Game Engines & Canvas**          |   **⚠️ Not Supported**   | Fully custom OpenGL/Vulkan/Unity games lack accessible UI nodes.       |
+| **Biometrics / OS Dialogs**        |      **⚠️ Limited**      | System-level biometric prompts require hardware-level mocks.           |
 
 ---
 
 ## ⚠️ Common Pitfalls & How to Solve Them
 
 ### 1. Hardware Back Button Minimizing the App
-* **What happens**: Running `Press back` while on the app's root dashboard or home tab tells the Android OS to minimize or exit the app.
-* **How to solve it**:
+
+- **What happens**: Running `Press back` while on the app's root dashboard or home tab tells the Android OS to minimize or exit the app.
+- **How to solve it**:
   - In specs, tap the in-app back icon/button (e.g. `Tap 'Back'` or `Tap '<'`) instead of the hardware key on top-level screens.
   - In autonomous exploration (`explore`), PromptTest's built-in **Package Jail Guard** automatically detects if the app was backgrounded and restores it.
   - Add the `--fresh` flag when running specs to cold-start your app cleanly before tests.
 
 ### 2. Android OS Permission Dialogs ("Allow Notifications / Location")
-* **What happens**: System dialogs belong to Android OS (`com.android.permissioncontroller`), not your app, and can appear unexpectedly on new installs.
-* **How to solve it**:
+
+- **What happens**: System dialogs belong to Android OS (`com.android.permissioncontroller`), not your app, and can appear unexpectedly on new installs.
+- **How to solve it**:
   - Use conditional handling in your spec:
     ```text
     Tap 'While using the app' (if present)
@@ -323,8 +359,9 @@ To maintain honest expectations, here is what PromptTest currently supports, wha
     ```
 
 ### 3. Off-Screen Items in Long Lists (FlatList / RecyclerView)
-* **What happens**: Mobile frameworks only render visible items on screen to save memory. Elements located further down the page are not in the hierarchy yet.
-* **How to solve it**:
+
+- **What happens**: Mobile frameworks only render visible items on screen to save memory. Elements located further down the page are not in the hierarchy yet.
+- **How to solve it**:
   - Scroll before tapping:
     ```text
     Scroll down
@@ -333,8 +370,9 @@ To maintain honest expectations, here is what PromptTest currently supports, wha
     ```
 
 ### 4. Layout Animations & Shimmer Settling
-* **What happens**: Tapping an element during a layout animation or skeleton fade-in can cause touch coordinates to miss while elements shift.
-* **How to solve it**:
+
+- **What happens**: Tapping an element during a layout animation or skeleton fade-in can cause touch coordinates to miss while elements shift.
+- **How to solve it**:
   - Add a brief settling pause: `Wait 500ms` or assert an anchor element first: `Verify 'Dashboard' is visible`.
   - Disable animations on test devices to run tests 2x faster:
     ```bash
@@ -344,13 +382,15 @@ To maintain honest expectations, here is what PromptTest currently supports, wha
     ```
 
 ### 5. WebViews & In-App Browsers (OAuth & Payment Gateways)
-* **What happens**: In-app web pages (like Google Sign-In or Stripe) expose rendered text to ADB, but not internal HTML DOM tags or CSS selectors.
-* **How to solve it**:
+
+- **What happens**: In-app web pages (like Google Sign-In or Stripe) expose rendered text to ADB, but not internal HTML DOM tags or CSS selectors.
+- **How to solve it**:
   - Use plain text matching (`Tap 'Sign in with Google'`). Deep DOM selector manipulation inside WebViews is not supported.
 
 ### 6. Multiple Devices Connected
-* **What happens**: If a physical phone and an emulator are both plugged in, ADB doesn't know which one to target.
-* **How to solve it**:
+
+- **What happens**: If a physical phone and an emulator are both plugged in, ADB doesn't know which one to target.
+- **How to solve it**:
   - Target a specific device serial using `--serial`:
     ```bash
     npx prompttest run specs/login.txt com.app --serial=emulator-5554
@@ -361,35 +401,40 @@ To maintain honest expectations, here is what PromptTest currently supports, wha
 ## 💡 Pro-Tips & Best Practices
 
 ### 1. The "Record & Refine" Workflow
-* `prompttest record` captures your natural physical device interactions and generates plain-English test steps in real time—scaffolding 90% of your test boilerplate in seconds.
-* **QA Best Practice**: After recording, do a quick 30-second review of the generated `.txt` spec to fine-tune timings or add custom `Verify` assertions.
-* Preview without touching your device:
+
+- `prompttest record` captures your natural physical device interactions and generates plain-English test steps in real time—scaffolding 90% of your test boilerplate in seconds.
+- **QA Best Practice**: After recording, do a quick 30-second review of the generated `.txt` spec to fine-tune timings or add custom `Verify` assertions.
+- Preview without touching your device:
   ```bash
   npx prompttest run specs/flow.txt --dry-run
   ```
 
 ### 2. Deterministic Clean States (`--fresh`)
-* Prevent "already-logged-in" test pollution by adding `--fresh` to cold-start the target app before execution:
+
+- Prevent "already-logged-in" test pollution by adding `--fresh` to cold-start the target app before execution:
   ```bash
   npx prompttest run specs/login.txt com.yourcompany.app --fresh
   ```
 
 ### 3. Zero-Maintenance Dynamic Badges (`--heal`)
-* When notification badges or counts change dynamically (e.g. `'Cart (1)'` vs `'Cart (3)'`), pass `--heal` to allow PromptTest's heuristic engine to self-heal the locator without failing.
+
+- When notification badges or counts change dynamically (e.g. `'Cart (1)'` vs `'Cart (3)'`), pass `--heal` to allow PromptTest's heuristic engine to self-heal the locator without failing.
 
 ### 4. Device & Screen Resolution Agnostic Portability
-* PromptTest binds interactions to semantic accessibility labels and proportional gestures—not fragile hardware pixel coordinates. Specs recorded on a phone seamlessly run on foldables and tablets.
+
+- PromptTest binds interactions to semantic accessibility labels and proportional gestures—not fragile hardware pixel coordinates. Specs recorded on a phone seamlessly run on foldables and tablets.
 
 ### 5. 🛡️ Enterprise Safety Guardrails & Custom Blacklists
-Autonomous exploration is safe by default, but enterprise applications often have company-specific sensitive keywords (e.g. *"Deactivate"*, *"Transfer Funds"*, *"Revoke Access"*).
 
-* **Default Protection**: PromptTest automatically detects and blocks destructive actions like `"Delete"`, `"Wipe"`, `"Remove"`, and `"Discard Changes"`.
-* **Add Your Own Sensitive Keywords**: You can supply your own custom blocked keywords to run **alongside** the defaults:
+Autonomous exploration is safe by default, but enterprise applications often have company-specific sensitive keywords (e.g. _"Deactivate"_, _"Transfer Funds"_, _"Revoke Access"_).
+
+- **Default Protection**: PromptTest automatically detects and blocks destructive actions like `"Delete"`, `"Wipe"`, `"Remove"`, and `"Discard Changes"`.
+- **Add Your Own Sensitive Keywords**: You can supply your own custom blocked keywords to run **alongside** the defaults:
   ```bash
   # Via CLI flag:
   npx prompttest explore com.yourcompany.app --safety-blacklist="Transfer,Deactivate,Revoke,Unsubscribe"
   ```
-* **Or configure once in `.prompttestrc.json`**:
+- **Or configure once in `.prompttestrc.json`**:
   ```json
   {
     "safety": {
@@ -444,14 +489,14 @@ docker run --rm --net=host \
 
 Tested and verified against live physical Android devices running complex multi-role enterprise apps:
 
-| Test Suite | Total Steps | Passed | Failed | Pass Rate | Execution Time |
-| :--- | :---: | :---: | :---: | :---: | :---: |
-| **CoachConnect Enterprise Suite** | 52 | 52 | 0 | **100%** | 47.8s |
-| **Govindam Multilingual Suite** | 8 | 8 | 0 | **100%** | 35.1s |
-| **Calculator Operations Suite** | 5 | 5 | 0 | **100%** | 19.6s |
-| **Automated Vitest Test Matrix** | 294 | 294 | 0 | **100%** | 14.8s |
+| Test Suite                        | Total Steps | Passed | Failed | Pass Rate | Execution Time |
+| :-------------------------------- | :---------: | :----: | :----: | :-------: | :------------: |
+| **CoachConnect Enterprise Suite** |     52      |   52   |   0    | **100%**  |     47.8s      |
+| **Govindam Multilingual Suite**   |      8      |   8    |   0    | **100%**  |     35.1s      |
+| **Calculator Operations Suite**   |      5      |   5    |   0    | **100%**  |     19.6s      |
+| **Automated Vitest Test Matrix**  |     294     |  294   |   0    | **100%**  |     14.8s      |
 
-*For deep architectural details and driver design, see `docs/ARCHITECTURE.md` included in the package.*
+_For deep architectural details and driver design, see `docs/ARCHITECTURE.md` included in the package._
 
 ---
 
@@ -460,11 +505,13 @@ Tested and verified against live physical Android devices running complex multi-
 PromptTest is licensed under the **Business Source License 1.1 (BSL 1.1)**, and automatically converts to the permissive **Apache License 2.0** on the Change Date: **September 14, 2030**.
 
 **✅ Free to use — no license required for:**
+
 - Personal, educational, academic, and open-source projects
 - Evaluation use
 - Internal software testing within organizations that have **both** under $100,000 USD in annual gross revenue **and** fewer than 10 employees
 
 **💼 Commercial license required for:**
+
 - Use within organizations exceeding either of the free-tier thresholds (revenue **or** headcount)
 - Testing agencies providing commercial QA services to third-party clients
 - Deployment into production commercial CI/CD pipelines
@@ -472,4 +519,4 @@ PromptTest is licensed under the **Business Source License 1.1 (BSL 1.1)**, and
 
 See the full [LICENSE](./LICENSE) and [Terms & Conditions](./TERMS.md) for exact terms.
 
-Commercial inquiries and enterprise licensing: `jairam.singh9@gmail.com` or open an issue at [github.com/shriramsingh/promptTest](https://github.com/shriramsingh/promptTest/issues).
+Commercial inquiries and enterprise licensing: `jairam.singh9@gmail.com` or open an issue at [github.com/shriramsingh/prompttest-community](https://github.com/shriramsingh/prompttest-community/issues).