prompttest 1.3.2 → 1.3.4

package/README.md

@@ -14,7 +14,8 @@
 ---
 
 ### 📑 Quick Navigation
-- [🚀 30-Second Quick Start](#-30-second-quick-start)
+- [🚀 Quick Start & CLI Workflows](#-quick-start--cli-workflows)
+- [📂 Outputs, Reports & Screenshots](#-outputs-reports--screenshots)
 - [✍️ Writing Plain-English Tests](#️-writing-plain-english-tests)
 - [📖 Syntax Reference](#-syntax-reference)
 - [🛠 CLI Command Reference](#-cli-command-reference)
@@ -38,33 +39,120 @@
 
 ---
 
-## 🚀 30-Second Quick Start
+## 🚀 Quick Start & CLI Workflows
 
 ### Prerequisites
 - **Node.js 18.0.0+**
 - **Android ADB** installed and accessible in your system `PATH`
-- An Android device or emulator with **USB Debugging** enabled
+- An Android device (USB or Wi-Fi) or emulator with **USB Debugging** enabled
 
-### 1. Run Instant Diagnostics (Zero Install Needed)
-Verify your environment and connected devices with zero configuration:
+### 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
+```
+
+---
+
+### 5 Core CLI Workflows
+
+#### 1. Environment Diagnostic Check
+Before running tests, verify your ADB connectivity, connected devices, and permissions:
 ```bash
 npx prompttest doctor
 ```
 
-### 2. Autonomous Exploration (0 Lines of Code)
-Autonomously crawl, discover navigation tabs, and stress-test your app:
+#### 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 <your.app.package>
+npx prompttest explore com.yourcompany.app
 ```
+*Tip: `explore` is its own top-level command. Pass `--max-screens=30` or `--safety-mode=strict` to customize.*
 
-### 3. Install in Your Project
-Add PromptTest as a development dependency in your mobile project:
+#### 3. Interactive Record & Replay
+Record your natural interactions on a physical phone directly into a reusable test spec:
 ```bash
-npm install --save-dev prompttest
+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.
+- `--fresh`: Cold-restart the target app before execution begins.
+- `--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
+```
+
+---
+
+### ⚠️ CLI Command Disambiguation Table
+
+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` |
+
+---
+
+### 📦 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",
+  "test:explore": "prompttest explore com.yourcompany.app --max-screens=25",
+  "test:record": "prompttest record specs/new_flow.txt",
+  "test:doctor": "prompttest doctor"
+}
 ```
 
 ---
 
+## 📂 Outputs, Reports & Screenshots
+
+Whenever PromptTest runs (`run`, `explore`, or `record`), all outputs are automatically organized inside an **`output/`** folder at your project root:
+
+```
+your-mobile-project/
+├── node_modules/
+├── specs/
+│   └── login.txt
+├── output/                               <-- 📂 Created automatically
+│   ├── login-report.html                 <-- 🌐 Interactive visual HTML report
+│   ├── login-junit.xml                   <-- 🤖 CI/CD JUnit test results
+│   ├── login-report.md                   <-- 📝 Markdown summary for PR comments
+│   ├── login-results.json                <-- 📊 Structured raw JSON execution metrics
+│   ├── step_1_tap_sign_in.png            <-- 📸 High-res visual screenshots
+│   ├── login-recording.mp4               <-- 🎥 Full MP4 video (when using --video)
+│   └── screenshots/                      <-- 📸 Screen transition photos from record sessions
+```
+
+### 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!
+
+---
+
 ## ✍️ Writing Plain-English Tests
 
 Test specifications are simple text files containing numbered steps written in conversational English.