youqu-ai 2.17.3

YouQu（有趣），一个使用简单且功能强大的自动化测试框架。

深度社区：linuxdeepin | deepin-community

欧拉社区：openEuler

龙晰社区：openAnolis

官方文档：https://youqu.uniontech.com

欢迎加入 YouQu官方兴趣小组

YouQu（有趣）是统信公司（Deepin/UOS）开源的一个 Linux 操作系统的自动化测试框架，支持多元化元素定位和断言、用例标签化管理和执行、强大的日志和报告输出等特色功能，同时完美兼容 X11、Wayland 显示协议，环境部署简单，操作易上手。🔥

YouQu 能做什么

• 💻 Linux 桌面应用 UI 自动化测试
• 🌏 Web UI 自动化测试
• 🚌 Linux DBus 接口自动化测试
• 🚀 命令行自动化测试
• 🕷️ HTTP 接口自动化测试

快速开始

安装

从 PyPI 安装:

$ sudo pip3 install youqu-ai

验证安装：youqu --help 列出所有子命令，youqu --version 显示版本号。 如果遇到 error: externally-managed-environment，加上 --break-system-packages（虚拟环境则无需）。 升级或重装时需加 --force-reinstall，否则同版本号会被 pip 跳过。

pip3 install youqu-ai

export PATH=$PATH:$HOME/.local/bin

创建项目

您可以在任意目录下，使用 youqu-startproject 命令创建一个项目：

$ youqu-startproject my_project

注意：所有命令不要以 root 用户执行！

如果 youqu-startproject 后面不加参数，默认的项目名称为：youqu ；

编写测试用例

YouQu 支持 YAML 和 Python 两种方式编写测试用例，同一个 run 命令统一执行：

youqu-startproject my_project
          |
   cd my_project
          |
   +------+-------+
   |              |
YAML 路径      Python 路径
声明式/AI友好   传统PO模式
   |              |
youqu make    youqu manage.py
   <name>      startapp <name>
   |              |
autotest/yaml/ apps/autotest_xxx/
├── elements   ├── widget/
│   .yaml      ├── case/
└── test_*.    └── ui.ini
    yaml
   |              |
   +------+-------+
          |
youqu manage.py run

YAML 路径（推荐 AI 用户）

声明式、无需编写 Python 代码，AI 客户端可直接通过 MCP 工具获取 AT-SPI 元素树并生成 YAML 用例：

$ youqu make my_app                    # 生成 autotest/，默认 YAML 格式
$ youqu make my_app --format all       # 同时生成 YAML + Python

YAML 用例将所有 UI 元素集中注册在 autotest/yaml/elements.yaml，测试用例通过 ref 引用元素，使用 action 声明操作、assert 声明断言。

Python 路径（传统 PO 模式）

适合需要复杂逻辑、自定义断言的场景，遵循 Page Object 设计模式：

$ youqu manage.py startapp autotest_deepin_some      # 创建 APP 工程（Python）
$ youqu make my_app --format py                       # 或通过 make 生成

自动创建的 APP 工程：

my_project
├── apps
│   ├── autotest_deepin_some
│   │   ├── widget/          # 元素操作层
│   │   ├── case/            # 测试用例层
│   │   ├── ui.ini           # 控件坐标配置
│   │   └── xxx.csv          # 标签管理

继承链：Src → BaseWidget → XxxWidget（方法层），AssertCommon → XxxAssert → BaseCase → TestXxx（用例层）。

在你的远程 Git 仓库中，只需要保存 APP 工程这部分代码即可。 apps 目录下可以存在任意多个 APP 工程。

系统依赖

YouQu 需要以下系统包：

RHEL/openEuler: 使用对应的包名，如 java-11-openjdk-headless、python3-tkinter、opencv 等。

一键部署脚本：

$ cd my_project
$ bash env.sh
# 默认密码: 1；
# 指定密码: bash env.sh -p ${my_password}；
# 或修改 setting/globalconfig.ini 中 PASSWORD 配置项。

env.sh 会自动安装系统依赖、pip 包、配置 SSH 和辅助功能。

桌面环境要求: 需要运行中的 X11 或 Wayland 桌面会话（DISPLAY=:0），~/.Xauthority 文件存在，辅助功能已开启。

