1. 项目概述：当大模型开始“动手”操作你的软件

最近在折腾一个内部工具链的自动化测试，传统的脚本录制回放和API测试已经覆盖了大部分场景，但总有一些边边角角的UI操作，比如一个配置项的下拉框联动、一个富文本编辑器的内容粘贴、或者一个需要OCR才能识别的验证码区域，写起来特别费劲。就在琢磨有没有更“聪明”的办法时，看到了Qwen3-14B这类大语言模型在工具调用和代码生成上的进展，一个想法冒了出来：能不能让大模型来“看”界面、“想”操作、“执行”步骤，最后再“判断”结果对不对？这就是“OpenClaw自动化测试”项目的核心——用Qwen3-14B作为大脑，驱动一个自动化工具（比如Selenium、Playwright）去执行UI操作，并完成结果的智能验证。

这听起来有点像RPA（机器人流程自动化），但底层逻辑完全不同。传统RPA是基于规则和元素定位的，而我们的方案是基于大模型对界面和任务的自然语言理解。它的价值在于应对那些 变化频繁、逻辑复杂、或难以用固定规则描述 的UI测试场景。比如，产品经理临时加了个“根据用户输入动态生成表单字段”的功能，传统的自动化脚本可能就得大改定位逻辑，而基于大模型的方案，你只需要告诉它：“在新增的动态表单里，找到‘联系方式’字段并填入我的邮箱。” 模型能理解这个指令，并尝试在页面上找到最符合描述的输入框。

这个项目适合谁呢？首先是测试开发工程师，尤其是面对大量C端产品UI测试，苦于维护成本高昂的团队。其次是前端开发者，可以用它来快速验证自己开发页面的交互流程是否通畅。甚至对运维同学来说，一些内部管理后台的日常巡检任务，也可以尝试用这种方式自动化。接下来，我会拆解整个方案的思路、核心细节、实操步骤以及我趟过的那些坑。

2. 整体架构与核心组件选型

要让大模型驱动UI自动化，不是一个模型就能包打天下的。我们需要一个清晰的架构，把“感知-决策-执行-验证”这个闭环跑通。整个系统可以分成四个核心层。

2.1 系统分层与数据流设计

最底层是 执行与环境层 。这里需要一个能真实操控浏览器或应用的工具。我选择了Playwright，而不是更老牌的Selenium。原因有几个：一是Playwright对现代Web技术的支持更好，比如能自动等待元素稳定，处理Shadow DOM更顺手；二是它的录制功能生成的代码更干净；三是它支持多浏览器（Chromium, Firefox, WebKit）且API设计一致。我们通过Playwright启动一个浏览器实例，作为大模型操作的“手”。

中间层是 感知与状态获取层 。这是关键。大模型不能直接“看”浏览器，我们需要把浏览器当前的状态“翻译”成模型能理解的信息。主要包括两部分：

1. 页面结构快照 ：获取当前页面的HTML DOM树。但全量HTML太臃肿，需要精简，只保留可视区域的主要元素及其关键属性（如id, class, name, role, aria-label, placeholder, text等）。可以使用Playwright的 page.evaluate() 注入脚本，提取结构化数据。
2. 视觉信息补充 ：对于一些纯CSS渲染的图标、状态（如勾选状态、加载动画），或者验证码这类图片内容，HTML信息不足。我们需要截取当前屏幕或特定元素的截图，然后通过一个多模态视觉模型（如Qwen-VL）或专门的OCR服务来识别其中的文字和图标信息。这一步是可选的，但对于复杂UI验证至关重要。

上层是 智能决策层 ，主角是Qwen3-14B。我们将当前页面状态（结构化DOM数据+可选视觉描述）和用户指令（测试步骤，如“登录”）一起构造为提示词（Prompt），输入给模型。模型的职责是输出一个具体的、可执行的“动作指令”。这个指令需要被严格格式化，例如一个JSON：

{
  "action": "click",
  "selector": "button[data-testid='submit-btn']",
  "reason": "这是页面中唯一的提交按钮，文本为‘登录’"
}

