GhostQA

SpecterQA

AI 用户角色在你的应用中漫游，让真实用户不再磕磕绊绊。

SpecterQA 会让 AI 用户角色在你的应用中体验操作——它们会查看屏幕、决定下一步操作，并像真实用户一样进行交互。无需测试脚本，也无需选择器。你只需用 YAML 描述用户角色和用户旅程，其余交给 SpecterQA 处理。

$ specterqa run -p myapp

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ SpecterQA Run                                                    ┃
┃ Product: myapp   Budget: $5.00   Viewport: 1280x720            ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

  ✓ Step 1/4: Navigate to homepage       PASS   3.2s   $0.0081
  ✓ Step 2/4: Click signup link          PASS   2.1s   $0.0043
  ✓ Step 3/4: Fill registration form     PASS   8.7s   $0.0312
  ✓ Step 4/4: Verify dashboard loads     PASS   4.5s   $0.0127

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ALL TESTS PASSED                                                ┃
┃ Steps: 4/4   Findings: 0   Duration: 18.5s   Cost: $0.0563     ┃
┃ Run ID: GQA-RUN-20260222-143052-a1b2                            ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

---

这是什么？

传统的 E2E 测试很脆弱。你编写选择器，它们会失效；你维护脚本，它们会逐渐过时。SpecterQA 采用了不同的方法：AI 视觉模型会查看你的实际 UI，并像人一样浏览操作。

你需要定义用户角色（谁在使用你的应用）和用户旅程（他们想要完成什么）。SpecterQA 的引擎会截取屏幕截图，将其发送给 Claude 视觉模型，获取一个决策（“点击此按钮”“填写此字段”），通过 Playwright 执行该操作，再截取另一张屏幕截图，并重复此过程，直到达成目标或出现问题。

出现问题时，你会获得相关证据：屏幕截图、UX 观察、成本明细，以及按严重程度分类的发现。

安装

SpecterQA 通过 PyPI 分发，要求 Python 3.10 或更高版本。

pip install specterqa

安装后，下载 Playwright 浏览器二进制文件：

specterqa install

如需测试 macOS 原生应用并支持 iOS Simulator，请安装可选的 native 附加组件：

pip install specterqa[native]

如需支持 MCP 服务（将 SpecterQA 集成为 Claude Desktop、Cursor 或其他 MCP 客户端中的工具）：

pip install specterqa[mcp]

运行测试还需要 Anthropic API 密钥：

export ANTHROPIC_API_KEY=sk-ant-...

验证安装：

specterqa --version
specterqa init       # scaffold a sample project
specterqa run -p demo

快速入门

pip install specterqa
specterqa install          # downloads Playwright browsers
specterqa init             # scaffolds .specterqa/ with sample configs
specterqa run -p demo      # runs the sample journey

你需要一个 Anthropic API 密钥：

export ANTHROPIC_API_KEY=sk-ant-...

就是这样。三条命令和一个 API 密钥即可。

工作原理

核心循环很简单：

screenshot --> vision model --> action decision --> execute --> repeat

1. 截屏——Playwright 将当前页面状态捕获为 PNG
2. 决策——Claude 视觉模型接收屏幕截图、用户角色上下文和目标，并返回结构化的 JSON 操作（click、fill、navigate、scroll、keyboard、wait、done 或 stuck）
3. 执行——Playwright 执行操作（点击指定坐标、输入文本、导航到 URL 等）
4. 重复——持续循环，直到达成目标、Agent 陷入停滞或预算耗尽

用户角色的资料会影响 AI 的行为。“精通技术的开发者”和“沮丧的首次使用者”的探索方式各不相同。用户角色的耐心程度、技术熟练度和挫折点都会影响系统提示词。

模型路由有助于降低成本。简单操作（点击、滚动）使用 Haiku，复杂操作（填写表单、初步评估）使用 Sonnet。你也可以将简单操作路由到本地 Ollama 模型（llava:13b），以零 API 成本完成直接的导航操作。

功能

