Files
claude-config/skills/ssw-e2e-test/docs/api-testing.md
T
2026-05-18 09:28:27 +08:00

427 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# jnpf 平台 API 测试模式
> 通过 API 直接调用获取数据,提高测试速度和稳定性
## API 基础信息
### 基础配置
```python
# 13880 生产环境
BASE_URL = "http://{host}:13880/jnpf_app_{app_code}"
API_BASE = "http://{host}:13880/api"
# 13000 Vite Dev 环境
BASE_URL = "http://{host}:13000/jnpf_app_{app_code}"
API_BASE = "http://{host}:13000/dev/api" # 注意:需要加 /dev 前缀
```
### 认证方式
**获取 Token(UI 登录 + 请求拦截)**:
jnpf 的 token 通过 UI 登录后自动生成,后续 API 请求在 `Authorization: Bearer {token}` header 中携带。
```python
from playwright.sync_api import sync_playwright
def get_token_via_ui() -> str:
"""通过 UI 登录获取 API token"""
token_captured = {}
def handle_request(request):
if '/api/' in request.url:
headers = dict(request.headers)
for name, value in headers.items():
if 'authorization' in name.lower() and value.startswith('bearer '):
token_captured['token'] = value
with sync_playwright() as p:
browser = p.chromium.launch(headless=True)
page = browser.new_page()
page.on("request", handle_request)
# UI 登录
page.goto(f"{BASE_URL}/login")
page.wait_for_load_state('domcontentloaded')
page.fill('#form_item_account', 'admin')
page.fill('#form_item_password', '123456')
page.click('button:has-text("登 录")')
page.wait_for_url("**/home**", timeout=15000)
page.wait_for_load_state('networkidle')
page.wait_for_timeout(2000) # 等待 token 出现在请求中
browser.close()
return token_captured.get('token', '')
```
> **说明**:密码 hash 算法虽未确认,但不影响测试。因为 token 在 UI 登录后自动生成并附加到所有 API 请求,无需手动计算 hash。
**使用 Token**:
```python
session = requests.Session()
session.headers.update({'Authorization': token}) # 完整 bearer token
# 测试 API
resp = session.get(f"{API_BASE}/oauth/CurrentUser?systemCode={APP_CODE}&isBackend=0")
print(resp.json())
```
---
## 核心 API 模式
### 1. 查询数据列表
**请求**:
```http
POST /api/visualdev/OnlineDev/{modelId}/List
Authorization: Bearer {token}
Content-Type: application/json
{
"currentPage": 1,
"pageSize": 20,
"modelId": "{modelId}",
"menuId": "{menuId}",
"queryJson": "{}",
"superQueryJson": "",
"sidx": ""
}
```
**响应**:
```json
{
"code": 200,
"msg": "Success",
"data": {
"pagination": {
"currentPage": 1,
"pageSize": 20,
"total": 100
},
"list": [
{
"id": "821711816240398405",
"F_ID": "821711816240398405",
"F_Name": "资产名称",
"F_Category": "分类",
...
}
]
}
}
```
### 2. 获取表单配置
**请求**:
```http
GET /api/visualdev/OnlineDev/{modelId}/Config?type=
Authorization: Bearer {token}
```
**响应**:
```json
{
"code": 200,
"data": {
"id": "{modelId}",
"formData": "{\"popupType\":\"general\",...}",
"columns": [...]
}
}
```
### 3. 获取菜单列表
**请求**:
```http
GET /api/oauth/CurrentUser?systemCode={app_code}&isBackend=0
Authorization: Bearer {token}
```
**响应**:
```json
{
"code": 200,
"data": {
"menuList": [
{"id": "...", "fullName": "审批中心", "enCode": "..."},
{"id": "...", "fullName": "数据资产台账", "enCode": "dataAsset", ...}
]
}
}
```
---
## API 测试封装
### 完整的 JnpfApiClient
```python
import requests
from typing import Optional, Dict, List, Any
class JnpfApiClient:
"""jnpf 平台 API 客户端 - 使用已获取的 token"""
def __init__(self, host: str, app_code: str, token: str, is_vite_dev: bool = False):
"""
初始化 API 客户端
Args:
host: 服务器地址 (如 "192.168.1.18:13880" 或 "192.168.1.18:13000")
app_code: 应用代码 (如 "dr", "workSystem")
token: UI 登录后获取的完整 bearer token
is_vite_dev: 是否为 Vite Dev 模式 (13000 端口,API 需要加 /dev 前缀)
"""
self.host = host
self.app_code = app_code
self.is_vite_dev = is_vite_dev
# Vite Dev 模式: API_BASE = http://host:13000/dev/api
# 生产模式: API_BASE = http://host:13880/api
self.api_base = f"http://{host}/dev/api" if is_vite_dev else f"http://{host}/api"
self.token = token
self.session = requests.Session()
self.session.headers.update({
'Authorization': token, # 完整 bearer token
'Content-Type': 'application/json'
})
@classmethod
def from_ui_login(cls, host: str, app_code: str, is_vite_dev: bool = False) -> 'JnpfApiClient':
"""通过 UI 登录获取 token 并创建客户端"""
from playwright.sync_api import sync_playwright
token_captured = {}
def handle_request(request):
if '/api/' in request.url:
headers = dict(request.headers)
for name, value in headers.items():
if 'authorization' in name.lower() and value.startswith('bearer '):
token_captured['token'] = value
with sync_playwright() as p:
browser = p.chromium.launch(headless=True)
page = browser.new_page()
page.on("request", handle_request)
base_url = f"http://{host}/jnpf_app_{app_code}"
page.goto(f"{base_url}/login")
page.wait_for_load_state('domcontentloaded')
page.fill('#form_item_account', 'admin')
page.fill('#form_item_password', '123456')
page.click('button:has-text("登 录")')
page.wait_for_url("**/home**", timeout=15000)
page.wait_for_load_state('networkidle')
page.wait_for_timeout(2000)
browser.close()
token = token_captured.get('token', '')
if not token:
raise RuntimeError("无法从 UI 登录获取 token")
return cls(host, app_code, token)
def get_current_user(self) -> Dict:
"""获取当前用户信息"""
url = f"{self.api_base}/oauth/CurrentUser?systemCode={self.app_code}&isBackend=0"
resp = self.session.get(url)
return resp.json().get('data', {})
def get_menu_list(self) -> List[Dict]:
"""获取菜单列表"""
user = self.get_current_user()
return user.get('menuList', [])
def get_menu_by_name(self, name: str) -> Optional[Dict]:
"""根据名称查找菜单"""
menus = self.get_menu_list()
for menu in menus:
if name in menu.get('fullName', ''):
return menu
return None
def query_list(self, model_id: str, menu_id: str,
page: int = 1, page_size: int = 20,
query_json: str = "{}") -> Dict:
"""查询列表数据"""
url = f"{self.api_base}/visualdev/OnlineDev/{model_id}/List"
data = {
"currentPage": page,
"pageSize": page_size,
"modelId": model_id,
"menuId": menu_id,
"queryJson": query_json,
"superQueryJson": "",
"sidx": ""
}
resp = self.session.post(url, json=data)
return resp.json()
def create(self, model_id: str, data: Dict) -> Dict:
"""创建数据"""
url = f"{self.api_base}/visualdev/OnlineDev/{model_id}"
resp = self.session.post(url, json=data)
return resp.json()
def update(self, model_id: str, data_id: str, data: Dict) -> Dict:
"""更新数据"""
url = f"{self.api_base}/visualdev/OnlineDev/{model_id}/{data_id}"
resp = self.session.put(url, json=data)
return resp.json()
def delete(self, model_id: str, data_id: str) -> Dict:
"""删除数据"""
url = f"{self.api_base}/visualdev/OnlineDev/{model_id}/{data_id}"
resp = self.session.delete(url)
return resp.json()
```
### 使用示例
```python
import os
# 方式1: 自动 UI 登录获取 token
client = JnpfApiClient.from_ui_login(
host=os.environ["JNPF_HOST"], # 如 "192.168.1.18:13880" 或 "192.168.1.18:13000"
app_code=os.environ["JNPF_APP_CODE"] # 如 "dr"
)
print("登录成功")
# 方式2: 手动传入已获取的 token
import os
client = JnpfApiClient(
host=os.environ["JNPF_HOST"], # 如 "192.168.1.18:13880"
app_code=os.environ["JNPF_APP_CODE"], # 如 "dr"
token="bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
)
# 获取菜单
menus = client.get_menu_list()
for menu in menus:
print(f"{menu['fullName']}: {menu['id']}")
# 查找菜单
asset_menu = client.get_menu_by_name("数据资产台账")
print(f"资产菜单ID: {asset_menu['id']}")
# 查询列表
result = client.query_list(
model_id="821711816240398405",
menu_id="821713439528321093"
)
print(f"总数: {result['data']['pagination']['total']}")
for item in result['data']['list']:
print(f" - {item.get('F_Name', 'N/A')}")
# 创建数据
new_item = {
"F_Name": "测试资产",
"F_Category": "分类1",
...
}
resp = client.create("821711816240398405", new_item)
print(f"创建结果: {resp}")
```
---
## 混合测试策略
### 推荐:UI + API 混合
| 操作 | 推荐方式 | 原因 |
|------|----------|------|
| 登录 | API | 更快,更稳定 |
| 导航/菜单 | UI | 确保界面正常 |
| 列表查询 | API | 更快,获取完整数据 |
| 新增/编辑/删除 | UI | 验证表单功能 |
| 详情查看 | UI | 验证弹窗/页面 |
### 策略选择
```python
def test_asset_crud_hybrid():
"""混合测试策略"""
# 1. UI 登录(验证登录功能)
page.goto(login_url)
page.fill('#form_item_account', 'admin')
page.fill('#form_item_password', '123456')
page.click('button:has-text("登 录")')
page.wait_for_url("**/home**")
# 2. API 查询(快速获取数据)
client.login("admin", "123456")
result = client.query_list(model_id, menu_id)
asset_count = result['data']['pagination']['total']
# 3. UI 操作(验证交互)
click_menu(page, "数据资产台账")
page.wait_for_timeout(1000)
# 新增
page.click('button:has-text("新增")')
page.wait_for_selector('.ant-modal')
page.fill('input[placeholder="请输入名称"]', '测试资产')
page.click('.ant-modal button:has-text("确 定")')
page.wait_for_timeout(1000)
# 4. API 验证(确认数据已保存)
result = client.query_list(model_id, menu_id)
new_count = result['data']['pagination']['total']
assert new_count == asset_count + 1
```
---
## API 测试优势
| 对比项 | 纯 UI 测试 | API 测试 | 混合测试 |
|--------|------------|----------|----------|
| 速度 | 慢 (3-5s/操作) | 快 (0.1-0.3s/操作) | 中等 |
| 稳定性 | 低 (依赖渲染) | 高 (直接数据) | 高 |
| 覆盖范围 | 仅界面 | 仅数据 | 全面 |
| 维护成本 | 高 | 低 | 中 |
| 真实用户场景 | ✅ 是 | ❌ 否 | ✅ 是 |
---
## 已知问题
### 1. Token 获取
jnpf 的 token 存储在 cookie 中,而非 localStorage:
```python
# 从 cookie 获取
context = page.context
cookies = context.cookies()
for c in cookies:
if c['name'] == 'Admin-Token':
token = c['value']
```
### 2. Token 在 Authorization Header
UI 登录后,token 通过请求拦截获取(不在 cookie 中):
```python
def handle_request(request):
if '/api/' in request.url:
headers = dict(request.headers)
for name, value in headers.items():
if 'authorization' in name.lower():
token = value # "bearer eyJ0eXAiOiJKV1Qi..."
```
### 3. Model ID 和 Menu ID
每个菜单项都有对应的 `modelId` 和 `menuId`,需要从页面配置或菜单数据中获取。