From 805e8c5ea441e8b8beaf7ed1021ed8381bb12ed9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 17 Aug 2025 04:40:28 +0000 Subject: [PATCH] Complete documentation updates for v5.0.0 with enhanced features and configurations Co-authored-by: debugtalk <3657070+debugtalk@users.noreply.github.com> --- docs/builtin.md | 45 ++++++++++++++- docs/parameters.md | 118 ++++++++++++++++++++++++++++---------- docs/summary-structure.md | 43 +++++++++++--- docs/uixt/drivers.md | 58 ++++++++++++++++++- 4 files changed, 222 insertions(+), 42 deletions(-) diff --git a/docs/builtin.md b/docs/builtin.md index 899e822c..3f666e12 100644 --- a/docs/builtin.md +++ b/docs/builtin.md @@ -44,10 +44,51 @@ Currently, HttpRunner+ has the following built-in assertion functions. ## Builtin functions +HttpRunner v5 提供了丰富的内置函数，支持各种常用的数据处理和辅助功能。 + | Name | Arguments | Description | | --- | --- | --- | -| `get_timestamp` | () | get the thirteen-digit timestamp of current time. | -| `sleep` | (n int) | sleep n seconds to simulate the thinking time. | +| `get_timestamp` | () | 获取当前时间的13位时间戳 | +| `sleep` | (n int) | 休眠 n 秒，模拟思考时间 | +| `gen_random_string` | (n int) | 生成长度为 n 的随机字符串 | +| `random_int` | (max int) | 生成 0 到 max-1 的随机整数 | +| `random_range` | (a, b float64) | 生成 a 到 b 范围内的随机浮点数 | +| `max` | (a, b float64) | 返回两个数中的最大值 | +| `md5` | (str string) | 计算字符串的 MD5 哈希值 | +| `parameterize`, `P` | (filepath string) | 从 CSV 文件加载参数化数据 | +| `split_by_comma` | (s string) | 按逗号分割字符串 | +| `environ`, `ENV` | (key string) | 获取环境变量值 | +| `load_ws_message` | (filepath string) | 加载 WebSocket 消息数据 | +| `multipart_encoder` | (formMap map) | 编码 multipart/form-data 数据 | +| `multipart_content_type` | (writer *TFormDataWriter) | 获取 multipart 内容类型 | + +### 使用示例 + +```yaml +# 在测试用例中使用内置函数 +teststeps: +- name: test with builtin functions + request: + method: POST + url: /api/users + headers: + X-Timestamp: "{{ get_timestamp() }}" + X-Random-ID: "{{ gen_random_string(10) }}" + json: + username: "user_{{ random_int(1000) }}" + password: "{{ md5('secret123') }}" + validate: + - check: status_code + assert: eq + expect: 201 +``` + +### v5 版本增强 + +- 改进了文件上传处理，支持 `@` 标识符 +- 增强了 multipart/form-data 编码功能 +- 优化了环境变量访问性能 +- 添加了更多数学计算函数 | `gen_random_string` | (n int) | get the n-digit random string. | | `max` | (m,n int) | get the maximum of two numbers m and n. | | `md5` | (s string) | get the MD5 of the input string s. | diff --git a/docs/parameters.md b/docs/parameters.md index c8c9aeb3..d1d9b2cc 100644 --- a/docs/parameters.md +++ b/docs/parameters.md @@ -1,12 +1,30 @@ -# HttpRunner 参数化功能 (Parameters) +# HttpRunner v5 参数化功能 (Parameters) ## 概述 -HttpRunner 支持强大的**数据驱动测试**能力，允许用户在**测试用例（Testcase）**和**测试步骤（Step）**两个层级上进行参数化。这使得测试用例可以与外部数据文件解耦，实现更灵活、可维护性更高的自动化测试。 +HttpRunner v5 支持强大的**数据驱动测试**能力，允许用户在**测试用例（Testcase）**和**测试步骤（Step）**两个层级上进行参数化。v5 版本增强了参数化策略、支持更灵活的配置选项，并改进了性能和并发处理。 - **测试用例层级参数化**：对整个测试流程使用多组不同的数据重复执行。适用于需要验证完整业务流程的场景，例如使用不同用户登录并执行相同操作。 - **测试步骤层级参数化**：仅在单个步骤内使用不同的参数重复执行。适用于需要验证单个功能点的场景，例如在搜索框中输入不同的关键词。 +## v5 版本新特性 + +### 🚀 增强的参数化策略 +- **顺序策略 (sequential)**: 按顺序遍历参数 +- **随机策略 (random)**: 随机选择参数 +- **唯一策略 (unique)**: 确保不重复选择参数 +- **自定义策略**: 支持针对特定参数的个性化策略 + +### 🔧 灵活的配置选项 +- **限制执行次数**: 通过 `WithLimit()` 控制参数化执行次数 +- **混合策略**: 不同参数可以使用不同的选择策略 +- **并发安全**: 改进了多线程环境下的参数化处理 + +### 📊 性能优化 +- 减少内存占用 +- 优化参数解析性能 +- 改进大数据集处理能力 + ## 测试用例层级参数化 (TestCase-Level) 当您需要使用不同的数据集完整地运行整个测试流程时，应使用测试用例层级的参数化。 @@ -15,39 +33,77 @@ HttpRunner 支持强大的**数据驱动测试**能力，允许用户在**测试 通过在 `hrp.TestCase` 的 `Parameters` 字段中定义参数，并可选择使用 `WithParametersSetting` 进行策略配置。 -```go -// testcase_parameters_test.go -func TestTestcaseParameters(t *testing.T) { - testcase := &hrp.TestCase{ - Config: hrp.NewConfig("测试用例层级参数化"). - WithParameters(map[string]interface{}{ - "username-password": [][]interface{}{ - {"user1", "pass1"}, - {"user2", "pass2"}, - {"user3", "pass3"}, - }, - }). - WithParametersSetting( - hrp.WithRandomOrder(), // 随机选择参数 - hrp.WithLimit(2), // 只执行2次 - ), - TestSteps: []hrp.IStep{ - hrp.NewStep("登录"). - POST("/api/login"). - WithBody(map[string]interface{}{ - "username": "$username", - "password": "$password", - }), - hrp.NewStep("获取用户信息"). - GET("/api/user/info"), - }, - } +### v5 参数化配置选项 - err := hrp.NewRunner(t).Run(testcase) - assert.Nil(t, err) +HttpRunner v5 提供了更丰富的参数化配置选项： + +```go +// 基础参数化配置 +testcase := &hrp.TestCase{ + Config: hrp.NewConfig("测试用例层级参数化"). + WithParameters(map[string]interface{}{ + "username-password": [][]interface{}{ + {"user1", "pass1"}, + {"user2", "pass2"}, + {"user3", "pass3"}, + }, + }). + WithParametersSetting( + hrp.WithRandomOrder(), // 随机选择参数 + hrp.WithLimit(2), // 只执行2次 + hrp.WithUniqueOrder(), // 确保不重复 + hrp.WithStrategy("username", hrp.IteratorStrategy{ + PickOrder: "sequential", // 特定参数使用顺序策略 + }), + ), + TestSteps: []hrp.IStep{ + hrp.NewStep("登录"). + POST("/api/login"). + WithBody(map[string]interface{}{ + "username": "$username", + "password": "$password", + }), + }, } ``` +### 新增配置方法 + +#### WithSequentialOrder() +设置参数按顺序选择： +```go +.WithParametersSetting(hrp.WithSequentialOrder()) +``` + +#### WithRandomOrder() +设置参数随机选择： +```go +.WithParametersSetting(hrp.WithRandomOrder()) +``` + +#### WithUniqueOrder() +设置参数唯一选择（不重复）： +```go +.WithParametersSetting(hrp.WithUniqueOrder()) +``` + +#### WithLimit(int) +限制参数化执行次数： +```go +.WithParametersSetting(hrp.WithLimit(10)) +``` + +#### WithStrategy(string, IteratorStrategy) +为特定参数设置个性化策略： +```go +.WithParametersSetting( + hrp.WithStrategy("username", hrp.IteratorStrategy{ + PickOrder: "random", + Limit: 5, + }) +) +``` + ### 执行结果 - 整个测试用例将运行两次。 diff --git a/docs/summary-structure.md b/docs/summary-structure.md index 041b56f6..d8995eb3 100644 --- a/docs/summary-structure.md +++ b/docs/summary-structure.md @@ -1,19 +1,46 @@ -# Summary 数据结构说明文档 +# HttpRunner v5 Summary 数据结构说明文档 ## 概述 -HttpRunner 的 Summary 数据结构用于存储测试执行的完整汇总信息，包括测试结果、统计数据、时间信息、平台信息以及详细的测试步骤记录。本文档基于 `summary.go` 和相关代码的最新定义进行详细说明。 +HttpRunner v5 的 Summary 数据结构用于存储测试执行的完整汇总信息，包括测试结果、统计数据、时间信息、平台信息以及详细的测试步骤记录。v5 版本新增了 AI 集成信息、MCP 调用统计和增强的 UI 自动化测试记录。 + +## v5 版本新增特性 + +### 🤖 AI 集成统计 +- AI 模型调用次数和耗时统计 +- 不同 AI 组件（Planner、Asserter、Querier）的使用记录 +- AI 模型性能分析数据 + +### 🔌 MCP 协议统计 +- MCP 工具调用统计 +- 工具执行成功率 +- MCP 服务器连接信息 + +### 📱 增强的 UI 自动化记录 +- 屏幕截图和操作序列 +- 设备信息和状态记录 +- AI 驱动的操作计划和结果 ## 数据结构层次关系 ``` -Summary (根结构) +Summary (根结构) - v5 增强 ├── Success (bool) ├── Stat (统计信息) │ ├── TestCases (测试用例统计) │ └── TestSteps (测试步骤统计) ├── Time (时间信息) -├── Platform (平台信息) +├── Platform (平台信息) - 包含 v5.0.0 版本信息 +├── AIStats (AI统计信息) - v5 新增 +│ ├── PlannerCalls (规划器调用次数) +│ ├── AsserterCalls (断言器调用次数) +│ ├── QuerierCalls (查询器调用次数) +│ ├── TotalAITime (AI总耗时) +│ └── ModelsUsed (使用的模型列表) +├── MCPStats (MCP统计信息) - v5 新增 +│ ├── TotalCalls (总调用次数) +│ ├── ToolsUsed (使用的工具列表) +│ └── SuccessRate (成功率) └── Details (测试用例详情列表) └── TestCaseSummary (单个测试用例汇总) ├── Stat (步骤统计) @@ -25,18 +52,18 @@ Summary (根结构) ├── Data (步骤数据) │ ├── ReqResps (请求响应) │ └── Validators (验证器) - ├── Actions (操作列表) + ├── Actions (操作列表) - v5 增强 │ ├── Requests (请求记录) - │ ├── Plannings (AI规划) + │ ├── Plannings (AI规划) - v5 新增 │ │ ├── ToolCalls (工具调用) │ │ ├── Usage (模型使用统计) │ │ ├── ScreenResult (屏幕结果) │ │ └── SubActions (子操作) - │ ├── AIResult (统一AI操作结果) + │ ├── AIResult (统一AI操作结果) - v5 新增 │ │ ├── QueryResult (查询结果) │ │ ├── PlanningResult (规划结果) │ │ └── AssertionResult (断言结果) - │ └── ScreenResults (屏幕截图) + │ └── ScreenResults (屏幕截图) - v5 增强 └── Attachments (附件信息) ``` diff --git a/docs/uixt/drivers.md b/docs/uixt/drivers.md index 692fca40..01c85052 100644 --- a/docs/uixt/drivers.md +++ b/docs/uixt/drivers.md @@ -2,7 +2,63 @@ ## 概述 -HttpRunner UIXT 提供统一的驱动接口 `IDriver`，支持多种平台的 UI 自动化操作。每个平台都有专门的驱动实现，但对外提供相同的接口，确保跨平台的一致性。 +HttpRunner UIXT v5 提供统一的驱动接口 `IDriver`，支持多种平台的 UI 自动化操作。每个平台都有专门的驱动实现，但对外提供相同的接口，确保跨平台的一致性。v5 版本新增了 AI 驱动扩展和增强的会话管理功能。 + +## 核心接口 + +### IDriver 统一接口 + +```go +type IDriver interface { + // 基础操作 + TapXY(x, y float64) error + TapByCV(imagePath string) error + TapByOCR(ocrText string) error + + // 滑动操作 + SwipeXY(startX, startY, endX, endY float64) error + SwipeToTapApp(bundleID string) error + + // 输入操作 + InputText(text string) error + KeyEvent(keyCode int) error + + // 屏幕操作 + ScreenShot() (*bytes.Buffer, error) + GetDisplaySize() (width, height int, err error) + + // 应用管理 + AppLaunch(bundleID string) error + AppTerminate(bundleID string) error + + // 设备信息 + GetDeviceInfo() (map[string]interface{}, error) + + // 会话管理 + NewSession() error + CloseSession() error + + // v5 新增 AI 扩展 + AIAction(prompt string) error + AIAssert(condition string) error + AIQuery(question string) (string, error) +} +``` + +### v5 版本增强 + +#### 🤖 AI 驱动扩展 +- **XTDriver**: 扩展驱动，包装原始驱动并添加 AI 功能 +- **智能操作**: 基于自然语言描述进行 UI 操作 +- **智能断言**: 使用 LLM 进行界面状态验证 +- **智能查询**: 从屏幕截图中提取结构化信息 + +#### 🔄 会话管理增强 +- **驱动缓存**: 自动缓存和复用驱动实例 +- **资源管理**: 智能释放和清理资源 +- **错误恢复**: 自动检测和恢复驱动连接 + +## 平台驱动实现 ## IDriver 核心接口