shop-platform/docs/websocket/test_readme.md

# WebSocket 测试文件说明

本目录包含用于测试 WebSocket 服务器的各种测试文件，支持不同环境和场景的测试需求。

## 测试文件列表

1. **`test_websocket.php`** - PHP 客户端测试脚本
2. **`test_websocket.html`** - 浏览器端 JavaScript 测试页面
3. **`test_wechat_miniprogram.js`** - 微信小程序客户端测试代码
4. **`test_readme.md`** - 本测试文件说明文档

## 测试前准备

在开始测试之前，请确保：

1. **启动 WebSocket 服务器**：
   ```bash
   cd d:/projects/shop-projects/backend/src
   php ws_server.php
   ```

2. **确保服务器运行正常**：
   服务器启动后，您应该看到类似以下输出：
   ```
   WebSocket服务器已启动，监听地址: ws://localhost:8080
   
   已注册WebSocket控制器的addon路径：
     - ws://localhost:8080/ws/aikefu (已注册)
   
   默认测试路径：
     - ws://localhost:8080/ws (默认路径，用于连接测试)
   按 Ctrl+C 停止服务器
   ```

## 1. PHP 客户端测试 (`test_websocket.php`)

### 功能说明
用于在 PHP 环境下测试 WebSocket 服务器的连接和基本功能。

### 使用方法

1. **直接运行测试脚本**：
   ```bash
   cd d:/projects/shop-projects/backend/docs/websocket
   php test_websocket.php
   ```

2. **测试不同路径**：
   - 默认测试路径：`ws://localhost:8080/ws`
   - aikefu 插件路径：`ws://localhost:8080/ws/aikefu`
   
   可以通过修改脚本中的 `$wsUrl` 变量来切换测试路径。

### 预期输出

成功连接并发送消息后，您应该看到类似以下输出：

```
正在连接到 WebSocket 服务器: ws://localhost:8080/ws
✅ 成功连接到 WebSocket 服务器
📤 发送 ping 消息
📤 发送测试消息
📥 收到消息: {"type":"welcome","message":"欢迎连接到默认WebSocket测试路径","info":"此路径仅用于测试，不提供实际功能。请使用/ws/{addonName}连接到具体的addon服务。"}
📥 收到消息: {"type":"pong"}
📥 收到消息: {"type":"info","message":"收到消息，但默认路径不提供实际功能","received":{"message":"Hello WebSocket!","action":"test"}}
```

## 2. 浏览器端 JavaScript 测试 (`test_websocket.html`)

### 功能说明
用于在浏览器环境下测试 WebSocket 服务器的连接和交互功能，提供直观的用户界面。

### 使用方法

1. **打开测试页面**：
   - 直接用浏览器打开 `test_websocket.html` 文件
   - 或者通过 Web 服务器访问：`http://your-domain/docs/websocket/test_websocket.html`

2. **配置测试参数**：
   - 在 "设置" 区域输入 WebSocket 服务器地址
   - 默认地址：`ws://localhost:8080/ws`
   - aikefu 插件地址：`ws://localhost:8080/ws/aikefu`

3. **连接和测试**：
   - 点击 "连接" 按钮建立 WebSocket 连接
   - 使用 "发送 Ping"、"发送测试消息" 或 "发送自定义消息" 按钮进行测试
   - 在消息区域查看发送和接收的消息

### 主要功能

- **连接管理**：连接、断开连接、重连
- **消息发送**：
  - Ping 消息：测试服务器响应
  - 测试消息：发送预设的测试数据
  - 自定义消息：支持发送任意 JSON 格式消息
- **消息显示**：
  - 美化显示 JSON 格式消息
  - 区分发送和接收的消息
  - 显示消息时间和发送者

## 3. 微信小程序客户端测试 (`test_wechat_miniprogram.js`)

### 功能说明
用于在微信小程序环境下测试 WebSocket 服务器的连接和通信功能，模拟实际的微信小程序客户端环境。

### 使用方法