可选功能依赖：

Web Spec 自动化测试

Web Spec 是基于 Playwright 的确定性 Web UI 测试能力，使用 YAML 描述页面入口、操作步骤和断言，不依赖 AI 推理执行。它适合把稳定的 Web 页面流程沉淀为可重复运行的自动化用例。

安装依赖

源码开发环境可安装 Web UI 额外依赖并安装浏览器：

pip install -e ".[webui]"
playwright install chromium

已安装 wheel 的环境可使用：

pip install "youqu-ai[webui]"
playwright install chromium

配置文件

可以先初始化一份默认配置：

youqu web-spec init web_spec.yaml
# 如需覆盖已有文件：youqu web-spec init web_spec.yaml --force

Web Spec 配置可写成扁平结构，也兼容 target、engine、paths 分组。示例见 examples/web_spec/web_spec.yaml：

base_url: http://localhost:5173
entry_route: /
headless: true
viewport:
  width: 1280
  height: 720
report_dir: report/web_spec

常用字段：

Spec 文件结构

一个最小 Web Spec YAML：

id: login-smoke
title: 登录页冒烟测试
module: 认证
tags: [smoke]
entry_page: /login
steps:
  - description: 检查登录按钮
    assertions:
      - type: visible
        locator:
          strategy: text
          value: 登录
          exact: true

常用顶层字段：

steps 的执行顺序以 YAML 列表顺序为准，报告中的 Step order 会自动从 1 开始生成；编写用例时不需要维护 order 字段。

Locator

当前支持的 locator 策略：

交互动作默认要求 locator 唯一匹配。确实需要取第一个匹配元素时，可以显式设置：

locator:
  strategy: text
  value: 删除
  exact: true
  first: true

Action

当前支持的 action：

Action 可通过 settle_after 声明操作后的稳定等待：

- type: click
  locator: {strategy: text, value: 提交, exact: true}
  settle_after:
    wait_for_text: 提交成功
    settle_ms: 300

Assertion

当前支持的 assertion：

示例：

assertions:
  - type: text_contains
    locator: {strategy: bem_css, value: .message:last-child}
    expected:
      - 你好
      - 欢迎

属性断言和文本序列断言示例：

assertions:
  - type: attribute_contains
    locator: {strategy: css, value: button.submit}
    attribute: aria-label
    expected: 提交
  - type: text_sequence
    locator: {strategy: css, value: .assistant-item}
    expected: [写作, 翻译, 总结]
    mode: contains_order

CLI 使用

初始化配置文件：

youqu web-spec init web_spec.yaml
youqu web-spec init path/to/web_spec.yaml --force

运行单个文件或目录：

youqu web-spec run examples/web_spec/specs --config examples/web_spec/web_spec.yaml

只加载校验并输出用例统计，不启动浏览器：

youqu web-spec run examples/web_spec/specs --config examples/web_spec/web_spec.yaml --dry-run

常用运行参数：

youqu web-spec run path/to/spec_or_dir --headed --verbose
youqu web-spec run path/to/spec_or_dir --report-dir report/web_spec/manual
youqu web-spec run path/to/spec_or_dir --no-screenshot

列举和筛选用例：

youqu web-spec list examples/web_spec/specs
youqu web-spec list examples/web_spec/specs --module 聊天区
youqu web-spec list examples/web_spec/specs --tag smoke

重建索引：

youqu web-spec index examples/web_spec/specs

运行 suite 目录，按 suite.yaml 声明顺序执行多个 case：

youqu web-spec suite examples/web_spec/smoke --config examples/web_spec/web_spec.yaml --dry-run
youqu web-spec suite examples/web_spec/smoke --config examples/web_spec/web_spec.yaml

suite 必须以文件夹组织，文件夹内必须包含 suite.yaml 或 suite.yml，顶层使用 specs 声明 case 列表；普通 case 顶层使用 steps。外部 *.suite.yaml / *.suite.yml 不再作为 suite 入口。run 执行当前路径下的 suite 和未被 suite 引用的独立 case，避免重复执行；list/index 会同时展示 case 和 suite；suite 命令用于只执行单个 suite 目录或目录内的 suite.yaml。

