---
title: UI Smoke / Functional 自动化
doc_type: functional-test
domain: frontend
keywords:
  - Playwright
  - UI smoke
  - functional test
  - renderer
  - mock desktop bridge
summary: 用浏览器自动化脚本验证 renderer 关键导航、筛选和设置页交互，并沉淀统一命令、产物位置和排障口径。
when_to_read:
  - 改了页面导航、筛选、设置页或共享 renderer 契约
  - 需要快速确认前端没有明显功能回归或设计漂移
read_next:
  - ./README.md
  - ./notice-original-functional-test.md
  - ../features/research-workbench-layout.md
---
# UI Smoke / Functional 自动化

这篇文档固定前端 UI 自动化的运行方式、覆盖范围和排障口径。它适合在你改了页面结构、筛选条件、关键文案、设置页交互或 renderer/shared 契约之后执行。读完后，如果你要做公告原文专项回归，再看 [notice-original-functional-test.md](./notice-original-functional-test.md)；如果你要确认页面结构和工作台布局边界，再看 [research-workbench-layout.md](../features/research-workbench-layout.md)。

## 目的

这套脚本解决的是“前端关键页面有没有明显回归”：

- 登录后能否进入工作台
- 顶部导航能否切到公告分析、公告原文和设置页
- 公告分析筛选、重置是否还按正式契约返回数据
- 公告原文列表筛选、详情跳转和返回态是否保留
- 设置页应用分组和涨跌色模式切换是否还能工作

它不是 Rust / Tauri 端到端测试，不负责验证真实数据库、真实调度任务或真实远程 LLM 结果。

## 当前实现边界

当前脚本使用：

- `scripts/ui_test_harness.mjs`
- `scripts/ui_test_fixtures.mjs`
- `scripts/ui_smoke_check.mjs`
- `scripts/ui_functional_check.mjs`
- `scripts/ui_run_all.mjs`

运行方式是：

1. 如果 `http://127.0.0.1:4173` 没有现成 renderer 服务，harness 会自动启动 `npm run dev:renderer -- --host 127.0.0.1 --port 4173 --strictPort`
2. 在浏览器启动前注入 mock `window.desktopApp`
3. 页面继续走正式 `src/renderer/src/api/client.ts` 和共享契约解析，不允许页面绕过 client 直连 mock
4. 每个场景都会输出 HTML 和 PNG 产物，方便回看 DOM 和视觉结果

这意味着它主要验证：

- 页面导航和路由行为
- renderer 到 desktop bridge 的契约调用形状
- 关键筛选、返回态和设置交互
- 页面没有浏览器级报错或 `console.error`

它不验证：

- 真实 Tauri IPC
- 真实 SQLite 数据
- 真实公告同步、分析和深报任务执行
- 真实 provider / sidecar 可用性

## 命令

安装前端自动化依赖：

```bash
npm install --registry=https://registry.npmjs.org
```

可选安装 Playwright 自带 Chromium：

```bash
npm run test:ui:install
```

只跑 smoke：

```bash
npm run test:ui:smoke
```

只跑 functional：

```bash
npm run test:ui:functional
```

顺序跑完整 UI 自动化：

```bash
npm run test:ui
```

## 浏览器选择

默认优先级如下：

1. Playwright 自带 Chromium
2. 本机 `Google Chrome`
3. 本机 `Microsoft Edge`

如果你想显式指定浏览器，可设置：

```bash
UI_TEST_BROWSER_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" npm run test:ui
```

其他常用环境变量：

```bash
UI_TEST_HOST=127.0.0.1
UI_TEST_PORT=4173
UI_TEST_BASE_URL=http://127.0.0.1:4173
```

## 覆盖场景

### Smoke

`npm run test:ui:smoke` 当前覆盖：

- 登录页输入测试账号并进入工作台
- 当日看盘首屏可见
- 顶部导航切到公告分析
- 顶部导航切到公告原文
- 从公告原文列表进入详情，再返回列表
- 从工作台进入设置页，再切到“应用”分组
- 从设置页返回工作台

### Functional

`npm run test:ui:functional` 当前覆盖：

- 公告分析页按证券简称和行业筛选
- 公告分析页重置后恢复完整列表
- 公告原文页按证券代码筛选
- 公告原文详情返回后保留列表查询态
- 公告原文页重置后恢复完整列表
- 设置页涨跌色模式切换到“绿涨红跌”

## 产物位置

每次运行会把当前页面的 HTML 和截图写到：

```text
output/playwright/ui-smoke/
output/playwright/ui-functional/
```

当前文件命名按步骤序号递增，例如：

- `01-today-watch.png`
- `03-notice-original-filtered.html`
- `07-settings-price-color.png`

如果脚本失败，优先看同目录下最新步骤的 `.html` 和 `.png`，再看终端报错。

## 通过标准

这套自动化通过时，至少满足：

- `npm run test:ui:smoke` 成功
- `npm run test:ui:functional` 成功
- `npm run test:ui` 成功
- 脚本没有捕获到浏览器 `pageerror`
- 脚本没有捕获到浏览器 `console.error`

## 常见问题

### 1. `npm install` 卡在 `registry.npmmirror.com`

当前仓库环境如果对 `npmmirror` 超时，直接切回官方 registry：

```bash
npm install --registry=https://registry.npmjs.org
```

### 2. Playwright 没装浏览器

如果 `chromium.launch()` 失败，但本机装了 Chrome 或 Edge，harness 会自动回退到本机浏览器。否则手动执行：

```bash
npm run test:ui:install
```

### 3. 页面能打开但脚本找不到元素

优先判断是下面哪类问题：

- 文案或按钮名改了，脚本选择器需要同步
- 页面结构改了，产物截图和 HTML 里已经能看到新结构
- mock `window.desktopApp` 缺了新接口或字段
- 共享契约变了，但 `scripts/ui_test_fixtures.mjs` 还没同步

排查顺序：

1. 看终端报错定位是哪个步骤
2. 看 `output/playwright/*/*.html`
3. 看对应截图
4. 再决定是改脚本、补 mock 还是修 renderer 契约

### 4. 什么时候还需要手工测试

以下场景仍然需要结合专项 runbook 或真实桌面环境：

- Tauri IPC / Rust 命令改动
- SQLite 读模型改动
- 真实调度任务、同步任务和补偿流程
- 真实远程 LLM 调用
- 真实 sidecar / provider 状态
