e2e

# E2E 测试执行指南

执行 `e2e/` 目录下的端到端测试用例。

## 🚨 强制要求：UI 测试必须执行

**⚠️ 禁止跳过 UI 测试！UI 测试是 E2E 测试的核心，必须使用 MCP Chrome DevTools 执行真实的浏览器验证。**

### UI 测试执行规则

1. **不可跳过**：任何 `verification.type: ui` 的测试步骤都必须执行
2. **不可替代**：禁止用 API 调用代替 UI 验证
3. **必须使用浏览器**：使用 MCP Chrome DevTools 工具（`mcp__chrome-devtools__*`）
4. **验证真实渲染**：确保页面元素真实渲染，而非仅验证数据存在

### 为什么 UI 测试重要？

- API 测试只验证数据，UI 测试验证用户体验
- 前端渲染问题只能通过 UI 测试发现
- 交互逻辑（点击、输入、导航）必须在浏览器中验证
- 响应式布局和样式问题需要实际渲染才能发现

## ⚠️ 关键：使用当前 Worktree 的开发环境

**每个 worktree 有独立的 Docker 环境和端口配置！**

### 1. 定位当前 Worktree 的 dev 环境

```bash
# 当前工作目录的 deploy/dev 目录
cd <当前worktree根目录>/deploy/dev

# 例如：
# /Users/stone/Works/AIO/AgentsMesh-Worktrees/feature-payment-membership/deploy/dev
# /Users/stone/Works/AIO/AgentsMesh-Worktrees/feature-xxx/deploy/dev
```

### 2. 获取当前环境的端口配置

**必须先 source 当前 worktree 的 .env 文件获取正确端口：**

```bash
cd <当前worktree>/deploy/dev
source .env

# 查看关键端口
echo "WEB_PORT: ${WEB_PORT}"           # Web/Nginx 端口（用于浏览器和 API）
echo "POSTGRES_PORT: ${POSTGRES_PORT}" # 数据库端口
echo "REDIS_PORT: ${REDIS_PORT}"       # Redis 端口
```

### 3. Docker 容器命名规则

容器名称包含 worktree 目录名，格式为：`agentsmesh-<worktree-dir>-<service>-1`

```bash
# 查看当前环境的容器
docker compose ps

# 示例容器名：
# agentsmesh-feature-payment-membership-postgres-1
# agentsmesh-feature-payment-membership-backend-1
# agentsmesh-feature-payment-membership-web-1
```

### 4. 确认环境运行中

```bash
cd <当前worktree>/deploy/dev
docker compose ps  # 确认所有服务 Up 且 healthy
```

---

## 环境变量与 URL 构建

### 浏览器 URL（UI 测试）

```bash
# 正确：使用 .env 中的 WEB_PORT
source deploy/dev/.env
URL="http://localhost:${WEB_PORT}/dev-org/settings?scope=organization&tab=billing"

# 错误：硬编码端口
URL="http://localhost/..."      # ❌ 可能不是当前环境
URL="http://localhost:80/..."   # ❌ 端口可能不对
```

### API URL

```bash
source deploy/dev/.env
API_BASE="http://localhost:${WEB_PORT}/api/v1"

# 示例
curl -s "${API_BASE}/orgs/dev-org/billing/subscription"
```

### 数据库连接

```bash
source deploy/dev/.env

# 获取容器名（基于 worktree 目录名）
WORKTREE_DIR=$(basename "$(git rev-parse --show-toplevel)")
POSTGRES_CONTAINER="agentsmesh-${WORKTREE_DIR}-postgres-1"

# 执行 SQL
docker exec ${POSTGRES_CONTAINER} psql -U agentsmesh -d agentsmesh -c "SELECT 1"
```

---

## 测试数据

| 数据 | 值 |
|------|-----|
| 测试用户邮箱 | dev@agentsmesh.local |
| 测试用户密码 | devpass123 |
| 测试组织 slug | dev-org |
| 账单页面路径 | /dev-org/settings?scope=organization&tab=billing |

---

## 验证方式与工具选择

### ⚠️ 重要：根据 `verification.type` 选择正确的工具

| 类型 | 说明 | 使用的工具 | 优先级 |
|------|------|-----------|--------|
| `ui` | 浏览器页面验证 | **MCP Chrome DevTools** | 🔴 最高优先级，禁止跳过 |
| `api` | API 调用验证 | **Bash (curl)** | 正常优先级 |
| `database` | 数据库查询验证 | **Bash (docker exec psql)** | 正常优先级 |

### 🚨 UI 测试不可跳过的原因