suite 用于把一个大流程拆成多个小 case，执行时会在同一个浏览器上下文、同一个 page 上按 specs 顺序接续运行。suite setup 会在共享 page 上执行；suite 开始时默认进入第一个 spec 的 entry_url / entry_page，后续 spec 不会在 case 边界自动重新导航。每个 spec 的入口字段仍用于单独运行该 spec，若 suite 中间需要跳转，请在 spec setup 或 steps 中显式声明。suite 内默认跳过单个 spec 的 teardown，最终清理由 suite-level teardown 负责，避免中间 case 清理 cookie 或恢复入口导致状态断裂。报告会按 suite 下的具体子用例分别生成，single_case: true 也只影响执行接续语义，不会把多个子用例揉成一个报告记录，方便定位到底是哪个子用例失败；汇总报告会记录 suite 元数据、case 顺序、source、fast_fail、timeout 和 suite 错误。

id: web-spec-smoke
name: Web Spec 示例冒烟套件
fast_fail: true
specs:
  - specs/01.侧边栏布局验证.yaml
  - specs/02.标题栏主菜单验证.yaml

静态检查 spec 和 suite 质量，不启动浏览器：

youqu web-spec check examples/web_spec/specs
youqu web-spec check path/to/spec_or_dir

check 会检查 YAML/schema、suite 命名、兼容字段、脆弱 selector、过宽 text/css locator、长固定等待、URL 断言冗余 locator 等问题；存在 ERROR 时命令返回非 0，只有 WARN 时仍返回 0。

报告输出

执行后会在 report_dir 下生成：

report/web_spec/<timestamp>/
├── summary.json
├── summary.html
└── <spec-id>/
    ├── report.json
    ├── report.html
    └── step_<order>.png

summary.* 是批量运行汇总，单个 spec 目录下保存步骤、action、assertion、截图和错误信息。suite 运行时，每个子用例都会生成独立的 <spec-id>/report.*，汇总表的 Suite 列用于标识其所属 suite。

索引行为

youqu web-spec list <spec_dir> 会读取 <spec_dir>/index.yaml。如果索引不存在，或索引版本低于当前 WebSpecIndex.INDEX_VERSION，命令会自动重建并写回 index.yaml。

如果希望显式刷新索引，可执行：

youqu web-spec index <spec_dir>

常见错误

运行测试

在项目根目录下有一个 manage.py ，它是执行器入口，提供了本地执行、远程执行等的功能。

本地执行

$ youqu manage.py run

autotest/ 项目（通过 youqu make 生成的 YAML/Python 项目）也可以直接使用 youqu run，更轻量，无需 manage.py。

在一些 CI 环境下使用命令行参数会更加方便：

$ youqu manage.py run -a apps/autotest_deepin_some -k "xxx" -t "yyy"

更多用法可以使用 -h 或 --help 查看。

通过配置文件 setting/globalconfig.ini 也可以配置执行的各项参数。

远程执行

远程执行就是用本地作为服务端控制远程机器执行，远程机器执行的用例相同。

使用 remote 命令：

$ youqu manage.py remote

生成报告

测试执行后会生成 Allure 原始数据（autotest/report/），使用 youqu report 转为 HTML：

$ youqu report                  # 生成 HTML 到 autotest/report/allure_html/
$ youqu report --clean          # 清除旧报告后重新生成
$ youqu report --serve          # 生成后启动 HTTP 服务，浏览器直接查看

需要 Java 运行环境（openjdk-11-jdk-headless），youqu doctor 可自动安装。

AI 集成

MCP Server

YouQu 内置 MCP (Model Context Protocol) Server，将桌面 UI 自动化能力暴露为 MCP 工具， 使 AI 客户端（Claude、OpenCode 等）能够直接操控测试机上的桌面应用。

功能概览

启动 MCP Server

YouQu 安装后 MCP Server 即刻用：

VLM 配置

编辑 setting/globalconfig.ini，启用 VLM 并配置后端 API：

[vlm]
VLM_ENABLED = true
VLM_BASE_URL = https://api-inference.modelscope.cn/v1/
VLM_MODEL = Qwen/Qwen3-VL-8B-Instruct
VLM_API_KEY = your-api-key

