企业官网建设流程全解析

1. 为什么要在 Cursor 里做 QQ音乐 GUI 自动化测试

桌面端 GUI 自动化测试一直是测试圈里比较“劝退”的方向：控件树层级深、定位方式五花八门、脚本跑一次崩一次。我这次拿一个自行搭建的 QQ音乐仿站桌面程序（非腾讯官方客户端）当被测对象，用 Cursor 写 Python + pywinauto 脚本，把首页、本地下载、推荐、我喜欢、最近播放、歌词页这几个模块的用例和脚本都跑通了一遍。

pywinauto 的核心思路其实不复杂：它通过 Windows 的 UI Automation 或 Win32 API 拿到窗口和控件的句柄，然后模拟点击、输入、读取文本。你可以把它理解成“用代码代替人手去点界面”。适合谁？适合已经会一点 Python、想入门桌面自动化测试的同学，也适合测试团队想把重复的回归用例脚本化的人。

真正让我头疼的不是 pywinauto 本身，而是写脚本过程中要反复让 AI 帮忙生成用例、补全控件定位、检查方法调用是否匹配控件类型。这时候如果每个 AI 工具都单独配一套 Key，管理起来很乱。所以我把 Cursor 里所有 AI 请求统一改到 TaoToken 管理，一个 Key 走通，省掉了到处找配置的麻烦。下面就把完整流程拆开讲。

2. TaoToken 前置准备：统一 Key 与 Cursor 接入配置

在开始写脚本之前，先把 AI 请求的出口统一掉。TaoToken 是一个 API 聚合管理平台，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。它的作用是让你用一个 Key 去调用不同的模型，不用在 Cursor、脚本、其他工具里各配一份。

第一步，去控制台创建 API Key。打开 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，登录后在 API Keys 页面新建一个 Key，复制出来备用。这个 Key 就是后面 Cursor 和脚本里要填的东西。

第二步，在 Cursor 里配置。Cursor 支持自定义 OpenAI 兼容的 Base URL。打开 Cursor 设置，找到 Models 或 OpenAI API Key 相关配置项，把 Base URL 改成https://taotoken.net/api，API Key 填刚才复制的那串。模型 ID 按你实际要用的填，比如claude-sonnet-4-20250514这类。这里要注意三件套必须齐全：Base URL、Key、Model ID，缺一个都会报错。

如果你用的是 Claude Code 这类命令行工具，配置方式类似，在环境变量或配置文件里指定ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。具体接入文档可以参考 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。

配置好之后，Cursor 里的 AI 对话、代码补全、内联编辑都会走 TaoToken。这样你在写 pywinauto 脚本时，让 AI 帮你生成用例、检查控件定位，请求都从同一个出口走，Key 管理集中在一处。对于要长期跑自动化、频繁调用 AI 的场景，也可以看看 Coding Plan，适合持续编码和 Agent 类任务：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。

这一步做完，环境就齐了。接下来进入正题：用 pywinauto 定位控件。

3. 可复制配置：pywinauto 控件定位与 Cursor 调用示例

pywinauto 定位控件最常用的两种后端是uia和win32。QQ音乐这类自绘界面比较多的程序，建议先用uia后端，因为它对现代控件的支持更好。启动应用的基本写法是这样：

from pywinauto.application import Application app = Application(backend="uia").start(r"D:\QQMusicDemo\QQMusic.exe") main_win = app.window(title_re=".*QQ音乐.*") main_win.wait("ready", timeout=20)

拿到主窗口后，定位子控件用child_window。比如顶部导航栏的“本地下载”按钮，可以这样写：

download_tab = main_win.child_window(title="本地下载", control_type="Button") download_tab.click_input()

这里的关键是control_type要和实际控件类型匹配。如果控件是列表项，用ListItem；是文本，用Text；是按钮，用Button。用错类型会直接抛ElementNotFoundError。

为了不让脚本里到处硬编码控件信息，我把控件数据抽到 YAML 里。比如data/controls.yaml：

main_window: title_re: ".*QQ音乐.*" backend: "uia" local_download: tab: title: "本地下载" control_type: "Button" song_list: control_type: "List" auto_id: "songListBox" like_page: tab: title: "我喜欢" control_type: "Button"

然后封装一个读取工具common/yaml_util.py：

import yaml def load_yaml(path): with open(path, "r", encoding="utf-8") as f: return yaml.safe_load(f)

在 Cursor 里让 AI 生成脚本时，我会把用例文档和控件信息文档一起 @ 进去。提示词大概是这样：

读取本地下载测试用例.md 和本地下载控件信息.md，用 Python + pywinauto 生成 pytest 测试脚本。控件定位的 window 和 child_window 方法必须和控件信息文档匹配，每个用例都要有断言，不使用复杂设计模式。

Cursor 会基于这两个文件生成脚本。生成后我会重点检查两点：一是control_type是否和控件信息一致，二是调用的方法是否匹配控件类型（比如对Edit控件用type_keys而不是click_input）。

pytest 的用例结构大概长这样：

