# gitlink-cli webhook +test

测试 Webhook 连接性，发送测试事件验证 Webhook 是否正常工作。

## 命令格式

```bash
gitlink-cli webhook +test \
  [--owner OWNER] \
  [--repo REPO] \
  --id WEBHOOK_ID \
  [--event EVENT_TYPE]
```

## 参数说明

| 参数 | 短参数 | 说明 | 是否必须 | 默认值 |
|------|--------|------|----------|--------|
| `--owner` | `-o` | 仓库所有者 | 否 | 自动从 git remote 解析 |
| `--repo` | `-r` | 仓库名称 | 否 | 自动从 git remote 解析 |
| `--id` | `-i` | Webhook ID | **是** | - |
| `--event` | `-e` | 测试的事件类型 | 否 | `push` |

### 支持的测试事件
- `push` - 推送事件（默认）
- `pull_request` - Pull 请求事件
- `issue` - Issue 事件
- 其他支持的事件类型

## 返回值

### 成功返回
```json
{
  "ok": true,
  "data": {
    "message": "Webhook test triggered successfully",
    "webhook_id": "456",
    "event_type": "push",
    "delivered": true,
    "response_status": 200,
    "response_body": "Webhook received"
  },
  "meta": {
    "identity": "user:myuser"
  }
}
```

### Webhook 不可达
```json
{
  "ok": true,
  "data": {
    "message": "Webhook test completed with warnings",
    "webhook_id": "456",
    "event_type": "push",
    "delivered": false,
    "error": "Connection timeout",
    "suggestion": "Please check if the webhook URL is accessible"
  }
}
```

### 错误返回
```json
{
  "ok": false,
  "error": {
    "code": 404,
    "message": "Webhook not found",
    "suggestion": "Please check the webhook ID"
  }
}
```

## 使用示例

### 基本测试
```bash
# 测试 Webhook（默认使用 push 事件）
gitlink-cli webhook +test --owner myuser --repo myrepo --id 456

# 在 git 仓库目录中测试
gitlink-cli webhook +test --id 456

# 使用短参数
gitlink-cli webhook +test -i 456
```

### 测试特定事件类型
```bash
# 测试 pull_request 事件
gitlink-cli webhook +test --id 456 --event pull_request

# 测试 issue 事件
gitlink-cli webhook +test --id 456 --event issue

# 测试多种事件类型
for event in push pull_request issue; do
    echo "Testing event: $event"
    gitlink-cli webhook +test --id 456 --event $event
done
```

### 批量测试所有 Webhook
```bash
# 测试仓库的所有 Webhook
for id in $(gitlink-cli webhook +list --format json | jq -r '.data.webhooks[].id'); do
    echo "Testing webhook: $id"
    gitlink-cli webhook +test --id $id
done
```

### 测试新创建的 Webhook
```bash
# 创建后立即测试
WEBHOOK_ID=$(gitlink-cli webhook +create --url https://example.com/webhook --events push --format json | jq -r '.data.id')
echo "Testing new webhook: $WEBHOOK_ID"
gitlink-cli webhook +test --id $WEBHOOK_ID
```

## 错误处理

### 常见错误

#### 1. Webhook 不存在
```bash
Error: [404] Webhook not found
```
**原因**: 指定的 Webhook ID 不存在
**解决方案**:
```bash
# 先列出所有 Webhook 找到正确 ID
gitlink-cli webhook +list
```

#### 2. 无效的事件类型
```bash
Error: unsupported event type: custom_event
```
**原因**: 指定了不支持的事件类型
**解决方案**:
```bash
# 查看支持的事件类型
gitlink-cli webhook +events

# 使用支持的事件类型
gitlink-cli webhook +test --id 456 --event push
```

#### 3. Webhook URL 不可达
```bash
Warning: Webhook delivery failed - Connection timeout
```
**原因**: Webhook URL 无法访问或服务器无响应
**解决方案**:
```bash
# 1. 检查 URL 是否正确
gitlink-cli webhook +info --id 456

# 2. 手动测试 URL
curl -X POST https://your-webhook-url.com/test

# 3. 检查服务器防火墙和网络设置
```

#### 4. SSL 证书问题
```bash
Warning: Webhook delivery failed - SSL certificate verify failed
```
**原因**: Webhook 服务器的 SSL 证书有问题
**解决方案**:
```bash
# 检查 SSL 证书
curl -v https://your-webhook-url.com/test

# 更新服务器的 SSL 证书
```

## 最佳实践

### 1. 创建后测试
```bash
# 创建 Webhook 后立即测试
WEBHOOK_ID=$(gitlink-cli webhook +create --url $URL --events $EVENTS --format json | jq -r '.data.id')
if gitlink-cli webhook +test --id $WEBHOOK_ID; then
    echo "Webhook created and tested successfully"
else
    echo "Webhook test failed, please check configuration"
    gitlink-cli webhook +delete --id $WEBHOOK_ID
fi
```

### 2. 更新后测试
```bash
# 更新 Webhook 后测试
gitlink-cli webhook +update --id 456 --url $NEW_URL
gitlink-cli webhook +test --id 456
```

### 3. 定期测试
```bash
# 定期测试所有 Webhook 确保正常工作
for id in $(gitlink-cli webhook +list --format json | jq -r '.data.webhooks[].id'); do
    if ! gitlink-cli webhook +test --id $id; then
        echo "WARNING: Webhook $id test failed"
    fi
done
```

## AI Agent 使用建议