• 基于 Persona 的测试 —— 定义具有背景、目标、痛点和技术熟悉程度的 AI 用户。他们不会只按脚本操作，而是会根据所见内容做出反应。
• 由视觉驱动 —— 无需选择器，也不查询 DOM。AI 会像人一样解读屏幕截图，还能发现基于选择器的测试完全无法发现的视觉和布局问题。
• 通过 YAML 配置 —— 产品、Persona 和用户旅程都使用 YAML 文件。产品经理也能看懂，无需维护代码。
• 预算管控 —— 可设置每次运行、每日和每月的费用上限。达到上限时，执行引擎会立即停止，不会产生意外账单。
• JUnit XML 输出 —— 添加 --junit-xml results.xml，即可接入任何 CI 系统。
• 分级模型路由 —— 使用 Haiku 进行低成本导航，使用 Sonnet 进行复杂推理，也可选择本地 Ollama，以零成本完成简单操作。
• 多平台支持 —— Web 应用（通过 Playwright）、macOS 原生应用（通过 Accessibility API + pyobjc）、iOS Simulator（通过 simctl）。使用相同的 YAML 格式，搭配不同的运行器。
• 证据收集 —— 每次运行都会生成屏幕截图、问题报告、费用明细和结构化 JSON 结果，并全部保存到证据目录中。
• 卡住检测 —— 如果 AI 重复执行相同操作，或界面不再变化，执行引擎会升级到更强的模型；如果仍无效，则会中止。不会陷入无限循环。
• 模板变量 —— 在用户旅程步骤中使用 {{persona.credentials.email}}。运行时会根据 Persona 配置解析变量。
• 前置条件检查 —— 运行测试前确认服务已启动。出现问题时快速失败并给出明确错误，而不是浪费 API 调用。

配置

SpecterQA 使用三种类型的 YAML 配置文件，均位于 .specterqa/ 中：

产品（products/myapp.yaml）

product:
  name: myapp
  display_name: "My Application"
  base_url: "http://localhost:3000"

  services:
    frontend:
      url: "http://localhost:3000"
      health_endpoint: /

  viewports:
    desktop:
      width: 1280
      height: 720
    mobile:
      width: 375
      height: 812

  cost_limits:
    per_run_usd: 5.00

Persona（personas/alex-developer.yaml）

persona:
  name: alex_developer
  display_name: "Alex Chen"
  role: "Full-Stack Developer"
  age: 28
  tech_comfort: high
  patience: medium
  preferred_device: desktop

  goals:
    - "Evaluate the app from a developer's perspective"
    - "Check for common UX anti-patterns"

  frustrations:
    - "Unclear error messages"
    - "Missing loading indicators"

  credentials:
    email: "[email protected]"
    password: "TestPass123!"

用户旅程（journeys/onboarding.yaml）

scenario:
  id: onboarding-happy-path
  name: "Onboarding Happy Path"
  description: "New user signs up, completes onboarding, reaches dashboard."
  tags: [onboarding, critical_path, smoke]

  personas:
    - ref: alex_developer
      role: primary

  preconditions:
    - service: frontend
      check: /
      expected_status: 200

  steps:
    - id: visit_homepage
      mode: browser
      goal: "Navigate to the homepage and verify it loads"
      checkpoints:
        - type: text_present
          value: "Welcome"

    - id: navigate_signup
      mode: browser
      goal: "Find and click the signup link"

    - id: fill_signup_form
      mode: browser
      goal: "Complete the signup form with test credentials"

    - id: verify_dashboard
      mode: browser
      goal: "Verify signup succeeded and the dashboard loads"

完整参考请参阅 docs/configuration.md。

YAML 架构支持

SpecterQA 为产品 YAML 文件提供了 JSON Schema，路径为 schemas/product.schema.json。

# yaml-language-server: $schema=../../schemas/product.schema.json

CI 集成

SpecterQA 专为 CI 构建，默认以无头模式运行，并返回正确的退出码。

# Basic CI run
specterqa run -p myapp --junit-xml results.xml

# Smoke test (runs first scenario only, fast)
specterqa run -p myapp --level smoke --budget 2.00

# JSON output for programmatic consumption
specterqa run -p myapp --output json > results.json

退出码：

• 0 —— 所有测试均通过
• 1 —— 一个或多个测试失败
• 2 —— 配置错误
• 3 —— 基础设施错误（缺少依赖项、无法访问 API）

GitHub Actions、GitLab CI 和 CircleCI 示例请参阅 docs/ci-integration.md。

费用

SpecterQA 使用 Anthropic 的 Claude API。每次运行都会产生费用。以下是预估费用：

模型	用途	输入（每 1M 个 token）	输出（每 1M 个 token）
Claude Haiku 4.5	简单导航	$0.80	$4.00
Claude Sonnet 4	复杂推理	$3.00	$15.00
Ollama llava:13b	本地备用	免费	免费

每次运行的典型费用：

• 3 步冒烟测试：约 $0.30-0.60
• 5 步标准用户旅程：约 $0.50-1.50
• 包含表单的复杂 10 步用户旅程：约 $1.00-3.00

默认预算为每次运行 $5.00。超出预算时，执行引擎会立即停止，不会悄悄超支。你也可以设置每日和每月的上限。

你还可以通过环境变量设置默认预算，避免每次都传入 --budget：

