Complete documentation updates for v5.0.0 with enhanced features and configurations

Co-authored-by: debugtalk <3657070+debugtalk@users.noreply.github.com>
2026-06-23 08:33:45 +08:00 · 2025-08-17 04:40:28 +00:00
parent 5442930e5a
commit 805e8c5ea4
4 changed files with 222 additions and 42 deletions
--- 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. |
--- 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,
+    })
+)
+```
+
 ### 执行结果

 - 整个测试用例将运行两次。
--- 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 (附件信息)
 ```

--- 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 核心接口