prompttest 1.3.4 → 1.4.0

package/LICENSE

@@ -34,3 +34,9 @@ Apache License, Version 2.0
 Notice:
 For commercial licensing inquiries, enterprise agreements, or custom SLAs, contact:
 PromptTest (https://github.com/shriramsingh/promptTest)
+
+Scope Notice:
+This License applies solely to the Licensed Work identified above (the PromptTest
+command-line interface, SDK, and associated engine). PromptTest Studio and any other
+PromptTest-branded products or services are separate products governed by their own
+license agreements and are NOT licensed under this License.

package/README.md

@@ -53,6 +53,8 @@ You can run PromptTest instantly with `npx` or install it as a dev dependency:
 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).
+
 ---
 
 ### 5 Core CLI Workflows
@@ -281,18 +283,121 @@ npx prompttest memory <package>
 
 ---
 
-## 🎯 Mode Expectations & Limits
+## 🎯 Platform Support, Expectations & Boundaries
 
-To maintain honest expectations, here is what PromptTest excels at and its architectural boundaries:
+To maintain honest expectations, here is what PromptTest currently supports, what is under active development, and its architectural boundaries:
 
-| Capability | Supported? | Notes |
+| Platform / Framework | Supported? | Notes |
 | :--- | :---: | :--- |
