PromptTest Studio Documentation

1. Introduction & Architecture

PromptTest Studio is an interactive visual desktop IDE designed for mobile QA engineers, developers, and product teams. It enables teams to write, debug, and automate mobile tests on Android devices using intuitive, human-readable English instructions.

Unlike traditional test frameworks that require Appium servers, complex WebDriver drivers, or fragile XPath selectors, PromptTest Studio operates locally via direct Android Debug Bridge (ADB) protocols:

System Requirements

Before installing PromptTest Studio, ensure your development workstation meets the minimum specifications:

• Operating System: Windows 10 (version 1809 or higher) or Windows 11 (64-bit x86_64).
• Memory: 4 GB RAM minimum (8 GB recommended for simultaneous screen mirroring and multi-step suites).
• Disk Space: 250 MB free disk space for the Studio application.
• Android Compatibility: Any physical smartphone, tablet, or emulator running Android 7.0 (Nougat / API 24) or newer.
• Connection: Standard USB data cable or a shared 2.4 GHz / 5 GHz local Wi-Fi network.

Windows Installation & SmartScreen Guide

PromptTest Studio is distributed as a lightweight Windows NSIS installer that installs to your local user directory without requiring administrative rights.

1. Download the latest installer from the Downloads page (e.g. PromptTest Studio_0.1.0_x64-setup.exe).
2. Double-click the downloaded .exe file to launch the setup wizard.

Once installed, launch PromptTest Studio from your Start Menu or Desktop shortcut.

Connecting an Android Device over USB

Follow these quick steps to prepare any physical Android device for automated testing:

To verify the connection in your terminal, run:

adb devices

You should see your device serial number with status device:

List of devices attached
35211FDH200194    device

Untethered Wi-Fi Testing (Wireless ADB)

PromptTest Studio allows you to test devices without any physical USB cables attached, running tests over your local Wi-Fi.

Option A: Android 11, 12, 13, and 14+ (Modern Pairing Code)

1. Ensure your PC and phone are connected to the same Wi-Fi network.
2. Go to Settings > Developer options > Wireless debugging and toggle it ON.
3. Tap directly on Wireless debugging to open its configuration screen.
4. Tap "Pair device with pairing code". Note the 6-digit Wi-Fi pairing code, IP address, and Port (e.g., 192.168.1.150:42135).
5. In PromptTest Studio, open the Device dropdown, click "Connect over Wi-Fi", enter the IP, port, and 6-digit code, and click Connect.

Option B: Android 10 and Older (USB-Assisted Wi-Fi)

1. Connect your phone to your PC via USB cable once.
2. Open PowerShell and run: adb tcpip 5555
3. Disconnect the USB cable.
4. Find your device's IP under Settings > About Phone > Status > IP Address.
5. In PromptTest Studio, enter the IP address with port 5555 and click Connect.

Using Android Emulators (AVD)

PromptTest Studio connects to Android Virtual Devices (AVD) launched through Android Studio or third-party emulators with zero extra configuration:

• Launch any Android Studio emulator from the AVD Manager.
• Studio automatically detects the running emulator (e.g. emulator-5554).
• Select the emulator from the Studio device selector to begin mirroring and testing.

2. Studio Workspace Tour

The PromptTest Studio interface is organized into 4 integrated panels to keep test authoring and device observation in one view:

Live Device Canvas

The central panel mirrors your Android device screen at 60 FPS with low latency. You can interact with the app just like holding the physical phone:

• Left-Click: Sends a native tap event at the clicked pixel coordinates.
• Click & Drag: Performs smooth touch scrolling and directional swiping.
• Keyboard: Direct keyboard input sends native Android key events.

Virtual Hardware Navigation Bar

Directly below the mirrored device screen is the virtual navigation bar:

• Back (◁): Triggers Android hardware Back button (KeyEvent.KEYCODE_BACK).
• Home (○): Navigates to the Android home launcher screen.
• Recents (□): Opens the multitasking app switcher.
• Screen Wake / Unlock: Wakes the device display and bypasses the keyguard.

Visual Element Inspector

When you hover over elements in the device canvas, the inspector highlights the element boundary box and displays critical attributes:

• Visible Text: The displayed label used for plain-English matching (e.g., "Sign In").
• Content Description: Accessibility label for icon buttons (e.g., "Search" or "Cart").
• Resource ID: The developer's assigned identifier (e.g. id/btn_login).
• Element Bounds: Exact screen coordinates `[x1, y1][x2, y2]`.
• State Attributes: `clickable: true`, `editable: false`, `focusable: true`.

Device Manager & Quick Switch

The top toolbar displays the currently active device. If multiple devices are plugged in (e.g., a physical Pixel 7 and a Samsung Galaxy tablet), click the dropdown to switch active context in 1 click.

3. Plain-English Spec Language Reference

PromptTest test specifications are written in natural English verbs. Each line represents an atomic user action or verification.

Application Lifecycle

Touch & Click Actions

Text & Keyboard Input

Scrolling & Navigation

Assertions & Verifications

Complete Sample Test Specs

User Login & Onboarding Test

# 1. Start application
Launch "com.acme.shop"