或者更复杂的组合动作。模型需要理解页面元素，并选择最合适的定位策略。

最顶层是 控制与验证层 。它接收模型的JSON指令，调用Playwright的相应API执行操作（如click, fill, select）。执行后，再次获取新的页面状态，并可能结合新的用户指令（如“验证登录成功”），让模型判断测试是否通过。验证逻辑同样由模型驱动，比如让它分析页面是否出现了“欢迎，[用户名]”的文本，或者关键元素是否从不可用变为可用。

2.2 为什么选择Qwen3-14B-Instruct？

市面上开源模型不少，为什么是Qwen3-14B-Instruct？首先，14B参数规模在精度和推理成本间取得了不错的平衡，在消费级显卡（如RTX 4090）上可以量化后本地部署，响应速度可以接受。其次，Qwen系列在工具调用和指令跟随方面做了大量优化，其Instruct版本对格式化输出（如JSON）的理解和遵从性很好，这对于生成稳定的动作指令至关重要。相比一些更大的模型，它在私有化部署和可控性上优势明显，测试数据不会外泄。

当然，也可以考虑CodeLlama-34B-Instruct或DeepSeek-Coder-V2，它们在代码生成上可能更强。但综合易用性、社区支持和中文指令理解，Qwen3-14B-Instruct是一个稳健的起点。如果后续对复杂逻辑推理要求更高，可以升级到Qwen3-32B或72B版本。

3. 核心实现细节拆解

架构清晰后，实现过程中的魔鬼都在细节里。以下几个环节直接决定了项目的成败。

3.1 页面信息的高效提取与表示

直接把整个页面的HTML丢给模型是不现实的，会浪费大量上下文窗口且包含无数无关信息。我们的目标是提取一个“语义化快照”。

精简DOM策略 ：

• 过滤 ：使用 document.querySelectorAll 获取所有元素，但过滤掉 <script> , <style> , 隐藏元素（ offsetParent 为null或 style.display 为 none ），以及过于深层的嵌套元素（比如深度大于10）。
• 关键属性提取 ：对保留的每个元素，提取 tagName , id , className , innerText （前200字符）, placeholder , aria-label , role , type （针对input）, href （针对a标签）, data-testid 等测试常用属性。
• 构建树形结构 ：保留基本的父子关系，但可以压缩只有单个文本子节点的元素。最终生成一个简化的JSON树。

视觉信息融合 ： 对于无法从HTML中可靠获取的信息，比如一个自定义的开关按钮当前是开还是关，我们需要截图。有两种方式：

1. 对整个页面或特定区域截图，调用本地的多模态模型（如部署的Qwen-VL）进行描述：“这是一个蓝色的开关按钮，处于开启状态。”
2. 对于已知的需要OCR的区域（如验证码、动态生成的文本图片），使用专门的OCR库（如Tesseract.js或PaddleOCR）进行识别。

最终，我们将精简后的DOM树和视觉描述文本合并，作为“当前页面状态描述”，送入提示词。

3.2 提示词工程：让模型理解任务并稳定输出

提示词的设计是连接人类意图和模型行动的关键。它必须清晰、具体，并约束输出格式。

一个基础的提示词模板如下：

你是一个UI自动化测试助手。你的任务是根据给定的当前页面描述和用户指令，输出下一步要执行的具体操作。

当前页面描述：
{{page_description}}

用户指令：{{user_instruction}}

请严格按以下JSON格式输出，且只输出JSON：
{
  "thought": "简要分析当前页面状态和如何完成指令",
  "action": "操作类型，必须是以下之一：click, fill, select, hover, wait, scroll, key_press, navigate, extract_text, assert",
  "selector": "用于定位元素的CSS选择器或XPath，尽可能简洁稳定",
  "value": "可选，fill或select时传入的值",
  "expected_condition": "可选，assert操作时期望的条件描述",
  "timeout": "可选，等待超时时间（毫秒）"
}

