# 金山文档测试工具使用指南

## 🔧 线程问题解决方案

浮浮酱为您创建了**4个不同版本**的测试工具，按推荐顺序排列：

---

## 📌 **推荐测试顺序**

### **方案1: 最简版本** ⭐⭐⭐⭐⭐ (首选)

**文件**: `simple_test.py`
**启动**: 双击 `start_simple_test.bat`

**特点**:
- ✅ **无UI界面** - 直接命令行运行
- ✅ **主线程运行** - 避免所有线程问题
- ✅ **最稳定** - 简单直接，出错概率最低
- ✅ **交互友好** - 每步都有提示

**使用流程**:
```
1. 双击 start_simple_test.bat
2. 输入金山文档URL (或直接回车使用默认)
3. 按 y 确认开始测试
4. 观察浏览器自动启动和操作
5. 测试完成后按Enter保持浏览器打开
```

**适合**: 所有人，特别是遇到问题的用户

---

### **方案2: 异步UI版本** ⭐⭐⭐

**文件**: `kdocs_async_test.py`
**启动**: 双击 `start_async_test.bat`

**特点**:
- ✅ **图形界面** - 有UI，操作直观
- ✅ **异步架构** - 使用asyncio避免线程问题
- ✅ **单线程异步** - 所有浏览器操作在异步循环中

**使用流程**:
```
1. 双击 start_async_test.bat
2. 点击"启动浏览器" → 确认执行
3. 点击"打开文档" → 确认执行
4. 依次执行各项测试
```

**适合**: 喜欢图形界面的用户

---

### **方案3: 同步线程版本** ⭐⭐

**文件**: `kdocs_sync_test.py`
**启动**: 双击 `start_sync_test.bat`

**特点**:
- ✅ **图形界面** - 有UI，操作直观
- ✅ **线程本地存储** - 每个线程使用自己的浏览器实例
- ⚠️ **较复杂** - 线程管理逻辑较复杂

**使用流程**:
```
1. 双击 start_sync_test.bat
2. 点击"启动浏览器" → 确认执行
3. 点击"打开文档" → 确认执行
4. 依次执行各项测试
```

**适合**: 开发者，调试特定问题

---

### **方案4: 线程锁版本** ⭐ (备选)

**文件**: `kdocs_safety_test_fixed.py`
**启动**: 双击 `start_safety_test_fixed.bat`

**特点**:
- ✅ **图形界面** - 有UI，操作直观
- ✅ **线程锁** - 使用锁机制同步访问
- ⚠️ **可能仍有问题** - Playwright对线程切换敏感

**使用流程**:
```
1. 双击 start_safety_test_fixed.bat
2. 点击"启动浏览器" → 确认执行
3. 点击"打开文档" → 确认执行
4. 依次执行各项测试
```

**适合**: 备选方案

---

## 🚀 **快速开始 (推荐)**

### **步骤1: 测试基本功能**

首先运行**最简版本**确认基本功能：

```bash
# Windows用户
双击: start_simple_test.bat

# 或手动运行
python simple_test.py
```

**预期结果**:
```
✓ Playwright启动成功
✓ 浏览器启动成功
✓ 页面创建成功
✓ 页面导航完成
✓ 人员搜索测试完成
```

### **步骤2: 测试UI工具**

如果最简版本工作正常，再测试UI版本：

```bash
# 首选异步版本
双击: start_async_test.bat

# 如果异步版本有问题，尝试同步版本
双击: start_sync_test.bat
```

---

## 🔍 **问题排查**

### **问题1: "cannot switch to a different thread"**

**解决方案**: 使用**最简版本** (`simple_test.py`)
- 这是最稳定的解决方案
- 避免了UI框架带来的线程复杂性

### **问题2: "playwright未安装"**

**解决方案**:
```bash
pip install playwright
playwright install chromium
```

### **问题3: 浏览器启动失败**

**可能原因**:
1. 权限不足 - 以管理员身份运行
2. 端口被占用 - 关闭其他浏览器实例
3. 杀毒软件阻止 - 添加例外

### **问题4: 文档打开失败**

**检查**:
1. URL是否正确
2. 网络是否正常
3. 是否需要登录

---

## 📊 **测试项目说明**

每个测试工具都包含以下测试项目：

### **测试1: 浏览器连接**
- 验证Playwright和浏览器是否正常
- 检查页面对象是否可用
- **安全**: 仅检查，无实际操作

### **测试2: 文档打开**
- 导航到金山文档URL
- 检查页面加载状态
- 检查是否需要登录
- **安全**: 仅导航，无修改

### **测试3: 表格读取**
- 尝试读取表格元素
- 检查名称框
- 检查canvas元素
- **安全**: 仅读取，无修改

### **测试4: 人员搜索**
- 执行 `Ctrl+F` 搜索操作
- 输入测试姓名"张三"
- **安全**: 仅搜索，无修改

### **测试5: 图片上传(单步)** ⚠️
- 导航到D3单元格
- 点击插入 → 图片 → 本地
- 上传用户选择的图片
- **注意**: 会实际执行上传，但仅影响单个单元格

---

## 💡 **使用建议**

### **新手用户**
1. **首选**: `start_simple_test.bat` (最简版本)
2. **备选**: `start_async_test.bat` (异步版本)

### **开发者**
1. **首选**: `simple_test.py` (快速调试)
2. **深入**: `kdocs_async_test.py` (异步架构)
3. **调试**: `kdocs_sync_test.py` (线程本地存储)

### **遇到问题**
1. **优先**: 使用最简版本确认基本功能
2. **查看日志**: 所有版本都有详细日志
3. **逐个测试**: 按顺序执行测试项目
4. **检查配置**: 确保URL等配置正确

---

## 📞 **获取帮助**

如果遇到问题：

1. **查看日志**: 每个操作都有详细日志输出
2. **尝试不同版本**: 按推荐顺序尝试
3. **检查环境**: 确保Python和依赖已正确安装
4. **最小化测试**: 使用最简版本隔离问题

---

## 🎯 **测试成功标志**

**最简版本成功**:
```
[15:06:47] SUCCESS: ✓ Playwright启动成功
[15:06:48] SUCCESS: ✓ 浏览器启动成功
[15:06:49] SUCCESS: ✓ 上下文创建成功
[15:06:50] SUCCESS: ✓ 页面创建成功
[15:06:53] SUCCESS: ✓ 页面导航完成
[15:06:56] SUCCESS: ✓ 人员搜索测试完成
```

**UI版本成功**:
- 浏览器窗口正常打开
- 文档正常加载
- 所有测试步骤都显示"SUCCESS"
- 操作日志无错误信息

---

**祝您测试顺利！** 🎉

如有问题，请优先使用最简版本进行排查。