import pytest from pywinauto.application import Application class TestLocalDownload: def test_switch_to_download_tab(self, app): main_win = app.window(title_re=".*QQ音乐.*") main_win.child_window(title="本地下载", control_type="Button").click_input() assert main_win.child_window(title="本地下载", control_type="Button").exists()

跑之前记得装依赖：

pip install pywinauto pytest pyyaml pytest-order allure-pytest

配置这块，pytest.ini里加上 allure 报告和用例顺序：

[pytest] addopts = --alluredir=./reports/allure-results

用例执行顺序用pytest-order指定，在类上加装饰器：

import pytest @pytest.mark.order(1) class TestCommonModule: ...

这样六个模块按test_common_module.py、test_local_download.py、test_like.py、test_recent.py、test_recommend.py、test_lyrics.py的顺序跑。

4. 验证请求：跑通一次完整测试用例

配置写完，得实际跑一次确认没问题。先验证 TaoToken 的 Key 在 Cursor 里能用：在 Cursor 里随便问一句“帮我写一个 pywinauto 点击按钮的例子”，如果能正常返回，说明 Base URL 和 Key 配对了。如果报 401，多半是 Key 复制错了或者 Base URL 少了/api。

然后验证脚本。先单独跑一个用例：

pytest tests/test_local_download.py::TestLocalDownload::test_switch_to_download_tab -v

预期结果是 PASSED。如果控件定位失败，会看到pywinauto.findwindows.ElementNotFoundError，这时候回去检查控件信息文档里的title和control_type是否和实际一致。

单个用例通过后，跑整个模块：

pytest tests/test_local_download.py -v

再跑全量：

pytest tests/ -v

全量跑的时候，因为用了pytest-order，类之间会按指定顺序执行。跑完生成 allure 报告：

allure serve .\reports\allure-results\

或者生成静态报告：

allure generate .\reports\allure-results\ -o .\reports\allure-report\

用 PyCharm 打开allure-report目录下的index.html就能看报告。报告里能看到每个用例的步骤、断言结果、失败截图（如果配了截图的话）。

我实测下来，第一次跑全量大概率会有几个用例挂掉，常见原因是页面切换后控件还没加载完。解决办法是在关键操作后加wait：

main_win.child_window(title="我喜欢", control_type="Button").click_input() main_win.child_window(auto_id="likeListBox", control_type="List").wait("visible", timeout=10)

等控件可见后再做断言，稳定性会好很多。

5. 本篇常见错排查：401、控件定位失败、OAuth 报错

跑自动化脚本和配 AI 工具的过程中，我踩过几个典型的坑，这里对照真实报错说下排查思路。

报错一：401 Unauthorized。这个一般出现在 Cursor 调用 AI 的时候。原因通常是 Key 无效或 Base URL 写错。检查三件套：Base URL 是不是https://taotoken.net/api，Key 是不是从控制台复制的完整串，Model ID 是不是填了不存在的模型。如果用的是 Claude Code，检查ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY是否配对。

报错二：local proxy failed。这个报错通常和网络配置有关。先确认你的 Base URL 没有多余的空格或换行，再确认本地没有残留的代理环境变量干扰。把HTTP_PROXY、HTTPS_PROXY这类环境变量清掉再试。

报错三：reading choices 相关报错。这类报错一般是返回体解析失败，常见于模型 ID 填错或者请求格式不对。确认你填的 Model ID 是平台支持的，请求体是标准的 OpenAI 兼容格式。

报错四：OAuth 相关报错。如果你用的是需要 OAuth 的工具，检查 token 是否过期。重新走一遍授权流程，或者换成 API Key 方式接入。

报错五：pywinauto 控件定位失败。报ElementNotFoundError时，先用print_control_identifiers()把控件树打出来：

main_win.print_control_identifiers()

对照输出检查title、auto_id、control_type是否和 YAML 里写的一致。常见问题是title带了动态内容，这时候改用title_re正则匹配。

报错六：方法调用不匹配。比如对Edit控件调了click_input而不是type_keys，或者对ListItem调了set_text。检查控件类型和方法的对应关系，Button用click_input，Edit用type_keys，List用item索引。

如果 Cursor 里配置一直报错，可以先去模型对话页面确认 Key 本身能用：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。Key 能用再回来查 Cursor 的配置。

6. 统一 Key 管理后的持续接入建议

把 AI 请求统一到 TaoToken 之后，最直接的好处是 Key 只维护一份。Cursor 里配一次，脚本里如果也要调 AI（比如自动生成用例），用同一个 Key 就行。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，API Keys 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。

对于要长期跑 GUI 自动化、频繁让 AI 帮忙改脚本的场景，Coding Plan 会更划算，适合持续编码和 Agent 任务：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。

最后说个实用技巧：重构项目之前一定先备份tests文件夹。我试过直接让 AI 重构，结果把已经跑通的用例改挂了，又得回滚。正确顺序是先把所有用例跑通过，再抽控件信息到 YAML，再重构测试文件，每步都跑一次确认没破坏原有逻辑。日志模块加上之后，跑失败时先看logs目录下的 error 日志，比在控制台翻输出快得多。