注意：
1. 选择器应优先使用有明确语义的属性，如`[data-testid]`, `[aria-label]`, `id`。
2. 对于`assert`操作，`expected_condition`应描述期望看到的文本、元素状态或URL变化。

关键技巧 ：

• 思维链（Chain-of-Thought） ：要求模型输出 thought 字段，这不仅能提高动作准确性，在调试时也极其有用，可以看到模型的“思考过程”。
• 严格枚举操作类型 ：将模型的动作限制在预定义集合内，防止它天马行空地输出无法执行的操作。
• 引导稳定选择器 ：在提示词中强调使用稳定的属性，减少对易变的 class 或文本内容的依赖。
• 多轮对话上下文 ：在实际测试流程中，一个测试用例包含多个步骤。我们需要在每次模型调用时，不仅传入当前页面状态，还要附带上一步或几步的 历史动作-结果 对，帮助模型理解测试进程。

3.3 动作执行与异常处理

收到模型的JSON输出后，控制层需要解析并执行。这里不能盲目信任模型。

安全执行策略 ：

1. JSON解析与校验 ：首先检查JSON格式是否合法，必要字段是否存在， action 是否在允许列表中。
2. 选择器存在性检查 ：在执行动作前，先用Playwright的 page.locator(selector).first() 检查元素是否存在且可见。如果不存在，不应直接报错，而是可以将此信息（“选择器未找到元素”）作为反馈，连同当前页面状态，再次发送给模型，让它重新决策或调整选择器。这构成了一个简单的自我修正循环。
3. 动作执行与等待 ：执行 click , fill 等操作后，必须加入适当的等待。Playwright本身有自动等待，但对于模型驱动的流程，在关键步骤后（如点击登录按钮），最好显式等待一个网络请求完成或页面导航发生（ page.waitForLoadState('networkidle') ）。
4. 超时与重试 ：为每个动作设置合理的超时时间。对于 assert 操作，可能需要轮询检查条件是否满足，而不是立即断言失败。

错误反馈循环 ： 当执行失败（如元素未找到、操作被拦截），这个错误信息是宝贵的。我们应该将错误详情（错误类型、截图、当时的页面状态）记录下来，并可以选择将其作为新的输入，让模型分析失败原因并尝试替代方案。例如，模型第一次可能想点击一个 button:has-text("Submit") ，但失败了。反馈错误后，模型可能会注意到另一个 form > button[type="submit"] ，从而进行重试。

4. 完整实操流程：从零搭建一个登录测试用例

理论说了这么多，我们动手搭一个最简单的例子：用这个框架测试一个Web应用的登录功能。

4.1 环境准备与初始化

首先，准备好Python环境（建议3.9+），安装核心库：

pip install playwright openai # 这里用openai兼容的库调用本地部署的Qwen
playwright install chromium

假设我们已经在本机（或内网服务器）部署了Qwen3-14B-Instruct的API服务，兼容OpenAI API格式，端点地址为 http://localhost:8000/v1 。

然后，编写一个核心的 Agent 类，它封装了与模型交互和Playwright操作：

import asyncio
from playwright.async_api import async_playwright
import json
import aiohttp

