DeepEval + Eval‑Harness 完整讲解（结合 Playwright UI 自动化例子）

一、基础概念

1）什么是 Eval‑Harness（评测脚手架 / 评测工装）DeepEval

Eval‑Harness：评测执行的整套基础设施 通俗类比： 传统自动化：pytest + selenium = 测试 harness； AI 系统：DeepEval 就是帮你搭建 AI 应用 Eval‑Harness 的工具。

Harness 做 4 件核心事：

1. 批量加载测试数据集（golden 测试用例集合）
2. 循环调用你的 Agent / 业务系统执行每一条 case
3. 采集输入、输出、完整 trace（思考、工具调用、中间状态）
4. 跑多组 Metrics 打分，输出报告、判断 pass/fail，支持 CI 阻断

区分：

• lm‑evaluation‑harness：测基础大模型能力基准（MMLU、GSM8K）
• DeepEval Eval‑Harness：测你自己开发完的业务 Agent/LLM 应用（你的 prompt、你的工具、你的业务逻辑），不是测底座模型本身。

2）DeepEval 是什么

LLM/Agent 的pytest，LLM‑as‑Judge 评测框架稀土掘金。 核心 4 大组件：

1. LLMTestCase：单条测试用例（输入、期望、上下文、工具调用记录、元数据）
2. Metric 指标 ：打分器（0‑1 分，设置阈值 threshold，低于阈值判定失败）
   • Agent 专用：TaskCompletenessMetric任务完成度、ToolCorrectnessMetric工具调用正确性、PlanAdherenceMetric是否遵守规划
   • RAG：AnswerRelevancy、Faithfulness 防幻觉
   • 自定义 G‑Eval：自然语言写评判规则
3. Trace：完整运行轨迹：思考、工具入参出参、中间状态（Agent 调试最重要）
4. Harness 执行引擎：批量跑 case、断言、输出报告、接入 CI/CD

传统自动化：代码断言assert actual == expected； AI 评测：assert_test(test_case, metrics=[xxx(threshold=0.8)])，由大模型裁判做模糊语义评判DeepEval。

3）本次示例业务场景

AI Agent 调用 Playwright 做 UI 自动化测试 业务：Agent 接收自然语言指令，调用 Playwright 打开浏览器操作网页，执行登录、搜索；

• Playwright：负责真实浏览器 DOM 操作（传统 UI 自动化，硬断言：元素、文本、截图）
• DeepEval Harness：评测这个 AI Agent 到底做的对不对，不只看 DOM 是否成功，还要评判：
  1. Agent 是否理解用户原始意图？
  2. Agent 调用 Playwright 工具序列是否合理？有没有幻觉调用不存在选择器？
  3. 是否完整完成业务任务？

重点：Playwright 做确定性 UI 动作执行；DeepEval 做AI Agent 行为质量评测；两者职责完全分开。

二、企业级 Harness 整体架构（生产）

┌────────────测试数据集（csv/json golden case库）─────────┐
│ 输入指令 | 业务期望 | 页面预置条件 | 元数据标签（冒烟/回归）│
└───────────────────┬────────────────────────────────────┘
                    ▼
┌────────────Eval‑Harness(DeepEval)────────────┐
│ 1.循环取出每条LLMTestCase                     │
│ 2.调用你的Agent业务逻辑                       │
│     └── Agent内部调用 Playwright（打开浏览器）│
│ 3.采集完整Trace：prompt、思考、工具调用、截图 │
│ 4.执行一组Metrics打分                        │
│ 5.断言阈值，生成报告（csv/html）              │
│ 6.CI：失败则阻断流水线                       │
└────────────┬─────────────────────────────────┘
             ▼
      失败样本入库，人工Review，回流扩充测试集

企业 Harness 不是写一个脚本跑一次；而是可复用、可回归、CI 集成、样本持续迭代的整套评测工装。

关键边界

1. Playwright 负责：浏览器点击、输入、DOM 硬断言、截图；
2. DeepEval 不控制浏览器，只评测 Agent 的行为与输出质量；
3. 可以组合：Playwright 给出页面结果，喂给 DeepEval 做语义层面评判。

三、完整可运行示例代码

环境安装

pip install deepeval playwright pytest
playwright install chromium

.env配置（裁判 LLM，可以用 OpenAI / Claude / DeepSeek）

OPENAI_API_KEY=sk-xxx

文件 1：ui_agent.py（AI Agent，内部封装 Playwright）

Agent 接收自然语言任务，调用 playwright 执行浏览器操作，返回结果 + 轨迹

from playwright.sync_api import sync_playwright
from typing import Dict, Any

class PlaywrightUIAgent:
    def __init__(self):
        self.trace_steps = []  # 记录Agent每一步动作，供deepeval评测

    def run_task(self, user_instruction: str) -> Dict[str, Any]:
        """模拟Agent接收自然语言指令执行UI自动化，这里简化演示搜索任务"""
        self.trace_steps.clear()
        result_summary = ""
        with sync_playwright() as p:
            browser = p.chromium.launch(headless=True)
            page = browser.new_page()

            # =========模拟Agent思考+动作（真实项目这里交给大模型生成playwright动作）=========
            self.trace_steps.append({"thought":"需要访问百度首页","action":"goto","param":"https://www.baidu.com"})
            page.goto("https://www.baidu.com")

            self.trace_steps.append({"thought":"定位搜索框输入DeepEval","action":"fill","param":"#kw,DeepEval"})
            page.locator("#kw").fill("DeepEval")

            self.trace_steps.append({"thought":"点击搜索按钮","action":"click","param":"#su"})
            page.locator("#su").click()
            page.wait_for_timeout(2000)

            page.screenshot(path="./screenshot_search.png")
            title = page.title()
            result_summary = f"页面标题:{title},已执行搜索DeepEval，完成页面截图"
            browser.close()

        return {
            "user_input": user_instruction,
            "agent_summary": result_summary,
            "tool_trajectory": self.trace_steps,  # 动作轨迹给deepeval做轨迹评测
            "screenshot_path": "./screenshot_search.png"
        }