# 2. Enter credentials
Tap "Sign in with Email"
Type "qa_engineer@acme.com" into "Email address"
Type "secure_pass_2026" into "Password"
Tap "Sign In"

# 3. Assert successful login
Assert "Welcome back, QA Engineer" is visible
Assert "Your Cart (0)" is visible

Search, Add to Cart & Checkout Flow

# Search for item
Tap "Search Products"
Type "Noise Cancelling Headphones" into "Search"
Press Enter

# Verify listing and tap first item
Assert "Sony WH-1000XM5" is visible
Tap "Sony WH-1000XM5"

# Add to cart and proceed
Scroll down
Tap "Add to Cart"
Assert "Item added to cart" is visible
Tap "View Cart"
Assert "Total: $349.99" is visible
Tap "Proceed to Checkout"

4. Visual Regression & Baseline Testing

Mobile applications frequently experience subtle visual regressions: broken layouts, text clipping, missing icons, or overlapping elements that pass traditional functional assertions. PromptTest Studio includes a built-in visual pixel comparison engine.

How to Capture an Approved Reference Baseline

1. In your test spec, add a visual baseline check:

   Assert visual baseline "Product_Details_Screen"

2. Run the test. On the first run, Studio captures the full screen and saves it as the Approved Reference Baseline.
3. On all subsequent runs, Studio captures the new screen at identical resolution and compares pixels against the approved reference.

Dynamic Exclude Masks

Screens often contain fluctuating elements (the digital status bar clock, Wi-Fi signal icon, battery percentage, or dynamic ads) that would trigger false positive differences.

Reviewing Baseline Deviations

When a visual difference exceeds the sensitivity threshold (default: 0.1% pixel change):

• The test step fails with a visual deviation warning.
• Studio presents a Side-by-Side Diff Viewer highlighting changed pixels in neon red.
• You can either click "Accept New Baseline" if the change was an intended redesign, or flag it as a visual regression bug for your development team.

5. Test Suites, Execution & Evidence

Step-by-Step vs Full Suite Execution

• Step-by-Step Debugging: Click the "Run Step" icon next to any individual instruction in Studio to test it in isolation without running the whole file.
• Full Suite Runs: Click "Run Suite" in the top header. Studio executes the entire test specification sequentially from top to bottom.

Live SSE Telemetry & Evidence Generation

During execution, Studio opens a Server-Sent Events (SSE) telemetry connection directly to the test engine. Every action displays its exact duration in milliseconds, pass/fail status, and diagnostic logs.

Upon completion, Studio automatically compiles an evidence package containing:

• Full Execution Log: Timestamps, ADB commands dispatched, and element resolution time.
• Failure Snapshots: High-resolution screenshot captured at the exact moment of failure.
• Interactive HTML Report: Self-contained report file ready to attach to GitHub Issues or Jira tickets.

6. CI/CD Pipeline Automation (PromptTest CLI)

Tests composed visually in PromptTest Studio are saved as human-readable .txt specification files. You can check these spec files directly into your Git repository and run them automatically on every pull request using the official PromptTest CLI published on npm.

Core CLI Commands

Automating in GitHub Actions (.github/workflows/mobile-qa.yml)

Here is a complete, copyable GitHub Actions workflow that launches an Android emulator and executes your Studio test specs automatically on push:

name: Mobile QA Regression Suite

on:
  push:
    branches: [main, dev]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: macos-13  # macOS runners support hardware acceleration for Android emulators
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Run Android Emulator
        uses: reactivecircus/android-emulator-runner@v2
        with:
          api-level: 34
          target: google_apis
          arch: x86_64
          script: |
            # 1. Verify ADB connection
            npx prompttest doctor

            # 2. Run PromptTest Studio specs
            npx prompttest run specs/smoke.txt com.example.myapp --heal --screenshots --embed-screenshots

      - name: Upload Test Evidence & HTML Report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-evidence
          path: output/

JUnit XML & Test Artifacts

Every CLI execution automatically populates an output/ directory containing:

• output/<spec>-junit.xml: Standard JUnit report format, automatically parsed by GitHub Actions, Jenkins, and GitLab CI.
• output/<spec>-report.html: Self-contained visual audit report with inlined Base64 failure screenshots.
• output/<spec>-results.json: Machine-readable JSON metrics for custom dashboards.

7. Troubleshooting & Common Diagnostics

Device Status Shows "Unauthorized"

This means your phone has not yet accepted your computer's RSA security key:

• Unplug and reconnect the USB cable.
• Unlock your phone screen and look for the popup: "Allow USB debugging?".
• Check "Always allow from this computer" and tap Allow.

Resetting the ADB Server Daemon

If another program (like Android Studio or an emulator) locked the ADB communication port, restart the ADB daemon using PowerShell:

adb kill-server
adb start-server

Then refresh PromptTest Studio and your devices will reconnect.

Testing WebViews & Hybrid Apps (React Native / Flutter)

PromptTest Studio interacts natively with React Native, Flutter, and Android WebViews through standard accessibility nodes. Ensure your custom components expose standard accessibility labels (e.g. accessibilityLabel in React Native or Semantics in Flutter) so the Studio inspector can identify them instantly.