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

npm install -g @ljiahao/qaspec

2. Project Initialization

Initialize QASpec for your preferred AI CLI (Gemini or Claude):

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.