Beacon/docs/activity_parameter_passing.md

# Activity 之间参数传递指南

## 概述

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

## 支持的变量格式

### 1. 全局变量
格式：`${global.key}`
- 用于访问工作流级别的全局变量
- 这些变量在工作流启动时通过 `GlobalParameters` 传入

### 2. 步骤结果变量
格式：`${step.stepId.field}`
- 用于访问之前步骤的执行结果
- `stepId` 是步骤的ID
- `field` 是结果中的具体字段

## 变量引用示例

### API 测试结果变量
```json
{
  "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，执行后返回：
```json
{
  "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**
```json
{
  "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**
```json
{
  "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

```json
{
  "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

```json
{
  "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 测试结果示例
```json
{
  "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}`

## 全局变量使用

### 工作流启动时传入全局变量
```go
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",
    },
}
```

### 在步骤参数中使用全局变量
```json
{
  "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：用户注册**
```json
{
  "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）**
```json
{
  "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）**
```json
{
  "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）**
```json
{
  "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` 函数来支持更多自定义字段的提取。

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

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