Beacon/docs/activity_parameter_passing.md

Activity 之间参数传递指南

概述

在动态测试工作流中，多个 Activity 之间经常需要传递参数。例如，第二个 Activity 可能需要使用第一个 Activity 响应的某个字段作为入参。本文档详细说明了如何实现这种参数传递机制。

支持的变量格式

1. 全局变量

格式：${global.key}

• 用于访问工作流级别的全局变量
• 这些变量在工作流启动时通过 GlobalParameters 传入

2. 步骤结果变量

格式：${step.stepId.field}

• 用于访问之前步骤的执行结果
• stepId 是步骤的ID
• field 是结果中的具体字段

变量引用示例

API 测试结果变量

{
  "test_case_id": "api_test_001",
  "endpoint": "/api/login",
  "http_method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "request_body": "{\"username\": \"testuser\", \"password\": \"testpass\"}",
  "expected_status_code": 200
}

假设这个API测试的步骤ID是123，执行后返回：

{
  "base_result": {
    "success": true,
    "message": "API Test Passed"
  },
  "actual_status_code": 200,
  "response_body": "{\"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\", \"user_id\": 456}",
  "headers": {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "Content-Type": "application/json"
  }
}

可用的变量引用

1. 响应体：${step.123.response_body}
2. 状态码：${step.123.actual_status_code}
3. 响应头：${step.123.headers.Authorization}
4. JSON字段：${step.123.json_token} (自动提取的token字段)
5. 用户ID：${step.123.json_user_id} (自动提取的user_id字段)

实际使用场景

场景1：登录后使用Token进行API调用

步骤1：登录API

{
  "test_case_id": "login_test",
  "endpoint": "/api/login",
  "http_method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "request_body": "{\"username\": \"testuser\", \"password\": \"testpass\"}",
  "expected_status_code": 200
}

步骤2：使用Token调用受保护的API

{
  "test_case_id": "protected_api_test",
  "endpoint": "/api/user/profile",
  "http_method": "GET",
  "headers": {
    "Authorization": "${step.123.json_token}",
    "Content-Type": "application/json"
  },
  "expected_status_code": 200
}

场景2：使用响应头中的Token

{
  "test_case_id": "api_with_header_token",
  "endpoint": "/api/data",
  "http_method": "GET",
  "headers": {
    "Authorization": "${step.123.headers.Authorization}",
    "Content-Type": "application/json"
  },
  "expected_status_code": 200
}

场景3：使用响应体中的用户ID

{
  "test_case_id": "user_data_test",
  "endpoint": "/api/users/${step.123.json_user_id}/data",
  "http_method": "GET",
  "headers": {
    "Authorization": "${step.123.json_token}",
    "Content-Type": "application/json"
  },
  "expected_status_code": 200
}

UI 测试结果变量

UI 测试结果示例

{
  "base_result": {
    "success": true,
    "message": "UI Test Passed"
  },
  "screenshot_url": "https://s3.amazonaws.com/screenshots/test_001.png",
  "html_report_url": "https://s3.amazonaws.com/reports/test_001.html"
}

可用的变量引用

1. 截图URL：${step.456.screenshot_url}
2. 报告URL：${step.456.html_report_url}

全局变量使用

工作流启动时传入全局变量

input := &pb.DynamicTestRunInput{
    RunId:             "test_run_001",
    CompositeCaseId:   "composite_case_001",
    GlobalParameters: map[string]string{
        "base_url": "https://api.example.com",
        "environment": "staging",
        "api_version": "v1",
    },
}

在步骤参数中使用全局变量

{
  "test_case_id": "api_test",
  "endpoint": "${global.base_url}/${global.api_version}/users",
  "http_method": "GET",
  "headers": {
    "X-Environment": "${global.environment}",
    "Content-Type": "application/json"
  },
  "expected_status_code": 200
}

复杂场景示例

多步骤参数传递链

步骤1：用户注册

{
  "test_case_id": "user_registration",
  "endpoint": "/api/register",
  "http_method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "request_body": "{\"username\": \"newuser\", \"email\": \"newuser@example.com\", \"password\": \"password123\"}",
  "expected_status_code": 201
}

步骤2：用户登录（使用注册返回的用户ID）

{
  "test_case_id": "user_login",
  "endpoint": "/api/login",
  "http_method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "request_body": "{\"username\": \"newuser\", \"password\": \"password123\"}",
  "expected_status_code": 200
}

步骤3：获取用户信息（使用登录返回的token）

{
  "test_case_id": "get_user_info",
  "endpoint": "/api/users/${step.123.json_user_id}",
  "http_method": "GET",
  "headers": {
    "Authorization": "Bearer ${step.124.json_token}",
    "Content-Type": "application/json"
  },
  "expected_status_code": 200
}

步骤4：更新用户信息（使用步骤3的token和用户ID）

{
  "test_case_id": "update_user_info",
  "endpoint": "/api/users/${step.123.json_user_id}",
  "http_method": "PUT",
  "headers": {
    "Authorization": "Bearer ${step.124.json_token}",
    "Content-Type": "application/json"
  },
  "request_body": "{\"display_name\": \"Updated User\", \"bio\": \"This is my updated bio\"}",
  "expected_status_code": 200
}

注意事项

1. 变量解析顺序：先解析全局变量，再解析步骤变量
2. 错误处理：如果变量不存在，会保持原始占位符不变
3. 类型安全：所有变量都会被转换为字符串
4. 性能考虑：变量解析在每次步骤执行时进行，避免频繁的字符串操作
5. 调试支持：工作流日志会记录变量解析过程

最佳实践

1. 使用有意义的变量名：避免使用过于简单的变量名
2. 文档化变量：在步骤描述中说明使用的变量
3. 测试变量解析：在开发环境中测试变量解析是否正确
4. 错误处理：在步骤参数中提供默认值或错误处理逻辑
5. 版本控制：记录变量格式的变更，确保向后兼容

扩展功能

自定义变量提取器

可以通过扩展 extractApiResultToGlobalVariables 和 extractUiResultToGlobalVariables 函数来支持更多自定义字段的提取。

条件变量

可以基于步骤的成功/失败状态来设置不同的变量值。

变量验证

可以在变量解析时添加验证逻辑，确保必需的变量存在且格式正确。