class UIAutoAgent:
    def __init__(self, model_api_url, api_key="none"):
        self.api_url = model_api_url
        self.api_key = api_key
        self.browser = None
        self.page = None
        self.context = None

    async def start(self):
        playwright = await async_playwright().start()
        self.browser = await playwright.chromium.launch(headless=False) # 调试时可设为False
        self.context = await self.browser.new_context()
        self.page = await self.context.new_page()

    async def get_page_description(self):
        # 注入脚本获取精简DOM
        description = await self.page.evaluate("""
            () => {
                function extractElementInfo(el, depth=0) {
                    if (depth > 8 || el.style.display === 'none' || el.offsetParent === null) return null;
                    let info = {
                        tag: el.tagName.toLowerCase(),
                        id: el.id,
                        class: el.className,
                        text: (el.innerText || '').substring(0, 200).trim(),
                        placeholder: el.placeholder,
                        'aria-label': el.getAttribute('aria-label'),
                        role: el.getAttribute('role') || el.tagName,
                        type: el.type,
                        href: el.href,
                        'data-testid': el.getAttribute('data-testid')
                    };
                    // 清理空值
                    Object.keys(info).forEach(key => info[key] == null && delete info[key]);
                    if (el.children.length > 0) {
                        info.children = [];
                        for (let child of el.children) {
                            let childInfo = extractElementInfo(child, depth+1);
                            if (childInfo) info.children.push(childInfo);
                        }
                        if (info.children.length === 0) delete info.children;
                    }
                    return info;
                }
                return extractElementInfo(document.body);
            }
        """)
        # 这里可以添加截图和OCR逻辑，本例暂略
        return json.dumps(description, ensure_ascii=False, indent=2)

    async def ask_model(self, page_desc, instruction, history=[]):
        prompt = self._build_prompt(page_desc, instruction, history)
        async with aiohttp.ClientSession() as session:
            async with session.post(
                f"{self.api_url}/chat/completions",
                headers={"Authorization": f"Bearer {self.api_key}"},
                json={
                    "model": "qwen3-14b-instruct",
                    "messages": [{"role": "user", "content": prompt}],
                    "temperature": 0.1, # 低温度保证输出稳定
                    "max_tokens": 1024
                }
            ) as resp:
                result = await resp.json()
                content = result['choices'][0]['message']['content']
                # 提取JSON部分，模型可能附带一些说明文字
                import re
                json_match = re.search(r'\{.*\}', content, re.DOTALL)
                if json_match:
                    return json.loads(json_match.group())
                else:
                    raise ValueError(f"模型未返回有效JSON: {content}")

    def _build_prompt(self, page_desc, instruction, history):
        # 构建提示词，包含历史记录
        hist_str = ""
        for h in history[-3:]: # 只保留最近3条历史
            hist_str += f"上一步动作: {h.get('action')}， 选择器: {h.get('selector')}\n"
        prompt_template = f"""你是一个UI自动化测试助手。你的任务是根据给定的当前页面描述和用户指令，输出下一步要执行的具体操作。
历史记录：
{hist_str}
当前页面描述：
{page_desc}
用户指令：{instruction}
请严格按以下JSON格式输出，且只输出JSON：
{{
  "thought": "简要分析当前页面状态和如何完成指令",
  "action": "操作类型，必须是以下之一：click, fill, select, hover, wait, scroll, key_press, navigate, extract_text, assert",
  "selector": "用于定位元素的CSS选择器或XPath，尽可能简洁稳定",
  "value": "可选，fill或select时传入的值",
  "expected_condition": "可选，assert操作时期望的条件描述",
  "timeout": "可选，等待超时时间（毫秒），默认5000"
}}"""
        return prompt_template

    async def execute_action(self, action_cmd):
        # 解析并执行模型返回的动作命令
        action = action_cmd.get('action')
        selector = action_cmd.get('selector')
        value = action_cmd.get('value')
        timeout = action_cmd.get('timeout', 5000)

        if not selector and action not in ['navigate', 'wait']:
            raise ValueError("非导航/等待操作必须提供选择器")

        try:
            if action == 'navigate':
                await self.page.goto(value)
            elif action == 'click':
                await self.page.locator(selector).first.click(timeout=timeout)
            elif action == 'fill':
                await self.page.locator(selector).first.fill(value, timeout=timeout)
            elif action == 'assert':
                # 这里简化处理，实际可根据expected_condition进行复杂断言
                if 'expected_condition' in action_cmd:
                    # 例如，检查文本是否存在
                    await self.page.wait_for_selector(f":text-is('{action_cmd['expected_condition']}')", timeout=timeout)
            # ... 其他动作实现
            await asyncio.sleep(0.5) # 动作间短暂间隔
            return {"status": "success", "action": action}
        except Exception as e:
            return {"status": "error", "action": action, "error": str(e), "screenshot": await self.page.screenshot()}

    async def run_test_step(self, instruction, history):
        page_desc = await self.get_page_description()
        action_cmd = await self.ask_model(page_desc, instruction, history)
        print(f"模型指令: {json.dumps(action_cmd, indent=2)}")
        result = await self.execute_action(action_cmd)
        return {**action_cmd, **result}