VLM 需要 OpenAI 兼容的视觉语言模型 API（Ollama、ModelScope、vLLM 等），框架不内置模型。

启动 MCP Server

stdio 模式（本地子进程）：

youqu mcp

适用于本地 AI 客户端通过 stdio 管道连接。

Streamable HTTP 模式（远程连接）：

youqu mcp --transport http --host 0.0.0.0 --port 8000

CLI 参数说明：

客户端连接配置

Claude（原生支持 HTTP）：

claude mcp add --transport http youqu http://192.168.1.100:8000/mcp

OpenCode — 在项目 opencode.json 中配置 MCP server：

{
  "mcp": {
    "youqu-mcp": {
      "enabled": true,
      "type": "remote",
      "url": "http://127.0.0.1:8066/mcp"
    }
  }
}

连接远程测试机时改为对应的 IP 和端口。

SSH 隧道（安全内网连接）：

无需在测试机暴露端口，通过 SSH 隧道转发：

ssh -L 8000:localhost:8000 user@test-machine

然后本地客户端连接 http://127.0.0.1:8000/mcp。

客户端兼容矩阵

YAML 批量执行

MCP Server 支持异步批量执行 YAML 用例，AI 客户端无需等待全部完成：

典型流程：

yaml_list_tests(app="deepin-music", module="播放")
    → 筛选需要执行的用例
yaml_run_batch(test_ids="test_001,test_002", batch_size=5)
    → job_id: "a1b2c3d4"
yaml_get_status(job_id="a1b2c3d4")  # 每 5s 轮询
    → {status: "running", progress: "batch 2/3"}
    → {status: "completed", result: {passed: 10, failed: 1}}

安装技能

YouQu 内置 AI 技能文件，供 Claude、OpenCode 等 AI 客户端使用。

安装方式一：通过 youqu doctor 交互式安装：

$ youqu doctor

doctor 会在所有检查完成后，检测到内置技能文件并提示您选择 AI 客户端， 自动将技能安装到对应目录：

安装方式二：手动复制：

# 查找技能文件路径
python3 -c "import youqu; from pathlib import Path; print(Path(youqu.__file__).parent / 'skills')"

# 复制到对应客户端目录
cp -r $(python3 -c "import youqu; from pathlib import Path; print(Path(youqu.__file__).parent / 'skills')")/* ~/.claude/skills/

安装后重启 AI 客户端即可加载技能。

常用命令

供 AI 客户端和 CI 环境使用的 CLI 命令：

开发者指南

编译安装

从源码构建和安装：

$ git clone https://github.com/linuxdeepin/youqu.git
$ cd youqu
$ python3 -m build
$ pip3 install dist/youqu_ai-*.whl

需要 python3 -m pip install build 安装构建工具。

发布到 PyPI

发布需要 build 和 twine 工具：

$ pip3 install --upgrade build twine

~/.pypirc 配置文件示例：

[pypi]
  username = __token__
  password = pypi-你的-PyPI-Token

[testpypi]
  username = __token__
  password = pypi-你的-TestPyPI-Token

Token 在 https://pypi.org/manage/account/token/ 和 https://test.pypi.org/manage/account/token/ 生成。

发布流程（推荐先发到 TestPyPI 验证）：

# 1. 清理旧构建产物
$ rm -rf dist/ build/ *.egg-info

# 2. 构建
$ python3 -m build

# 3. 检查包质量
$ twine check dist/*

# 4. 先发到 TestPyPI 验证
$ twine upload --repository testpypi dist/*

# 5. 验证安装
$ pip install --index-url https://test.pypi.org/simple/ --no-deps youqu-ai

# 6. 确认无误后，发布到正式 PyPI
$ twine upload dist/*

开发环境

使用开发模式部署，直接 pip 安装依赖（不使用虚拟环境）：

$ bash env.sh -D

代码检查

$ ruff check .     # lint
$ ruff format .    # format
$ src/utils/pylint.sh apps/autotest_xxx   # pylint HTML 报告

单元测试

$ python -m pytest -c pytest-tests.ini tests/

贡献

贡献文档

开源许可证

YouQu 在 GPL-2.0 下发布。