buer2233/jev-ui-test

简体中文 · English

Jev 决策模型驱动的 UI 自动化测试框架：一句自然语言写用例、跑成回归，每一步决策都说得清为什么。

用例用自然语言写（中文即可），pytest 执行，Allure 出报告。执行它的是浏览器 agent，而替它做每一步决定的 是 Jev 决策模型（TypeSafe System One，当前最新的一版）：它不生成「下一步该做什么」 这句话，而是在候选元素里直接打分，把「操作 + 目标」和带校准的概率一起返回。所以没有选择器、 没有站点脚本、没有预置的字段值。

它 fork 自 browser-use/jev-ultrafast（MIT）： 上游是 Browser Use 的浏览器 agent 内核，本仓库把它改造成跑测试的框架——不重写内核，只在外围加一层。

效率：实测每个操作决策中位 458 ms，32 次操作决策里 30 次在 1 秒以内（p90 919 ms）； 而改造前用大模型直接驱动执行时，单个操作判断经常要 4–5 秒、个别到 10 秒。

🎬 演示视频与报告 · 📊 在线报告 · 快速开始 · Jev 模型介绍和使用教程 · 框架与改造详解 · 效率实测

「4–5 秒 / 10 秒」是改造前的使用经验值，本仓库没有机器可读证据；458 ms 这一侧全部来自随仓库 分发的演示报告，可逐步核对。口径见效率实测。

「大模型直接驱动」是把截图 / DOM 丢给一个通用大模型，让它输出下一步动作——选择器、坐标或一句自然语言。 这条路能走通，但每一步都在赌模型这次没编错：

Jev 在其中起的关键作用——它把「看页面 → 决定下一步」从生成换成了打分：

1. 动作空间是闭合的：模型只能在当次快照出的候选里选，模型输出永远不会变成选择器、坐标或可执行 JS；
2. 一次往返出两个决策：「操作 + 目标」在同一请求里返回（推测式 fan-out），只有被选中操作对应的那个目标头会被执行；
3. 概率可编程：带校准的概率让框架能把判定权留在代码里——语义断言拿它当证据，阈值由人定；
4. 可审计：每一步都是索引 + 概率 + 耗时的结构化记录，能逐行走查「它当时为什么这么点」。

↑ 60 秒动图（报告首页 → 用例详情 → 执行录屏与步骤时间轴）；▶ 观看完整录屏（3 分 57 秒 · 1452×680 · 7 MB）。

📊 在线查看完整执行报告 → —— 一次真实项目的执行报告 （3 条用例全绿 · 3 passed），对应 cases/e9/workflow_design.yaml； 报告源文件随仓库分发在 examples/allure-report/。

怎么在本地看这份报告、怎么自己产出一份，见快速开始第 4 步。

1. 装

git clone https://github.com/buer2233/jev-ui-test.git
cd jev-ui-test
uv sync
cp .env.example .env        # 填入 TYPESAFE_API_KEY 与 TEXT_MODEL_API_KEY

还没有 Jev 的 API Key？见 Jev 模型介绍和使用教程——注册就送 5 美元额度，够把演示用例跑好几遍。

需要 Python ≥ 3.12，Chrome 通过 Browser Harness 连接（uv sync 已装）。连不上时跑 uv run browser-harness --doctor 并按提示允许远程调试。

Windows 上起不来时：导入期报 UnicodeDecodeError / codec can't decode byte，是中文 Windows 的区域编码问题（不是依赖问题）；报 DevToolsActivePort not found，多半是 没有可连接的 Chrome（不是权限没开）。排查步骤见 .claude/skills/run-jev/SKILL.md。

2. 配（只有 E9 环境才需要）

cp config.example.json config.json    # 填 base_url 与 admin / employee1~5 账号

⚠️ config.json 已被 .gitignore 忽略，且必须保持忽略——本仓库是公开仓库， 真实账号与内网地址提交上去就是凭据泄漏。入库的只有占位模板 config.example.json。

3. 写用例（cases/**/*.yaml，用户只写自然语言）

• 手上已有功能测试用例 → 用 /nl-case-author，它把源材料转成下面的 YAML；
• 想直接看一条能跑的 → examples/weaver_site_tour.yaml， 公开网站上跑、不需要 E9 环境也不需要 config.json（展示副本，执行源在 cases/demo/）。

cases:
  - id: e9-workflow-add-bym
    name: 新建 BYM专用测试 流程并提交
    url: "{{ base_url }}/wui/index.html#/main/workflow/add"
    login: employee1                 # 接口登录后把 cookie 注入浏览器，用例免登录开跑
    goal: |
      1. 打开新建流程页面，页面上按分组列出了各种流程名称；
      2. 点击「BYM专用测试」，它会打开该流程的表单页面；
      3. 在「签字意见」里输入「同意流程」；
      4. 点击「提交」。
      提交成功后表单页会自动关闭，回到新建流程列表页；此时停止。
    expect_mode: and                 # 多断言合成口径：and / or / min_pass，逐用例决定
    expect:
      - type: ai                     # 语义断言：Jev 的 noul 给概率，阈值比较在代码里
        claim: 页面上显示的是新建流程的流程名称列表
      - type: text_not_contains      # 确定性断言
        value: "流转设定"
      - type: url_contains
        value: "/wui/index.html#/main/workflow/add"

两条硬约束（AGENTS.md 有完整版）：断言只对【终局页面】求值； agent 没有「后退」动作，站点内换页要靠页面上的导航。

4. 跑 + 看报告

看线上那份（随仓库分发的真实执行报告，3 条用例全绿）：https://buer2233.github.io/jev-ui-test/

本地跑一遍并出报告：

uv run pytest                     # 默认离线，自然语言用例不会跑：143 passed，6 skipped

# 显式请求才会执行（会调付费 API 并接管一个 Chrome 标签页）
uv run --env-file .env pytest tests/test_nl_cases.py --nl --reruns 1 \
  --alluredir=report/allure-results
allure generate report/allure-results -o report/allure-report --clean
uv run python scripts/install_report_plugin.py report/allure-report   # 二开插件：录屏 + 步骤时间轴
allure open report/allure-report

看仓库里那份已生成的（不用跑用例，allure CLI 需要 Java）：

uv sync
allure open examples/allure-report

别直接双击 index.html（浏览器会拦本地文件请求），也别用 python -m http.server 代替 ——它不支持 HTTP Range，录屏进度条拖不动。

也可以用 /nl-case-run：你说「测一下新建流程」或「跑 cases/e9 下的用例」，它负责挑用例、 执行、出报告；如果该功能还没写成用例，会先转 /nl-case-author。

浏览器 agent 内核由上游维护，本仓库是 browser-use/jev-ultrafast 的 fork。

• Linux do