e2e

name	e2e
description	执行 E2E 测试用例。 根据测试用例的验证类型（ui/api/database）选择正确的工具执行验证。
user-invocable	true

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 环境

# 当前工作目录的 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 文件获取正确端口：

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

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

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

4. 确认环境运行中

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

---

环境变量与 URL 构建

浏览器 URL（UI 测试）

# 正确：使用 .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

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

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

数据库连接

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"

---

测试数据

数据	值
测试用户邮箱	[e-mail]
测试用户密码	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 工具进行浏览器验证。

执行前准备

# 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: "[e-mail]")
   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）

示例：验证页面元素存在

# 测试用例要求
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

# 切换到当前 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":"[e-mail]","password":"devpass123"}' | jq -r '.token')

echo "Token: ${TOKEN}"

API 调用模板

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 查询。

获取正确的容器名

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 查询

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, seat_count
  FROM subscriptions
  WHERE organization_id = (SELECT id FROM organizations WHERE slug = 'dev-org');
"

Setup/Cleanup SQL

source deploy/dev/.env
WORKTREE_DIR=$(basename "$(git rev-parse --show-toplevel)")
POSTGRES_CONTAINER="agentsmesh-${WORKTREE_DIR}-postgres-1"

# 执行 setup SQL
docker exec ${POSTGRES_CONTAINER} psql -U agentsmesh -d agentsmesh -c "
  INSERT INTO promo_codes (code, ...) VALUES ('TESTCODE', ...);
"

# 执行 cleanup SQL
docker exec ${POSTGRES_CONTAINER} psql -U agentsmesh -d agentsmesh -c "
  DELETE FROM promo_code_uses WHERE ...;
"

---

完整执行流程

0. 确认环境（最重要！）

# 切换到当前 worktree 的 dev 环境
cd <当前worktree>/deploy/dev
source .env

# 确认服务运行中
docker compose ps

# 记录关键信息
echo "WEB_PORT: ${WEB_PORT}"
echo "WORKTREE: $(basename "$(git rev-parse --show-toplevel)")"

1. 读取测试用例

读取 YAML 文件，解析：
- preconditions: 前置条件
- setup: 初始化数据
- steps: 测试步骤
- cleanup: 清理数据

2. 执行 Setup

如果有 setup.sql，先执行数据库初始化。

3. 逐步执行 Steps

对每个 step：

1. 读取 action 描述
2. 根据 verification.type 选择工具：
   - ui → MCP Chrome DevTools（使用 ${WEB_PORT}）
   - api → curl（使用 ${WEB_PORT}）
   - database → docker exec psql（使用正确容器名）
3. 执行操作
4. 验证 expected 结果
5. 记录 PASS/FAIL

4. 执行 Cleanup

执行清理 SQL，恢复测试环境。

5. 输出报告

=== TC-XXX-001: 测试用例名称 ===
环境: feature-payment-membership (WEB_PORT=8080)

Step 1: [操作描述] ✅ PASS
Step 2: [操作描述] ✅ PASS
Step 3: [操作描述] ❌ FAIL - 期望 "xxx"，实际 "yyy"

结果: 2/3 PASS

---

常见问题

Q: 页面无法访问 / Connection refused？

1. 检查端口是否正确：

   source deploy/dev/.env && echo "WEB_PORT: ${WEB_PORT}"
   

2. 确认服务运行中：

   docker compose ps
   

3. 不要使用默认端口 80，每个 worktree 端口不同

Q: 数据库容器找不到？

1. 容器名包含 worktree 目录名：

   # 查看实际容器名
   docker compose ps
   

Q: API 返回 401？

1. Token 可能过期，重新获取
2. 确认使用的是当前环境的 WEB_PORT

Q: UI 测试用 API 模拟？

🚨 错误做法！ UI 测试必须使用 MCP Chrome DevTools 进行真实的浏览器验证。

Q: 可以跳过 UI 测试吗？

🚨 绝对不可以！ UI 测试是 E2E 测试的核心：

1. 不要因为 MCP 不可用就跳过：先解决 MCP 连接问题
2. 不要用 API 替代：API 测试无法验证前端渲染
3. 不要因为"太慢"就跳过：UI 测试发现的问题往往是最关键的

如果 MCP Chrome DevTools 无法连接：

1. 确认 Chrome 浏览器已打开
2. 确认 MCP 服务已配置并运行
3. 尝试 mcp__chrome-devtools__list_pages 检查连接
4. 如仍无法连接，报告问题，不要跳过测试

---

命令速查

操作	命令/工具
获取端口	source deploy/dev/.env && echo $WEB_PORT
获取容器名	docker compose ps
导航页面	mcp__chrome-devtools__navigate_page
获取快照	mcp__chrome-devtools__take_snapshot
截图	mcp__chrome-devtools__take_screenshot
点击	mcp__chrome-devtools__click
输入	mcp__chrome-devtools__fill
等待文本	mcp__chrome-devtools__wait_for
API 调用	curl -s "http://localhost:${WEB_PORT}/api/v1/..."
数据库查询	docker exec <container> psql -U agentsmesh -d agentsmesh -c "SQL"

---

注意事项

1. 🚨 UI 测试禁止跳过：所有 verification.type: ui 的测试必须使用 MCP Chrome DevTools 执行
2. UI ≠ API：绝对不要用 API 调用代替 UI 验证
3. 先确认环境：执行前先 source deploy/dev/.env 获取正确端口
4. 不要硬编码端口：使用 ${WEB_PORT} 变量
5. 区分验证类型：严格按 verification.type 选择工具
6. 容器名包含 worktree 名：不要使用通用容器名
7. 执行 Cleanup：测试后清理数据，避免影响其他测试