文件 2：test_harness_playwright.py DeepEval Harness 评测脚本

这就是企业 Harness 核心：批量加载 case，调用 Agent，执行多维度 metrics 打分

import os
from dotenv import load_dotenv
from deepeval import assert_test
from deepeval.test_case import LLMTestCase
from deepeval.metrics import (
    TaskCompletenessMetric,
    ToolCorrectnessMetric,
    AnswerRelevancyMetric
)
from ui_agent import PlaywrightUIAgent

load_dotenv()

# 初始化Agent
ui_agent = PlaywrightUIAgent()

# ---------------------- 1、业务Golden测试数据集（企业放到csv/json管理）----------------------
test_dataset = [
    {
        "input": "请打开百度，搜索DeepEval，完成页面搜索",
        "expected_output": "完成DeepEval关键词搜索，成功加载搜索页面",
    }
]

# ---------------------- 2、定义评测指标集（企业根据业务定制阈值）----------------------
metrics = [
    # 任务完成度：是否完成用户给的原始任务，阈值0.8，低于即失败
    TaskCompletenessMetric(threshold=0.8),
    # 工具调用正确性：评判Agent的playwright动作序列是否合理、参数是否合法
    ToolCorrectnessMetric(threshold=0.75),
    # 回答相关性：Agent输出摘要是否匹配用户输入
    AnswerRelevancyMetric(threshold=0.8)
]

# ---------------------- 3、Harness执行逻辑：循环跑全部case ----------------------
def run_eval_harness():
    for item in test_dataset:
        print(f"\n======执行case input:{item['input']}======")
        # 调用Agent，内部会执行Playwright浏览器操作
        agent_result = ui_agent.run_task(user_instruction=item["input"])

        # 组装DeepEval测试用例，传入Agent完整轨迹
        test_case = LLMTestCase(
            input=item["input"],
            actual_output=agent_result["agent_summary"],
            expected_output=item["expected_output"],
            # trajectory 传入Agent工具调用序列，供ToolCorrectness做轨迹级评测
            trajectory=agent_result["tool_trajectory"]
        )
        # 执行评测，内部调用LLM‑as‑Judge打分；不满足阈值抛出异常，CI流水线可捕获
        assert_test(test_case, metrics=metrics)
        print(f"case pass, summary:{agent_result['agent_summary']}")

if __name__ == "__main__":
    run_eval_harness()

运行 harness：

python test_harness_playwright.py
# 或者deepeval命令行运行，生成html报告
deepeval test run test_harness_playwright.py

四、运行之后发生了什么（重点理解）

1. Harness 取出测试用例，交给PlaywrightUIAgent；
2. Agent 执行浏览器操作，拿到页面结果，记录完整工具调用轨迹 trajectory；
3. DeepEval 把input、actual_output、expected_output、trajectory交给裁判大模型；
4. ToolCorrectnessMetric会检查：
   • Agent 动作序列是否符合业务逻辑？
   • 选择器、参数是否有幻觉错误（比如写不存在 DOM 选择器）
5. TaskCompletenessMetric评判：用户要求的 "搜索 DeepEval" 这个目标到底有没有达成；
6. 全部指标分数≥阈值 → pass；任意指标低于阈值抛出异常，CI 流水线直接失败。

对比传统 Playwright： Playwright 只能判断：元素存在？页面 title 等于 xxx？ DeepEval 可以判断：Agent 理解我的意图吗？动作序列逻辑合理吗？有没有做多余错误操作？ 这是 AI 自动化测试和传统 UI 自动化最大区别。

五、企业 Harness 生产落地改造要点

上面是最小 demo，企业环境要做这几件事：

1. 测试数据集外部化：不要写死在代码，读取 csv、json，管理 golden 样本库，持续沉淀回归 case；
2. 环境隔离：Playwright 指向测试环境，禁止打生产网页；headless 模式运行在 CI 容器；
3. 指标阈值调优：不同业务设置不同 threshold，不要全部 0.8 一刀切；
4. 失败样本自动落库：把输入、trace、截图、分数保存，定期人工 review，把 bad case 回流进数据集；
5. 区分两层断言
   • 底层：Playwright 硬断言（DOM、截图比对，快速失败）；
   • AI 层：DeepEval 做 Agent 行为语义评测；
6. 替换裁判模型：企业内网可以替换为 Ollama、Azure OpenAI，不要用公网模型做敏感业务评判；
7. 增加自定义 Metric (G‑Eval)：业务特有的评判规则，用自然语言写评判标准，不用写复杂代码。

六、常见误区

• 误区： DeepEval 替代 Playwright

不替代。Playwright 负责真实浏览器执行；DeepEval 评测AI Agent 的行为质量。两者协同。

• 误区： Eval‑Harness 就是跑几个测试用例脚本

Harness 是整套工程化体系：数据集管理、trace 采集、批量执行、打分、报告、CI 阻断、样本回流。一次性脚本≠harness。

• 误区：全部靠 LLM‑as‑Judge 做所有断言

优先硬断言（Playwright DOM、响应码）；AI 评判用来处理模糊、意图、规划、工具调用合理性场景。