4.2 测试用例编排与执行

有了 Agent ，我们就可以编排一个登录测试：

import asyncio

async def test_login():
    agent = UIAutoAgent(model_api_url="http://localhost:8000/v1")
    await agent.start()
    history = []

    # 步骤1：导航到登录页
    step1 = await agent.run_test_step("导航到登录页面，网址是 https://example.com/login", history)
    history.append(step1)
    if step1['status'] == 'error':
        print("导航失败"); return

    # 步骤2：在用户名输入框填写用户名
    step2 = await agent.run_test_step("在用户名输入框中填写 'testuser'", history)
    history.append(step2)

    # 步骤3：在密码输入框填写密码
    step3 = await agent.run_test_step("在密码输入框中填写 'password123'", history)
    history.append(step3)

    # 步骤4：点击登录按钮
    step4 = await agent.run_test_step("点击登录按钮", history)
    history.append(step4)

    # 步骤5：验证登录成功（例如，页面出现欢迎语或跳转到主页）
    step5 = await agent.run_test_step("验证登录成功，检查页面是否包含 '欢迎' 或 'Dashboard' 文本", history)
    history.append(step5)

    if step5['status'] == 'success':
        print("登录测试通过！")
    else:
        print(f"登录测试失败，最后一步结果: {step5}")

    await agent.browser.close()

if __name__ == "__main__":
    asyncio.run(test_login())

运行这个脚本，你会看到模型输出一系列的 thought 和 action ，然后Playwright执行它们。整个过程就像有一个虚拟的测试员在阅读页面并操作。

5. 避坑指南与效能优化

在实际项目中跑通这个流程后，我积累了一些宝贵的经验教训，能帮你节省大量调试时间。

5.1 模型幻觉与选择器不稳定

这是最常见的问题。模型可能会“幻想”出页面上不存在的元素，或者生成一个非常脆弱的选择器（比如依赖完整的文本内容 button:has-text("Submit Application Now") ，按钮文本一改就失效）。

应对策略 ：

• 强化提示词约束 ：在提示词中反复强调“选择器必须基于当前页面描述中实际存在的属性”，“优先使用 data-testid 、 id 、 name 或具有唯一性的 aria-label ”。
• 引入元素候选集 ：在提取页面描述时，可以为每个可交互元素生成多个候选选择器（如CSS选择器、XPath），并将这个列表提供给模型选择，而不是让模型从头生成。这能大幅提高稳定性。
• 后处理校验 ：在执行模型生成的选择器前，先用Playwright的 page.locator(selector).count() 检查匹配的元素数量。如果匹配到0个或多个，可以将此信息反馈给模型，要求它重新选择或澄清。
• 人工编写关键选择器 ：对于核心业务流程的关键元素（如登录按钮、支付确认框），不要完全依赖模型。可以预先在测试用例中定义好这些元素的稳定选择器（如 [data-testid="login-submit"] ），当指令涉及这些元素时，直接使用预定义的选择器，绕过模型生成。

5.2 执行速度与成本考量

大模型推理相比传统脚本是慢的。Qwen3-14B在本地A100上生成一个动作可能需要1-3秒，在消费级显卡上可能更久。一个包含10个步骤的测试用例，可能就需要半分钟到一分钟。

优化手段 ：

• 缓存页面描述 ：如果连续几个操作都在同一页面，且页面状态没有发生根本变化（比如只是填写表单），可以缓存第一次获取的页面描述，后续步骤复用，减少DOM提取和模型推理的开销。
• 动作批处理 ：对于一些简单的、连续的操作序列（如“填写用户名、密码、点击登录”），可以尝试在一个Prompt中让模型规划多个动作，输出一个动作列表。但这要求模型有更强的规划能力，且容易出错，初期建议单步执行。
• 模型量化与推理优化 ：使用GPTQ、AWQ等量化技术将模型量化到4bit或8bit，可以显著降低显存占用并提升推理速度，精度损失在可接受范围内。同时，使用vLLM、TGI等高性能推理框架，而非简单的Transformers推理。
• 非关键断言本地化 ：对于“验证页面标题”、“检查URL”这类简单断言，完全可以用正则表达式或字符串匹配在本地完成，无需调用大模型，节省开销。

