102 lines
2.9 KiB
Markdown
102 lines
2.9 KiB
Markdown
# 外部服务 API 脚本运行说明
|
|
|
|
Last Updated: 2026-04-22
|
|
|
|
本文说明 `xworkmate-app` 里两份外部服务 API 测试脚本的用途、执行方式和适用边界。
|
|
|
|
## 1. 脚本列表
|
|
|
|
### 1.1 API 接口测试脚本
|
|
|
|
- [`scripts/ci/verify_api_interface_contract.sh`](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/scripts/ci/verify_api_interface_contract.sh)
|
|
|
|
用途：
|
|
|
|
- 校验账户服务与 bridge 主入口的接口契约
|
|
- 重点验证请求路径、鉴权头、返回结构和能力面数据
|
|
|
|
### 1.2 场景测试脚本
|
|
|
|
- [`scripts/ci/verify_api_scenario_contract.sh`](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/scripts/ci/verify_api_scenario_contract.sh)
|
|
|
|
用途：
|
|
|
|
- 按真实使用链路跑完整场景
|
|
- 重点验证登录 -> 同步 -> 能力 -> 路由 -> 会话启动 / 续跑 / 取消 / 关闭
|
|
|
|
## 2. 运行前提
|
|
|
|
两份脚本都依赖以下环境变量：
|
|
|
|
- `REVIEW_ACCOUNT_LOGIN_PASSWORD`
|
|
- 可选 `BRIDGE_AUTH_TOKEN`，未提供时使用 profile sync 返回的 token
|
|
- 可选 `BRIDGE_SERVER_URL`
|
|
- 可选 `BRIDGE_SERVER_URLS`，用于接口脚本同时验证多个 bridge host
|
|
- 可选 `REVIEW_ACCOUNT_BASE_URL`
|
|
|
|
推荐直接在命令前临时注入：
|
|
|
|
```bash
|
|
REVIEW_ACCOUNT_LOGIN_PASSWORD='***REMOVED-CREDENTIAL***' \
|
|
BRIDGE_AUTH_TOKEN='<bridge token>' \
|
|
BRIDGE_SERVER_URL='https://xworkmate-bridge.svc.plus' \
|
|
bash scripts/ci/verify_api_interface_contract.sh
|
|
```
|
|
|
|
双入口验证示例：
|
|
|
|
```bash
|
|
REVIEW_ACCOUNT_LOGIN_PASSWORD='***REMOVED-CREDENTIAL***' \
|
|
BRIDGE_SERVER_URLS='https://xworkmate-bridge.svc.plus,https://cn-xworkmate-bridge.svc.plus' \
|
|
bash scripts/ci/verify_api_interface_contract.sh
|
|
```
|
|
|
|
## 3. 默认校验入口
|
|
|
|
推荐使用 `Makefile` 目标：
|
|
|
|
```bash
|
|
make test-api-contract
|
|
make test-api-scenario-contract
|
|
```
|
|
|
|
如果需要一次性执行两份脚本，可使用：
|
|
|
|
```bash
|
|
make check-api-external
|
|
```
|
|
|
|
## 4. 脚本覆盖内容
|
|
|
|
### 4.1 `test-api-contract`
|
|
|
|
- `POST /api/auth/login`
|
|
- `GET /api/auth/session`
|
|
- `GET /api/auth/xworkmate/profile/sync`
|
|
- `GET /api/ping`
|
|
- `POST /acp/rpc` with `acp.capabilities`
|
|
- `POST /acp/rpc` with `xworkmate.routing.resolve`
|
|
|
|
### 4.2 `test-api-scenario-contract`
|
|
|
|
- 登录与会话确认
|
|
- profile sync 元数据读取
|
|
- bridge capabilities 拉取
|
|
- routing resolve
|
|
- `session.start`
|
|
- `session.message`
|
|
- `session.cancel`
|
|
- `session.close`
|
|
|
|
## 5. 已知行为
|
|
|
|
- `session.start` / `session.message` 在当前环境下可能返回下游连接失败，这不代表脚本失效
|
|
- 只要脚本正确拿到 JSON-RPC 返回并解析出结果，就认为脚本可用
|
|
- 脚本不会把 `BRIDGE_SERVER_URL` 当成 runtime 真源；它只作为可选显式输入
|
|
|
|
## 6. 相关文档
|
|
|
|
- [APP 对接外部服务 API 接口测试详细清单](./app-external-service-api-test-matrix.md)
|
|
- [XWorkmate 测试规范模板与指南](./xworkmate-test-spec.md)
|
|
- [测试 Case 覆盖矩阵](./test-case-coverage-matrix.md)
|