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

12 KiB
Raw Blame History

jnpf 平台 API 测试模式

通过 API 直接调用获取数据,提高测试速度和稳定性

API 基础信息

基础配置

# 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 中携带。

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:

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. 查询数据列表

请求:

POST /api/visualdev/OnlineDev/{modelId}/List
Authorization: Bearer {token}
Content-Type: application/json

{
  "currentPage": 1,
  "pageSize": 20,
  "modelId": "{modelId}",
  "menuId": "{menuId}",
  "queryJson": "{}",
  "superQueryJson": "",
  "sidx": ""
}

响应:

{
  "code": 200,
  "msg": "Success",
  "data": {
    "pagination": {
      "currentPage": 1,
      "pageSize": 20,
      "total": 100
    },
    "list": [
      {
        "id": "821711816240398405",
        "F_ID": "821711816240398405",
        "F_Name": "资产名称",
        "F_Category": "分类",
        ...
      }
    ]
  }
}

2. 获取表单配置

请求:

GET /api/visualdev/OnlineDev/{modelId}/Config?type=
Authorization: Bearer {token}

响应:

{
  "code": 200,
  "data": {
    "id": "{modelId}",
    "formData": "{\"popupType\":\"general\",...}",
    "columns": [...]
  }
}

3. 获取菜单列表

请求:

GET /api/oauth/CurrentUser?systemCode={app_code}&isBackend=0
Authorization: Bearer {token}

响应:

{
  "code": 200,
  "data": {
    "menuList": [
      {"id": "...", "fullName": "审批中心", "enCode": "..."},
      {"id": "...", "fullName": "数据资产台账", "enCode": "dataAsset", ...}
    ]
  }
}

API 测试封装

完整的 JnpfApiClient

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()

使用示例

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 验证弹窗/页面

策略选择

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:

# 从 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 中):

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,需要从页面配置或菜单数据中获取。