5.3 测试场景的局限性

不要指望这个方案能100%替代所有UI自动化。它擅长的是 探索性测试、复杂交互测试和适配变化 。但对于以下场景，传统方法可能更优：

• 性能测试 ：需要精确计时和并发控制。
• 极端数据验证 ：需要系统性地输入大量边界值。
• 底层API校验 ：UI操作背后的API调用是否正确，仍需专门的API测试。

最佳实践是将其作为 补充工具 ，与传统自动化框架（如Pytest + Playwright）结合。用传统框架覆盖稳定、核心的流程，用大模型驱动的OpenClaw来处理那些“难啃的骨头”和探索性用例。

5.4 结果验证的可靠性

让模型自己判断测试是否通过，存在“自我欺骗”的风险。比如，登录失败了，但页面显示了一个错误提示“用户名不存在”，模型可能会错误地认为这个错误提示的出现就是“预期结果”。

提升验证可靠性 ：

• 多维度验证 ：不要只依赖模型的一次断言。结合传统断言，例如在模型判断成功后，再检查本地存储中是否设置了正确的用户token，或当前URL是否跳转到了预期路径。
• 定义清晰的通过/失败标准 ：在测试用例开始时，就用明确的、可量化的标准描述成功状态（如“页面URL包含 /dashboard ，且存在一个 h1 元素，其文本内容为‘欢迎，testuser’”）。在最终验证步骤，将这个标准作为指令的一部分发给模型。
• 人工审核关键用例 ：对于核心业务流程的测试结果，尤其是首次运行或代码变更后，建议保留截图或操作录屏，供人工二次确认。

6. 进阶方向与扩展思考

把这个基础框架跑起来只是第一步。要让它在实际项目中发挥更大价值，可以考虑以下几个扩展方向：

1. 自学习与选择器库构建 ： 模型每次操作成功的选择器，都可以被记录到一个“可靠选择器库”中。当下次遇到类似页面结构或元素时，可以优先从库中推荐选择器，甚至直接使用，从而减少模型生成不稳定选择器的几率，并加快执行速度。

2. 多模态能力深度融合 ： 当前方案中，视觉信息作为文本描述补充。未来可以直接将页面截图输入给像Qwen-VL这样的多模态大模型，让它直接“看”图输出动作坐标或元素位置。Playwright支持基于坐标的点击，这样可以完全绕过脆弱的CSS选择器，对图形化界面或游戏UI测试有奇效。

3. 测试用例的自然语言生成 ： 反过来，我们可以让模型“观摩”人工操作（录制操作序列和页面变化），自动生成对应的自然语言测试用例描述和自动化脚本骨架。这能极大提升测试用例编写的效率。

4. 与CI/CD流水线集成 ： 将OpenClaw Agent封装成一个服务，在CI/CD流水线中，针对每次构建的版本，自动运行一组核心的、由大模型驱动的“智能冒烟测试”。它可以发现那些因UI微调而导致的、传统脚本未能及时更新的测试失败。

这个项目让我深刻体会到，大模型并非要取代传统的自动化测试，而是赋予其一种“模糊智能”和“自适应能力”。它把测试脚本的编写和维护，从精确的、脆弱的代码编写，部分转变为了对模型进行任务描述和结果校验。这条路还很长，稳定性、成本和速度都是挑战，但它为应对日益复杂的软件界面和快速迭代的开发节奏，提供了一个充满想象力的新思路。如果你也在为UI自动化测试的维护成本头疼，不妨从一个小用例开始，试试让Qwen3-14B来当你的“测试实习生”。