export SPECTERQA_BUDGET=2.00
specterqa run -p myapp          # uses $2.00 budget
specterqa run -p myapp --budget 5.00  # uses $5.00 budget (CLI flag wins)

模型路由有助于控制费用：简单的点击和滚动操作使用 Haiku（每次操作约 $0.01），而填写表单和初始评估使用 Sonnet（每次操作约 $0.03-0.05）。如果你有本地 Ollama 实例，简单操作也可以路由到本地执行，不产生 API 费用。

详细的费用明细和预算策略请参阅 docs/cost-guide.md。

多平台

SpecterQA 不仅限于 Web。同一 persona/journey YAML 格式适用于多个平台：

Web 应用（默认）——使用 Playwright 进行浏览器自动化。

macOS 原生应用——通过 pyobjc 使用 macOS Accessibility API。AI 会读取辅助功能树和屏幕截图，然后通过 AX 操作执行点击和按键操作。

product:
  name: my-mac-app
  app_type: native_macos
  app_path: /Applications/MyApp.app
  bundle_id: com.example.myapp

iOS 模拟器——使用 simctl 截取屏幕截图并模拟触控。适用于在没有实体设备的情况下测试 iOS 应用。

product:
  name: my-ios-app
  app_type: ios_simulator
  bundle_id: com.example.myiosapp
  simulator_device: "iPhone 15 Pro"
  simulator_os: "17.2"

原生应用和模拟器支持需要 native 可选依赖：

pip install specterqa[native]

面向 AI Agent

如果你是 AI Agent，或正在构建 Agent 工具，SpecterQA 提供了可供编程使用的结构化接口。

输出 JSON 的 CLI

specterqa run -p myapp --output json

向 stdout 返回结构化 JSON：

{
  "passed": true,
  "run_id": "GQA-RUN-20260222-143052-a1b2",
  "step_reports": [
    {
      "step_id": "visit_homepage",
      "passed": true,
      "duration_seconds": 12.3
    }
  ],
  "findings": [],
  "cost_usd": 0.4521
}

Python API

from specterqa.config import SpecterQAConfig
from specterqa.engine.orchestrator import SpecterQAOrchestrator

config = SpecterQAConfig()
config.project_dir = Path(".specterqa")
config.products_dir = Path(".specterqa/products")
config.personas_dir = Path(".specterqa/personas")
config.journeys_dir = Path(".specterqa/journeys")
config.evidence_dir = Path(".specterqa/evidence")
config.anthropic_api_key = "sk-ant-..."
config.budget = 5.00
config.headless = True

orchestrator = SpecterQAOrchestrator(config)
report_md, all_passed = orchestrator.run(product="myapp", level="smoke")

联合协议

SpecterQA 提供了一个 protocols.py 模块，其中包含 Python Protocol 类（AIDecider、ActionExecutor），让你可以换用自己的 AI 模型或操作后端：

from specterqa.engine.protocols import AIDecider, Decision

class MyCustomDecider:
    def decide(self, goal, screenshot_base64, **kwargs) -> Decision:
        # Your logic here
        ...

MCP 服务

SpecterQA 附带一个 MCP（Model Context Protocol）服务。任何兼容 MCP 的 Agent（Claude Desktop、Cursor、Cline、自定义 Agent 工具）都可以发现并调用 SpecterQA 作为工具——运行测试、读取结果、管理配置——而无需通过 shell 调用 CLI。

添加到 MCP 客户端配置（claude_desktop_config.json 或同等配置）中：

{
  "specterqa": {
    "command": "specterqa-mcp",
    "args": []
  }
}

可用工具：

工具	描述
specterqa_run	针对产品执行行为测试。同步执行——可能需要 45-300s。会产生 API 费用（默认预算：$5.00）。
specterqa_list_products	列出已配置的产品及其可用的旅程
specterqa_get_results	根据运行 ID 获取先前运行的完整结构化结果
specterqa_init	初始化新的 SpecterQA 项目目录

完整的编程 API 参考和 MCP 集成详情，请参阅 docs/for-agents.md。

API 参考

完整的 API 参考请访问 specterqa.synctek.io/docs。

主要类

类	模块	描述
SpecterQAConfig	specterqa.config	根配置对象。设置项目目录、API 密钥、预算和模型路由偏好。
SpecterQAOrchestrator	specterqa.engine.orchestrator	以编程方式运行的主要入口点。调用 orchestrator.run(product, level) 执行旅程。
AIDecider	specterqa.engine.protocols	Protocol 类。实现此类即可换用自定义视觉模型或决策后端。
ActionExecutor	specterqa.engine.protocols	Protocol 类。实现此类即可换用自定义操作执行后端（例如，替换 Playwright）。
RunReport	specterqa.models	orchestrator.run() 返回的结构化结果。包含步骤报告、发现项和费用明细。
Finding	specterqa.models	运行过程中记录的单个 UX 问题。包含严重程度、步骤 ID、屏幕截图引用和描述。