-| **Standard UI Apps** | ✅ Full | React Native, Expo, Flutter, Native Views, Jetpack Compose. |
-| **Zero Code Changes** | ✅ Full | Operates 100% via native ADB hierarchy stream (`uiautomator dump`). |
-| **Self-Healing** | ✅ Full | Auto-resolves modified counts and labels dynamically. |
-| **Bottom-Tab Discovery** | ✅ Full | Explores hubs, nested master-detail views, and backtracks cleanly. |
-| **Game Engines & Canvas**| ⚠️ Limited | Fully custom OpenGL/Vulkan/Unity games lack accessible UI nodes. |
-| **Biometrics / OS Dialogs**| ⚠️ Limited | System-level biometric prompts require hardware-level mocks. |
+| **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**:
+  - 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**:
+  - Use conditional handling in your spec:
+    ```text
+    Tap 'While using the app' (if present)
+    Tap 'Allow' (if present)
+    ```
+  - Or auto-grant permissions via ADB before running tests:
+    ```bash
+    adb shell pm grant com.yourcompany.app android.permission.POST_NOTIFICATIONS
+    ```
+
+### 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**:
+  - Scroll before tapping:
+    ```text
+    Scroll down
+    Verify 'Save Changes' is visible
+    Tap 'Save Changes'
+    ```
+
+### 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**:
+  - 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
+    adb shell settings put global window_animation_scale 0
+    adb shell settings put global transition_animation_scale 0
+    adb shell settings put global animator_duration_scale 0
+    ```
+
+### 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**:
+  - 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**:
+  - Target a specific device serial using `--serial`:
+    ```bash
+    npx prompttest run specs/login.txt com.app --serial=emulator-5554
+    ```
+
+---
+
+## 💡 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:
+  ```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:
+  ```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.
+
+### 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.
+
+### 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:
+  ```bash
+  # Via CLI flag:
+  npx prompttest explore com.yourcompany.app --safety-blacklist="Transfer,Deactivate,Revoke,Unsubscribe"
+  ```
+* **Or configure once in `.prompttestrc.json`**:
+  ```json
+  {
+    "safety": {
+      "mode": "strict",
+      "customBlacklist": ["Transfer", "Deactivate", "Revoke", "Unsubscribe"]
+    }
+  }
+  ```
 
 ---
 
@@ -352,8 +457,19 @@ Tested and verified against live physical Android devices running complex multi-
 
 ## 📄 License
 
-PromptTest is licensed under the **Business Source License 1.1 (BSL 1.1)**:
+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
+- Offering PromptTest (modified or unmodified) as a hosted or managed QA/cloud testing service
+
+See the full [LICENSE](./LICENSE) and [Terms & Conditions](./TERMS.md) for exact terms.
 
-- **Free for Community Use**: 100% free for educational use, individual developers, open-source projects, and startups/businesses with under $100,000 in annual revenue.
-- **Commercial License**: Required for organizations exceeding the annual revenue threshold or companies wrapping PromptTest into hosted cloud services.
-- Commercial inquiries and enterprise licensing: `jairam.singh9@gmail.com`.
+Commercial inquiries and enterprise licensing: `jairam.singh9@gmail.com` or open an issue at [github.com/shriramsingh/promptTest](https://github.com/shriramsingh/promptTest/issues).

package/TERMS.md

@@ -0,0 +1,134 @@
+# PromptTest Terms & Conditions
+
+> **Status:** Draft for legal review. Have a qualified attorney review these terms
+> before relying on them commercially. This document supplements — and does not
+> replace — the [LICENSE](./LICENSE) (Business Source License 1.1).
+
+Effective Date: 2026-09-20
+Operator: PromptTest (Shriram Singh)
+Contact: jairam.singh9@gmail.com
+
+---
+
+## 1. Definitions
+
+- **"PromptTest CLI"** — the PromptTest command-line interface, SDK, and engine
+  distributed via npm under the BSL 1.1 license.
+- **"PromptTest Studio"** — the PromptTest-branded web/desktop testing product with a
+  graphical user interface. Studio is a **separate commercial product** licensed under
+  its own agreement and is **not** governed by these terms or the BSL license.
+- **"Commercial License"** — a paid license agreement signed with the Operator that
+  lifts the usage restrictions of the BSL 1.1 Additional Use Grant.
+- **"License Key"** — a cryptographic token issued upon purchase that unlocks paid
+  tiers or removes free-tier usage limits.
+
+## 2. Use Tiers
+
+### 2.1 Free / Community Tier (BSL 1.1)
+Use of the PromptTest CLI is free under the terms of the BSL 1.1 Additional Use Grant
+for:
+- Personal, educational, academic, and open-source purposes;
+- Evaluation use; and
+- Internal software testing within organizations with both (a) annual gross revenue
+  under $100,000 USD (or equivalent) and (b) fewer than 10 employees.
+
+### 2.2 Commercial Tier
+Organizations exceeding the free-tier thresholds, testing agencies providing QA
+services to third parties, and production commercial CI/CD deployments require a
+paid Commercial License. Contact the Operator for pricing and terms.
+
+## 3. Acceptable Use
+
+You agree **not** to:
+1. Circumvent, bypass, or attempt to defeat any license-key validation, feature
+   gating, or usage limits in the PromptTest CLI or Studio.
+2. Reverse-engineer, decompile, or extract source code, models, heuristics, or
+   proprietary logic from PromptTest Studio, except where such restriction is
+   prohibited by applicable law.
+3. Use PromptTest against applications you do not own or lack explicit permission to
+   test, or in violation of any applicable law (including computer misuse and
+   unauthorized-access statutes).
+4. Resell, sublicense, or redistribute PromptTest Studio or paid Commercial License
+   entitlements without written authorization.
+5. Offer PromptTest (modified or unmodified) as a hosted, managed, or cloud testing
+   service to third parties (this mirrors the BSL 1.1 Hosting & Managed Service
+   Restriction).
+6. Remove or obscure any license, copyright, or attribution notices.
+
+## 4. Intellectual Property & Trademarks
+
+- All rights, title, and interest in PromptTest, PromptTest Studio, and associated
+  documentation remain with the Operator.
+- The names "PromptTest" and "PromptTest Studio," logos, and brand assets are
+  trademarks of the Operator. You may refer to PromptTest nominatively (e.g., in
+  tutorials or CI configurations), but you may not use the marks to brand a
+  competing product or imply endorsement.
+- Nothing in these terms transfers ownership of any intellectual property.
+
+## 5. License Keys & Paid Features
+
+- License Keys are issued per organization/seat as specified in your order and are
+  non-transferable unless agreed in writing.
+- Paid features unlocked by a License Key may be verified locally or require periodic
+  online validation; extended offline grace periods are available for air-gapped CI
+  environments on request.
+- Sharing a License Key beyond its licensed scope is a material breach and will
+  terminate the license immediately.
+
+## 6. Data & Privacy
+
+- The PromptTest CLI operates 100% locally and collects no telemetry by default (see
+  [SECURITY.md](./SECURITY.md)).
+- External LLM providers are strictly opt-in; you are responsible for the data you
+  choose to send to third-party providers.
+- PromptTest Studio's data handling is described in its own privacy policy at the
+  time of its release.
+
+## 7. Subscriptions, Billing & Refunds (Paid Products)
+
+- Paid licenses and subscriptions are billed in advance per the pricing plan chosen
+  at purchase.
+- Subscriptions renew automatically until cancelled; cancellation takes effect at the
+  end of the current billing period.
+- Refunds are handled per the policy stated at the point of sale (default: 14-day
+  refund window for first-time purchases).
+
+## 8. Support & Service Levels
+
+- Free-tier users receive community support via GitHub Issues only.
+- Commercial and Enterprise customers receive support per their signed agreement
+  (response SLAs are defined in SECURITY.md for vulnerabilities and in the Commercial
+  License for general support).
+
+## 9. Disclaimers & Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, PROMPTTEST IS PROVIDED "AS IS" WITHOUT
+WARRANTIES OF ANY KIND. THE OPERATOR IS NOT LIABLE FOR ANY INDIRECT, INCIDENTAL,
+SPECIAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS OR DATA LOSS. TOTAL
+AGGREGATE LIABILITY FOR PAID PRODUCTS IS LIMITED TO THE AMOUNTS PAID BY YOU IN THE
+TWELVE (12) MONTHS PRECEDING THE CLAIM. (Note: this mirrors the BSL 1.1 warranty
+disclaimer for the free CLI; negotiate specific terms in Commercial License
+agreements.)
+
+## 10. Termination
+
+- Use in violation of the LICENSE or these terms terminates all rights immediately
+  (BSL 1.1 also terminates rights across all versions on violation).
+- Upon termination, you must cease use and delete all copies of the Licensed Work.
+
+## 11. Changes to These Terms
+
+The Operator may update these terms; material changes will be announced via the
+repository or the npm package notes at least 30 days before taking effect for
+existing paid customers. Continued use after the effective date constitutes
+acceptance.
+
+## 12. Governing Law
+
+These terms are governed by the laws of India (or the jurisdiction specified in your
+Commercial License agreement), without regard to conflict-of-law rules.
+
+---
+
+*PromptTest Studio is developed and sold separately. This document does not grant
+any rights to PromptTest Studio. See the Studio license agreement for details.*