### 自动化测试流程
```bash
# AI Agent 测试 Webhook 的完整流程
test_and_fix_webhook() {
    WEBHOOK_ID=$1
    MAX_RETRIES=3
    RETRY_COUNT=0

    while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
        echo "Testing webhook $WEBHOOK_ID (attempt $((RETRY_COUNT + 1))/$MAX_RETRIES)"

        # 测试 Webhook
        if gitlink-cli webhook +test --id $WEBHOOK_ID; then
            echo "✓ Webhook test successful"
            return 0
        fi

        # 测试失败，等待后重试
        RETRY_COUNT=$((RETRY_COUNT + 1))
        if [ $RETRY_COUNT -lt $MAX_RETRIES ]; then
            echo "Test failed, waiting 5 seconds before retry..."
            sleep 5
        fi
    done

    echo "✗ Webhook test failed after $MAX_RETRIES attempts"
    return 1
}
```

### 监控 Webhook 健康
```bash
# 定期检查所有 Webhook 的健康状态
check_all_webhooks_health() {
    REPORT_FILE="webhook_health_report_$(date +%Y%m%d_%H%M%S).txt"

    echo "Webhook Health Check Report - $(date)" > $REPORT_FILE
    echo "=================================" >> $REPORT_FILE

    for id in $(gitlink-cli webhook +list --format json | jq -r '.data.webhooks[].id'); do
        webhook_info=$(gitlink-cli webhook +info --id $id --format json)
        webhook_url=$(echo $webhook_info | jq -r '.data.hook_url')
        webhook_status=$(echo $webhook_info | jq -r '.data.is_active')

        echo -e "\nWebhook ID: $id" >> $REPORT_FILE
        echo "URL: $webhook_url" >> $REPORT_FILE
        echo "Active: $webhook_status" >> $REPORT_FILE
        echo "Test Result:" >> $REPORT_FILE

        if gitlink-cli webhook +test --id $id >> $REPORT_FILE 2>&1; then
            echo "Status: HEALTHY ✓" >> $REPORT_FILE
        else
            echo "Status: UNHEALTHY ✗" >> $REPORT_FILE
        fi
    done

    cat $REPORT_FILE
}
```

### 故障诊断
```bash
# 诊断 Webhook 问题
diagnose_webhook() {
    WEBHOOK_ID=$1

    echo "=== Webhook Diagnosis ==="
    echo "Webhook ID: $WEBHOOK_ID"
    echo

    # 1. 检查 Webhook 是否存在
    echo "1. Checking webhook existence..."
    if ! gitlink-cli webhook +info --id $WEBHOOK_ID >/dev/null 2>&1; then
        echo "   ✗ Webhook not found"
        return 1
    fi
    echo "   ✓ Webhook exists"

    # 2. 获取 Webhook 配置
    echo "2. Webhook configuration:"
    gitlink-cli webhook +info --id $WEBHOOK_ID

    # 3. 测试网络连通性
    echo "3. Testing network connectivity..."
    WEBHOOK_URL=$(gitlink-cli webhook +info --id $WEBHOOK_ID --format json | jq -r '.data.hook_url')
    if curl -s -o /dev/null -w "%{http_code}" "$WEBHOOK_URL" | grep -q "200\|301\|302"; then
        echo "   ✓ URL is accessible"
    else
        echo "   ✗ URL is not accessible"
    fi

    # 4. 测试 Webhook
    echo "4. Testing webhook delivery..."
    if gitlink-cli webhook +test --id $WEBHOOK_ID; then
        echo "   ✓ Webhook test successful"
    else
        echo "   ✗ Webhook test failed"
    fi
}
```

## 注意事项

1. **测试限制**: 测试事件不会触发实际的业务逻辑，仅验证连通性
2. **请求格式**: 测试请求的格式与真实事件略有不同
3. **响应时间**: Webhook 应在 10 秒内响应，否则超时
4. **重试机制**: 测试失败不会触发 GitLink 的重试机制
5. **权限要求**: 需要仓库管理员权限

## 常见使用场景

### 场景1: 验证新 Webhook
```bash
# 创建 Webhook 后验证配置
WEBHOOK_ID=$(gitlink-cli webhook +create \
  --url https://ci.example.com/webhook \
  --events push,pull_request \
  --format json | jq -r '.data.id')

# 测试各种事件类型
for event in push pull_request; do
    echo "Testing $event event..."
    gitlink-cli webhook +test --id $WEBHOOK_ID --event $event
done
```

### 场景2: 故障排查
```bash
# Webhook 未触发时进行测试
# 1. 检查 Webhook 是否激活
gitlink-cli webhook +info --id 456

# 2. 测试 Webhook 连通性
gitlink-cli webhook +test --id 456

# 3. 查看详细错误信息
gitlink-cli webhook +test --id 456 --debug
```

### 场景3: 批量验证
```bash
# 验证所有 Webhook 在服务器迁移后是否正常
for id in $(gitlink-cli webhook +list --format json | jq -r '.data.webhooks[].id'); do
    echo "Testing webhook $id..."
    if ! gitlink-cli webhook +test --id $id; then
        echo "WARNING: Webhook $id needs attention"
        # 可以在这里添加自动修复逻辑
    fi
done
```

## 安全建议

1. **避免敏感数据**: 测试事件可能包含真实数据，注意隐私保护
2. **测试频率**: 不要过于频繁测试，避免对服务器造成压力
3. **错误信息**: 测试失败时的错误信息可能暴露系统细节
4. **访问控制**: 确保测试 URL 只暴露必要的信息

## 相关命令

- `webhook +list` - 列出所有 Webhook
- `webhook +info` - 查看 Webhook 详情
- `webhook +create` - 创建新 Webhook
- `webhook +update` - 更新 Webhook 配置
- `webhook +events` - 查看支持的事件类型
