npm package: @ljiahao/qaspec
Description: Agentic QA Automation Workflow for Gemini CLI - Integrated with Appium MCP
Author: ljiahao
Latest version: 1.4.0

# QASpec: Agentic QA Automation Framework

QASpec is an advanced workflow extension designed for AI agents (such as Gemini CLI and Claude Code). It transforms standard AI capabilities into a structured QA Engineering process, enabling autonomous application exploration, behavior-driven test generation, and isolated workspace management.

## Core Advantages

### 1. Shadow Workspaces (Git Worktree Isolation)
Unlike traditional AI tools that modify your active working directory, QASpec utilizes `git worktree` to create **Shadow Workspaces**.
*   **Zero Pollution**: All AI-generated artifacts, intermediate logs, and temporary test scripts are stored in a hidden `.qaspec_worktree/` directory.
*   **Concurrent Development**: The AI works in its own isolated branch and directory. Your current branch remains "clean" and "inactive," allowing you to continue coding without interruption.
*   **Safe Rollbacks**: If the AI's output is unsatisfactory, simply discard the worktree without affecting your source tree.

### 2. Autonomous Application Exploration
Powered by the Appium MCP, the `/qaspec:explore` skill gives the AI "eyes and hands" to interact with your application.
*   **Behavior Modeling**: The AI autonomously traverses the UI to identify elements and flows, translating them into a human-readable `behavior_record.md`.
*   **Context Awareness**: It scans your existing Page Object Models (POM) and libraries to ensure the generated actions align with your project's architecture.

### 3. Visual Web Review
QASpec bridges the gap between AI generation and human oversight with the `/qaspec:review` command.
*   **Browser-Based Diff**: Instead of reading raw git diffs in the terminal, QASpec launches a side-by-side visual report in your default browser.
*   **Governance**: Review every line of code the AI intends to change. Decide to **Merge** the shadow branch into your main codebase only after you are satisfied with the quality.

---

## Standard Workflow

QASpec follows a rigorous Test Development Life Cycle (TDLC):

1.  **`/qaspec:new`**: Initializes a new task and establishes the Shadow Workspace.
2.  **`/qaspec:explore`**: The AI launches the app and maps out the functional paths.
3.  **`/qaspec:observe`**: Findings are structured into a formal behavior specification.
4.  **`/qaspec:generate`**: Test code is authored using project-specific templates and custom skills (e.g., `mobile_test_gen`).
5.  **`/qaspec:review`**: **(Critical Path)** A visual diff is generated for human approval.
6.  **`/qaspec:validate`**: The AI executes the tests and self-heals based on execution results.

---

## Installation & Setup

### 1. Global Installation
```bash
npm install -g @ljiahao/qaspec
```

### 2. Project Initialization
Initialize QASpec for your preferred AI CLI (Gemini or Claude):
```bash
qaspec init claude
# or
qaspec init gemini
```

### 3. Custom Skill Integration
During initialization, QASpec automatically detects local skills. You can map custom skills (like team-specific coding standards) to specific workflow steps (e.g., integrating a specialized generator into the `generate` command).

---

## Why QASpec?

*   **Isolation**: Keep your production-ready code safe from experimental AI modifications.
*   **Transparency**: Every AI action is recorded and visually reviewable.
*   **Extensibility**: Easily import custom skills to adapt to different testing frameworks (Pytest, XCUITest, Espresso).
*   **Autonomy**: Reduces the "hand-holding" required for AI to write functional, high-quality automation.

---
*Developed for the next generation of autonomous QA Engineering.*