1. **集成测试代码**：
   - 将 `test_wechat_miniprogram.js` 文件中的代码复制到微信小程序的页面 JavaScript 文件中
   - 将注释中的 WXML 和 WXSS 代码分别复制到对应的 `.wxml` 和 `.wxss` 文件中

2. **配置服务器地址**：
   - 修改 `wsUrl` 变量为您的 WebSocket 服务器地址
   - 注意：微信小程序要求使用 HTTPS/WSS 协议，需要配置 SSL 证书

3. **运行测试**：
   - 在微信开发者工具中打开小程序项目
   - 进入包含测试代码的页面
   - 点击 "连接" 按钮建立 WebSocket 连接
   - 使用测试按钮发送消息并查看接收结果

### 注意事项

- **微信小程序 WebSocket 限制**：
  - 只支持 HTTPS/WSS 协议
  - 需要在小程序管理后台配置合法域名
  - 最多同时存在 5 个 WebSocket 连接

- **调试建议**：
  - 使用微信开发者工具的调试模式查看日志
  - 先在浏览器端测试确保服务器正常
  - 注意网络环境和防火墙设置

## 测试场景和用例

### 基本连接测试

| 测试场景 | 预期结果 | 测试文件 |
|---------|---------|---------|
| 连接默认测试路径 | 成功连接，收到欢迎消息 | 所有测试文件 |
| 连接 aikefu 插件路径 | 成功连接 | 所有测试文件 |
| 断开连接 | 连接关闭，收到关闭通知 | 所有测试文件 |
| 重连 | 成功重新建立连接 | 浏览器和小程序测试文件 |

### 消息功能测试

| 测试场景 | 预期结果 | 测试文件 |
|---------|---------|---------|
| 发送 Ping 消息 | 收到 Pong 响应 | 所有测试文件 |
| 发送测试消息 | 收到服务器处理结果 | 所有测试文件 |
| 发送 JSON 消息 | 正确解析和处理 | 所有测试文件 |
| 发送错误格式消息 | 收到错误提示 | 所有测试文件 |

## 常见问题和解决方案

### 1. 连接失败

**可能原因**：
- WebSocket 服务器未启动
- 服务器地址或端口错误
- 防火墙或网络设置阻止连接
- 微信小程序域名未配置

**解决方案**：
- 确认服务器已启动并运行正常
- 检查服务器地址和端口配置
- 关闭防火墙或添加例外规则
- 在微信小程序管理后台配置合法域名

### 2. 消息发送失败

**可能原因**：
- WebSocket 连接已关闭
- 消息格式不正确
- 服务器处理错误

**解决方案**：
- 检查连接状态，必要时重新连接
- 确保消息格式符合 JSON 规范
- 查看服务器日志排查错误

### 3. 接收消息异常

**可能原因**：
- 服务器返回格式错误
- 网络传输问题
- 客户端解析错误

**解决方案**：
- 检查服务器代码确保返回正确格式
- 检查网络连接稳定性
- 查看客户端日志排查解析错误

## 测试完成后的清理

测试完成后，您可以：

1. **停止 WebSocket 服务器**：
   在运行服务器的终端中按 `Ctrl+C` 停止服务器。

2. **关闭测试客户端**：
   - 浏览器测试：关闭浏览器标签页
   - PHP 测试：测试完成后自动退出
   - 微信小程序测试：退出小程序页面

## 扩展测试建议

1. **性能测试**：
   - 测试同时连接多个客户端
   - 测试大消息传输
   - 测试长时间连接稳定性

2. **异常场景测试**：
   - 服务器意外关闭
   - 网络中断恢复
   - 消息丢失场景

3. **功能完整性测试**：
   - 测试所有消息类型
   - 测试错误处理机制
   - 测试安全验证功能

## 联系和支持

如果在测试过程中遇到问题，请联系开发人员或查看服务器日志获取更多信息。

---

**更新时间**：2025-12-19  
**版本**：1.0.0  
**维护人员**：WebSocket 开发团队