prompttest 1.3.1 → 1.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +98 -66
  2. package/package.json +1 -2
package/README.md CHANGED
@@ -4,14 +4,25 @@
4
4
  > The zero-setup, zero-instrumentation alternative to Appium & Detox for React Native, Expo, Flutter, and Native Android.
5
5
 
6
6
  [![npm version](https://img.shields.io/npm/v/prompttest.svg?color=cb3837)](https://www.npmjs.com/package/prompttest)
7
- [![License: BSL 1.1](https://img.shields.io/badge/License-BSL%201.1-blue.svg)](LICENSE)
7
+ [![License: BSL 1.1](https://img.shields.io/badge/License-BSL%201.1-blue.svg)](#-license)
8
8
  [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
9
9
  [![Android ADB](https://img.shields.io/badge/Android-ADB%20Native-orange.svg)](https://developer.android.com/tools/adb)
10
10
  [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
11
11
 
12
12
  **PromptTest** enables QA engineers, mobile developers, and autonomous agents to test Android applications using **plain-English natural language scripts**. It completely bypasses heavy server frameworks (Appium, Selenium, WebDriver) in favor of high-speed native ADB streams, expectation-driven polling, and an autonomous state-graph exploration engine.
13
13
 
14
- 📖 **[Read the Full User Manual](docs/USER_MANUAL.md)** • 🏛 **[System Architecture](docs/ARCHITECTURE.md)** • 📜 **[License (BSL 1.1)](LICENSE)** • 🤝 **[Contributing](CONTRIBUTING.md)**
14
+ ---
15
+
16
+ ### 📑 Quick Navigation
17
+ - [🚀 30-Second Quick Start](#-30-second-quick-start)
18
+ - [✍️ Writing Plain-English Tests](#️-writing-plain-english-tests)
19
+ - [📖 Syntax Reference](#-syntax-reference)
20
+ - [🛠 CLI Command Reference](#-cli-command-reference)
21
+ - [🎯 Mode Expectations & Limits](#-mode-expectations--limits)
22
+ - [💻 Programmatic TypeScript SDK](#-programmatic-typescript-sdk)
23
+ - [🐳 Docker Deployment](#-docker-container-deployment)
24
+ - [📊 Real-Device Benchmarks](#-proven-real-device-benchmarks)
25
+ - [📄 License](#-license)
15
26
 
16
27
  ---
17
28
 
@@ -61,7 +72,7 @@ Test specifications are simple text files containing numbered steps written in c
61
72
  ### Example Spec (`specs/login_and_dashboard.txt`)
62
73
 
63
74
  ```text
64
- # 1. Authentication
75
+ # 1. Authentication Flow
65
76
  1. Type 'ramesh@coachconnect.app' into 'Email Address'
66
77
  2. Type 'Teacher@1234' into 'Password'
67
78
  3. Tap 'Sign In'
@@ -72,7 +83,7 @@ Test specifications are simple text files containing numbered steps written in c
72
83
  6. Verify 'Dr. Ramesh Sharma' is visible
73
84
  7. Verify 'My Batches' is visible
74
85
 
75
- # 3. Batches Module
86
+ # 3. Batches Module & Navigation
76
87
  8. Tap 'Batches'
77
88
  9. Verify 'Batches & Schedules' is visible
78
89
  10. Tap 'Grade 10 Mathematics'
@@ -93,86 +104,107 @@ npx prompttest run specs/login_and_dashboard.txt com.yourcompany.app
93
104
 
94
105
  ---
95
106
 
96
- ## 🛠 Core Commands & Capabilities
107
+ ## 📖 Syntax Reference
108
+
109
+ | Category | Command Syntax | Description |
110
+ | :--- | :--- | :--- |
111
+ | **Tap / Click** | `Tap 'Sign In'` | Taps button, icon, link, or tab matching label or text. |
112
+ | **Input Fields** | `Type 'user@test.com' into 'Email'` | Auto-focuses field, clears existing text, and enters string safely. |
113
+ | **Assertions** | `Verify 'Dashboard' is visible` | Polls until the element appears on screen (sub-second resolution). |
114
+ | **Absence Check** | `Verify 'Loading...' is not visible` | Confirms an element, dialog, or spinner has dismissed. |
115
+ | **Spatial Tap** | `Tap 'Delete' next to 'Order #12'` | Disambiguates duplicate elements using directional proximity. |
116
+ | **Gestures** | `Scroll down`, `Scroll up`, `Swipe left` | Performs viewport-proportional touch flings. |
117
+ | **Hardware Keys** | `Press back`, `Press home` | Dispatches physical Android keycodes (`KEYCODE_BACK`, etc.). |
118
+ | **Delays** | `Wait 2s` or `Wait 1500ms` | Pauses execution for custom animation settling. |
119
+ | **Conditionals** | `Tap 'Dismiss' (if present)` | Executes step only if element exists, without failing the suite. |
120
+ | **Generators** | `$random.email`, `$date.now`, `$uuid` | Inlines dynamic synthetic data into input fields. |
121
+
122
+ ---
123
+
124
+ ## 🛠 CLI Command Reference
125
+
126
+ ### Primary Execution Modes
97
127
 
98
- ### 1. Spec Runner (`prompttest run`)
99
- Executes deterministic plain-English test specs with fail-fast execution and self-healing locators:
100
128
  ```bash
101
- # Basic run
102
- npx prompttest run specs/flow.txt com.example.app
129
+ # 1. Deterministic Spec Runner
130
+ npx prompttest run specs/flow.txt <package>
103
131
 
104
- # Cold-restart app before testing begins
105
- npx prompttest run specs/flow.txt com.example.app --fresh
132
+ # Cold-restart app before suite begins
133
+ npx prompttest run specs/flow.txt <package> --fresh
106
134
 
107
- # Capture full screenshots on every step
108
- npx prompttest run specs/flow.txt com.example.app --screenshots
135
+ # Capture high-resolution visual screenshots on every step
136
+ npx prompttest run specs/flow.txt <package> --screenshots
109
137
 
110
- # Dry-run validation (validates grammar without touching device)
138
+ # Dry-run validation (checks syntax without touching device)
111
139
  npx prompttest run specs/flow.txt --dry-run
112
140
 
113
141
  # Display formatted table of parsed steps
114
142
  npx prompttest run specs/flow.txt --list-steps
115
143
 
116
144
  # Run data-driven iterations
117
- npx prompttest run specs/flow.txt com.example.app --iterations 5
145
+ npx prompttest run specs/flow.txt <package> --iterations 5
118
146
 
119
- # Run against a managed device pool
120
- npx prompttest run specs/flow.txt com.example.app --device-pool emulator-5554,emulator-5556
147
+ # Run against a managed device pool with concurrency leasing
148
+ npx prompttest run specs/flow.txt <package> --device-pool emulator-5554,emulator-5556
121
149
 
122
150
  # Visual regression testing against gold baseline images
123
151
  npx prompttest run specs/flow.txt --save-baseline
124
152
  npx prompttest run specs/flow.txt --compare-baseline --baseline-threshold=0.02
125
153
  ```
126
154
 
127
- ### 2. Autonomous State-Graph Explorer (`prompttest explore`)
128
- Autonomous crawling engine with bottom-tab detection, smart form filling, and safety policies:
155
+ ### Autonomous State-Graph Explorer (`explore`)
156
+
129
157
  ```bash
130
- # Standard autonomous crawl (Strict safety mode)
131
- npx prompttest explore com.example.app
158
+ # Autonomous exploration with Strict safety policy
159
+ npx prompttest explore <package>
132
160
 
133
- # Set custom screen and step interaction budgets
134
- npx prompttest explore com.example.app --max-screens=30 --step-budget=60
161
+ # Set custom screen discovery and step interaction limits
162
+ npx prompttest explore <package> --max-screens=30 --step-budget=60
135
163
 
136
- # Add custom protected blacklist keywords
137
- npx prompttest explore com.example.app --safety-blacklist="Wipe,Revoke,Transfer"
164
+ # Protect custom sensitive action keywords from being clicked
165
+ npx prompttest explore <package> --safety-blacklist="Wipe,Revoke,Transfer"
138
166
  ```
139
167
 
140
- ### 3. Interactive Record & Replay (`prompttest record`)
141
- Record your real interactions on the phone and auto-generate clean test specs:
168
+ ### Interactive Record & Replay (`record`)
169
+
142
170
  ```bash
171
+ # Record gestures, taps, and inputs directly on device into a spec
143
172
  npx prompttest record specs/recorded_flow.txt
144
173
  ```
145
174
 
146
- ### 4. Device Management & Wi-Fi Debugging
147
- Connect to physical phones wirelessly without keeping USB cables attached:
175
+ ### Device Management & Wi-Fi Debugging
176
+
148
177
  ```bash
149
- # List connected devices and serials
178
+ # List all connected devices, emulators, and serial numbers
150
179
  npx prompttest devices
151
180
 
152
- # Connect to device wirelessly over Wi-Fi
181
+ # Connect to physical device wirelessly over Wi-Fi
153
182
  npx prompttest wifi 192.168.1.50
154
183
 
155
184
  # Inspect active screen hierarchy and detected components
156
185
  npx prompttest status
186
+
187
+ # Run comprehensive environment diagnostic check
188
+ npx prompttest doctor
189
+
190
+ # View offline learned component memory graph
191
+ npx prompttest memory <package>
157
192
  ```
158
193
 
159
194
  ---
160
195
 
161
- ## 📖 Plain-English Syntax Reference
196
+ ## 🎯 Mode Expectations & Limits
162
197
 
163
- | Interaction | Example Syntax | Description |
164
- | :--- | :--- | :--- |
165
- | **Tap / Click** | `Tap 'Sign In'` | Clicks buttons, icons, tabs, or links by text or accessibility label. |
166
- | **Text Input** | `Type 'test@example.com' into 'Email'` | Focuses input, clears existing text, and types value safely. |
167
- | **Assertions** | `Verify 'Dashboard' is visible` | Polls until the element appears on screen. |
168
- | **Negative Check** | `Verify 'Loading...' is not visible` | Confirms an element or spinner has dismissed. |
169
- | **Relative Tap** | `Tap 'Delete' next to 'Order #12'` | Disambiguates duplicate elements using spatial proximity. |
170
- | **Gestures** | `Scroll down`, `Scroll up`, `Swipe left` | Responsive proportional swipe gestures across the viewport. |
171
- | **System Keys** | `Press back`, `Press home` | Emits hardware key events (`KEYCODE_BACK`, etc.). |
172
- | **Pauses** | `Wait 2s` or `Wait 1500ms` | Pauses execution for custom animation delays. |
173
- | **Conditionals** | `Tap 'Dismiss' (if present)` | Executes step only if target element is visible without failing. |
174
-
175
- *For advanced syntax (loops, regex assertions, data-driven iterations, subflow `#include`), check the **[Comprehensive User Manual](docs/USER_MANUAL.md)**.*
198
+ To maintain honest expectations, here is what PromptTest excels at and its architectural boundaries:
199
+
200
+ | Capability | Supported? | Notes |
201
+ | :--- | :---: | :--- |
202
+ | **Standard UI Apps** | ✅ Full | React Native, Expo, Flutter, Native Views, Jetpack Compose. |
203
+ | **Zero Code Changes** | ✅ Full | Operates 100% via native ADB hierarchy stream (`uiautomator dump`). |
204
+ | **Self-Healing** | ✅ Full | Auto-resolves modified counts and labels dynamically. |
205
+ | **Bottom-Tab Discovery** | ✅ Full | Explores hubs, nested master-detail views, and backtracks cleanly. |
206
+ | **Game Engines & Canvas**| ⚠️ Limited | Fully custom OpenGL/Vulkan/Unity games lack accessible UI nodes. |
207
+ | **Biometrics / OS Dialogs**| ⚠️ Limited | System-level biometric prompts require hardware-level mocks. |
176
208
 
177
209
  ---
178
210
 
@@ -183,7 +215,7 @@ PromptTest exports a full programmatic SDK for embedding into Node.js test runne
183
215
  ```typescript
184
216
  import { createPromptRunner, createAndroidDriver } from 'prompttest';
185
217
 
186
- // Initialize native ADB driver for device
218
+ // Initialize native ADB driver for connected device
187
219
  const driver = createAndroidDriver('DEVICE_SERIAL');
188
220
  const runner = createPromptRunner(driver);
189
221
 
@@ -193,40 +225,40 @@ const report = await runner.runSpec('specs/login.txt', 'com.example.app', {
193
225
  screenshots: 'failure-only',
194
226
  });
195
227
 
196
- console.log(`Passed: ${report.passedSteps}/${report.totalSteps}`);
228
+ console.log(`Execution complete: ${report.passedSteps}/${report.totalSteps} passed.`);
197
229
  ```
198
230
 
199
231
  ---
200
232
 
201
- ## 📊 Proven Real-Device Benchmarks
202
-
203
- Tested and verified against live physical Android devices running complex multi-role enterprise apps:
204
-
205
- | Test Suite | Total Steps | Passed | Failed | Pass Rate | Execution Time |
206
- | :--- | :---: | :---: | :---: | :---: | :---: |
207
- | **CoachConnect Enterprise Suite** | 52 | 52 | 0 | **100%** | 47.8s |
208
- | **Govindam Multilingual Suite** | 8 | 8 | 0 | **100%** | 35.1s |
209
- | **Calculator Operations Suite** | 5 | 5 | 0 | **100%** | 19.6s |
210
- | **Automated Vitest Test Matrix** | 294 | 294 | 0 | **100%** | 14.8s |
211
-
212
233
  ## 🐳 Docker Container Deployment
213
234
 
214
235
  PromptTest is containerized with Android platform-tools and headless runtime support:
215
236
 
216
237
  ```bash
238
+ # Build container image
217
239
  docker build -t prompttest .
218
- docker run --rm --net=host -v $(pwd)/specs:/app/specs prompttest run specs/flow.txt com.example.app
240
+
241
+ # Execute test spec inside container sharing host ADB daemon
242
+ docker run --rm --net=host \
243
+ -v $(pwd)/specs:/app/specs \
244
+ -v $(pwd)/output:/app/output \
245
+ prompttest run specs/flow.txt com.example.app
219
246
  ```
220
247
 
221
248
  ---
222
249
 
223
- ## 📁 Packaged Artifacts & Documentation
250
+ ## 📊 Proven Real-Device Benchmarks
251
+
252
+ Tested and verified against live physical Android devices running complex multi-role enterprise apps:
253
+
254
+ | Test Suite | Total Steps | Passed | Failed | Pass Rate | Execution Time |
255
+ | :--- | :---: | :---: | :---: | :---: | :---: |
256
+ | **CoachConnect Enterprise Suite** | 52 | 52 | 0 | **100%** | 47.8s |
257
+ | **Govindam Multilingual Suite** | 8 | 8 | 0 | **100%** | 35.1s |
258
+ | **Calculator Operations Suite** | 5 | 5 | 0 | **100%** | 19.6s |
259
+ | **Automated Vitest Test Matrix** | 294 | 294 | 0 | **100%** | 14.8s |
224
260
 
225
- - **[docs/USER_MANUAL.md](docs/USER_MANUAL.md)**: Exhaustive reference manual covering all keywords, configurations, edge-case triage, and real-world recipes.
226
- - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**: Deep dive into the ADB streaming driver, state-graph crawler, and memory indexing engine.
227
- - **[LICENSE](LICENSE)**: Legal terms under the Business Source License (BSL 1.1).
228
- - **[CONTRIBUTING.md](CONTRIBUTING.md)**: Guidelines for contributing bug fixes and enhancements.
229
- - **[SECURITY.md](SECURITY.md)**: Security vulnerability disclosure policy.
261
+ *For deep architectural details and driver design, see `docs/ARCHITECTURE.md` included in the package.*
230
262
 
231
263
  ---
232
264
 
@@ -236,4 +268,4 @@ PromptTest is licensed under the **Business Source License 1.1 (BSL 1.1)**:
236
268
 
237
269
  - **Free for Community Use**: 100% free for educational use, individual developers, open-source projects, and startups/businesses with under $100,000 in annual revenue.
238
270
  - **Commercial License**: Required for organizations exceeding the annual revenue threshold or companies wrapping PromptTest into hosted cloud services.
239
- - See the full terms in **[LICENSE](LICENSE)**. For commercial licensing inquiries, contact `jairam.singh9@gmail.com`.
271
+ - Commercial inquiries and enterprise licensing: `jairam.singh9@gmail.com`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "prompttest",
3
- "version": "1.3.1",
3
+ "version": "1.3.2",
4
4
  "description": "Ultra-fast, zero-code autonomous mobile testing & visual QA brain for Android",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "type": "module",
@@ -49,7 +49,6 @@
49
49
  "prepublishOnly": "npm run typecheck && npm run build",
50
50
  "pack:check": "npm pack --dry-run",
51
51
  "preversion": "npm run typecheck && npm test",
52
- "postversion": "git push && git push --tags",
53
52
  "version:patch": "npm version patch",
54
53
  "version:minor": "npm version minor",
55
54
  "version:major": "npm version major"