```
❌ 错误做法：
   "UI 测试需要浏览器，我先跳过，只执行 API 测试"
   "MCP 工具不可用，改用 curl 验证"

✅ 正确做法：
   1. 确认 Chrome 浏览器已打开并可通过 MCP 连接
   2. 使用 mcp__chrome-devtools__* 工具执行所有 UI 验证
   3. 如果 MCP 不可用，报告问题而非跳过测试
```

---

## UI 验证 (`verification.type: ui`)

使用 **MCP Chrome DevTools** 工具进行浏览器验证。

### 执行前准备

```bash
# 1. 获取端口
source deploy/dev/.env
echo "浏览器访问: http://localhost:${WEB_PORT}"
```

### 工具列表

| 工具 | 用途 |
|------|------|
| `mcp__chrome-devtools__new_page` | 打开新页面 |
| `mcp__chrome-devtools__navigate_page` | 导航到 URL |
| `mcp__chrome-devtools__take_snapshot` | 获取页面 A11Y 快照（推荐） |
| `mcp__chrome-devtools__take_screenshot` | 截图 |
| `mcp__chrome-devtools__click` | 点击元素 |
| `mcp__chrome-devtools__fill` | 填写输入框 |
| `mcp__chrome-devtools__wait_for` | 等待文本出现 |

### 执行流程

```
1. 先获取端口
   source deploy/dev/.env
   # WEB_PORT=xxx

2. 打开/导航到目标页面（使用正确端口）
   mcp__chrome-devtools__new_page(url: "http://localhost:${WEB_PORT}/login")

3. 登录（如需要）
   mcp__chrome-devtools__fill(uid: "email-input", value: "dev@agentsmesh.local")
   mcp__chrome-devtools__fill(uid: "password-input", value: "devpass123")
   mcp__chrome-devtools__click(uid: "login-button")

4. 导航到测试页面
   mcp__chrome-devtools__navigate_page(url: "http://localhost:${WEB_PORT}/dev-org/settings?scope=organization&tab=billing")

5. 等待页面加载
   mcp__chrome-devtools__wait_for(text: "当前方案")

6. 获取页面快照
   mcp__chrome-devtools__take_snapshot()

7. 验证快照中包含预期元素
   - 检查快照文本是否包含预期内容
   - 检查元素是否存在（按钮、输入框等）
   - 检查元素状态（disabled、enabled）
```

### 示例：验证页面元素存在

```yaml
# 测试用例要求
verification:
  type: ui
  check:
    - exists: 'heading "优惠码"'
    - contains: "输入优惠码获取套餐时长"
```

执行步骤：
1. `source deploy/dev/.env` → 获取 WEB_PORT
2. `mcp__chrome-devtools__navigate_page` → 导航到账单页面
3. `mcp__chrome-devtools__wait_for` → 等待 "优惠码" 文本
4. `mcp__chrome-devtools__take_snapshot` → 获取快照
5. 分析快照：确认包含 "优惠码" 标题和描述文本

---

## API 验证 (`verification.type: api`)

使用 **curl** 进行 API 调用验证。

### 获取认证 Token

```bash
# 切换到当前 worktree 的 deploy/dev 目录
cd <当前worktree>/deploy/dev
source .env

TOKEN=$(curl -s -X POST "http://localhost:${WEB_PORT}/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@agentsmesh.local","password":"devpass123"}' | jq -r '.token')

echo "Token: ${TOKEN}"
```

### API 调用模板

```bash
source deploy/dev/.env

# GET 请求
curl -s -X GET "http://localhost:${WEB_PORT}/api/v1/orgs/dev-org/billing/subscription" \
  -H "Authorization: Bearer $TOKEN" | jq

# POST 请求
curl -s -X POST "http://localhost:${WEB_PORT}/api/v1/orgs/dev-org/billing/checkout" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"order_type":"subscription","plan_name":"pro","success_url":"http://localhost/success","cancel_url":"http://localhost/cancel"}' | jq
```

---

## 数据库验证 (`verification.type: database`)

使用 **docker exec psql** 执行 SQL 查询。

### 获取正确的容器名

```bash
cd <当前worktree>/deploy/dev
source .env

# 方法1：从 docker compose 获取
POSTGRES_CONTAINER=$(docker compose ps -q postgres)

# 方法2：根据 worktree 目录名构建
WORKTREE_DIR=$(basename "$(git rev-parse --show-toplevel)")
POSTGRES_CONTAINER="agentsmesh-${WORKTREE_DIR}-postgres-1"
```

### 执行 SQL 查询

```bash
source deploy/dev/.env
WORKTREE_DIR=$(basename "$(git rev-parse --show-toplevel)")

docker exec agentsmesh-${WORKTREE_DIR}-postgres-1 psql -U agentsmesh -d agentsmesh -c "
  SELECT status, plan_id, s