CLI 参考

命令	描述
specterqa run -p PRODUCT	运行产品的所有旅程
specterqa run -p PRODUCT --level smoke	仅运行带有 smoke 标签的旅程
specterqa run -p PRODUCT --junit-xml results.xml	为 CI 输出 JUnit XML
specterqa run -p PRODUCT --output json	向 stdout 输出结构化 JSON
specterqa init	使用示例配置搭建 .specterqa/ 项目目录
specterqa install	下载 Playwright 浏览器二进制文件
specterqa list	列出已配置的产品和旅程
specterqa results RUN_ID	输出先前运行的完整报告
specterqa-mcp	启动 MCP 服务

MCP 工具

工具	描述
specterqa_run	执行行为测试。参数：product（str）、level（str，可选）、directory（str，可选）。返回 RunReport JSON 对象。
specterqa_list_products	列出所有产品及其配置的用户旅程。无需参数。
specterqa_get_results	根据 run_id 获取之前的运行报告。
specterqa_init	在指定的 directory 中初始化新的 SpecterQA 项目。

有关架构定义、类型存根和联邦协议详情，请参阅 docs/for-agents.md。

安全

目录访问： 未设置环境变量 SPECTERQA_ALLOWED_DIRS 时，SpecterQA MCP 服务允许 specterqa_run 的 directory 参数指向进程可访问的文件系统中的任意路径。在共享或多用户环境中，或者在任何向不可信 Agent 开放 MCP 服务的环境中，都应将此变量设为明确的允许列表：

export SPECTERQA_ALLOWED_DIRS="/home/user/projects:/ci/workspaces"

设置后，MCP 服务会拒绝任何不属于所列前缀之一的 directory 值。这可以缓解 SECURITY_ADVISORY.md（GHSA-SPECTERQA-001）中所述的 MCP 目录遍历风险。

命令注入修复（v0.2.1）： 产品 YAML 服务定义中的 check_command 字段已移除。该字段是严重命令注入漏洞的源头。现在，前置条件检查仅限于 TCP 连通性检查和 HTTP 健康端点检查，确保安全。详情请参阅 SECURITY_ADVISORY.md。

凭据清理： 运行产物（JSON 结果文件、日志输出）在写入磁盘前，会自动从捕获的内容中清除已知的凭据模式，包括 API 密钥、令牌和密码。

报告漏洞： 请勿公开提交安全漏洞问题。请发送邮件至 [email protected]，或查看 SECURITY.md 了解完整的披露政策。

局限性

请坦诚看待它的能力与局限：

• 需要 Anthropic API 密钥。 没有 API 密钥就无法测试。SpecterQA 本身不提供免费套餐。
• 需要付费。 每次运行都会调用 API。一次典型的 3 步用户旅程费用为 $0.30-0.60。预算限制可避免意外支出，但费用始终在产生。
• 视觉模型并非完美。 AI 有时会误读小字、点击错误的元素，或被复杂布局弄糊涂。它表现不错，但并非万无一失。偶尔会出现误报和漏报。
• 不能替代单元测试。 SpecterQA 测试行为层面的 UX 流程，不测试业务逻辑、数据完整性或边界情况处理。请将其与现有测试套件配合使用，而非取而代之。
• macOS 原生测试需要 pyobjc。 specterqa[native] 附加项会引入 pyobjc 软件包（约 200MB）。仅原生 macOS 和 iOS Simulator 测试需要此项。
• Alpha 软件。 版本为 0.4.0。API 可能会变更，文件结构也可能会变更。请预期存在一些不完善之处。
• 目前每个用户旅程仅支持单一角色。 多角色并发测试（例如模拟两名用户之间的聊天）已列入路线图，但尚不支持。
• 难以确定性地复现。 由于 AI 会在运行时做出决策，每次运行的具体操作序列都可能不同。同一用户旅程、同一角色，点击位置也可能略有不同。这是有意为之（可以发现更多问题），但会使精确复现变得棘手。

贡献

欢迎贡献。代码仓库位于 github.com/SyncTek-LLC/specterqa。

git clone https://github.com/SyncTek-LLC/specterqa.git
cd specterqa
pip install -e ".[dev]"
pytest

开始大型 PR 之前，请先提交 issue。我们希望先讨论方案。

许可证

MIT —— 详情请参阅 LICENSE。

---

由 SyncTek LLC 构建。