测试快速入门指南

最后更新: 2026-01-20 适用对象: QA 工程师, 测试人员, 前端开发人员

本指南将帮助您快速开始测试 AXBlade 平台 API。所有测试脚本均已准备就绪，仅需简单设置即可运行。

快速开始 (5 分钟)

1. 安装依赖

cd backend/tests
pip3 install aiohttp eth-account certifi web3 python-dotenv requests

2. 运行所有核心测试

# 全面 API 测试 (44 个测试)
python3 test_api_comprehensive.py

# 场景和边界情况测试 (21 个测试)
python3 test_scenarios_and_edge_cases.py

3. 检查结果

Total tests: 65
  Pass: 65
  Fail: 0
Pass rate: 100.0%

测试环境

环境	API Base URL	WebSocket	链 (Chain)
测试网 (Testnet)	`https://api.8a27.xyz`	`wss://ws.8a27.xyz`	Arbitrum Sepolia (421614)

测试套件概览

可用测试文件

测试文件	测试数	时长	描述
`test_api_comprehensive.py`	44	~30s	API 全面覆盖
`test_scenarios_and_edge_cases.py`	21	~45s	交易场景测试
`test_limit_orders.py`	20	~60s	限价单生命周期
`test_liquidation.py`	9	~30s	清算机制
`test_points_phase1.py`	16	~30s	积分系统
`test_earn_e2e.py`	10	~120s	EARN 产品生命周期
`test_stress_10k.py`	8 阶段	~90s	1万并发压力测试

快速测试命令

# 运行特定测试
python3 test_limit_orders.py

# 运行并显示详细输出
python3 -v test_api_comprehensive.py

# 顺序运行所有测试
./run_api_tests.sh

测试账户设置

默认测试账户

所有测试文件均使用预配置的测试账户：

ADDRESS = "0x29F721B203A9fC9c5DDe35A739d8b8E0E4605489"
PRIVATE_KEY = "0x9b7f11c9a5c41fc4a62ab0aa767a3a18018a16f3bd012b2ca78d3a12ae947041"

使用自己的账户

生成新钱包或使用现有钱包
获取测试 USDT (仅限测试网)
更新测试文件：

ADDRESS = "0xYourAddress"
PRIVATE_KEY = "0xYourPrivateKey"

测试账户充值

对于测试网，请向团队申请或使用水龙头：

Arbitrum Sepolia ETH: Arbitrum 水龙头
测试 USDT: 联系团队管理员

API 测试指南

身份验证流程

所有需要身份验证的请求都需要 EIP-712 签名：

# 1. 获取 nonce
GET /api/v1/auth/nonce/{address}

# 2. 对类型化数据进行签名
typed_data = response['typed_data']
signature = sign_typed_data(typed_data, private_key)

# 3. 登录
POST /api/v1/auth/login
{
  "address": "0x...",
  "signature": "0x...",
  "timestamp": 1234567890
}

# 4. 在 Header 中使用 Token
Authorization: Bearer {token}

常用 API 端点

类别	端点	认证	描述
市场	`GET /api/v1/markets`	否	列出所有市场
	`GET /api/v1/markets/{symbol}/price`	否	当前价格
	`GET /api/v1/markets/{symbol}/ticker`	否	24小时行情
	`GET /api/v1/markets/{symbol}/orderbook`	否	订单簿深度
仓位	`POST /api/v1/positions`	是	开仓
	`GET /api/v1/positions`	是	列出仓位
	`POST /api/v1/positions/{id}/close`	是	平仓
订单	`POST /api/v1/orders`	是	创建订单
	`GET /api/v1/orders`	是	列出订单
	`DELETE /api/v1/orders/{id}`	是	取消订单
账户	`GET /api/v1/account/balance`	是	获取余额
	`GET /api/v1/account/positions`	是	仓位历史
积分	`GET /api/v1/points`	是	用户积分
	`GET /api/v1/leaderboard`	否	排行榜
	`GET /api/v1/epochs`	否	Epoch 列表

测试类别

1. API 全面测试 (44 个测试)

文件: test_api_comprehensive.py

测试跨 11 个模块的所有 API 端点：

模块	测试数	覆盖范围
身份验证	3	Nonce, 登录, 无效签名
账户	7	个人资料, 余额, 仓位, 订单, 历史
市场数据	7	市场列表, 订单簿, 行情, 价格, K线
仓位	4	开仓, 获取, 预估强平价, 平仓
资金费率	4	所有费率, 单个费率, 历史
清算	4	事件, 配置, 保险基金
ADL	3	排名, 配置, 历史
推荐系统	3	状态, 面板, 日志
积分系统	3	用户积分, 排行榜, Epoch
Earn	3	域名, 产品, 订阅
充值/提现	3	准备, 历史

2. 场景与边界情况测试 (21 个测试)

文件: test_scenarios_and_edge_cases.py

交易场景

完整交易周期 (开仓 → 检查 → 平仓 → 验证)
部分平仓
加仓 (同向)
反向开仓 (对冲)
多币种仓位
快速连续开平仓

边界情况

最小保证金
最大杠杆 (50倍限制)
无效仓位 ID
防止重复平仓
拒绝无效币种/方向
拒绝零/负保证金
拒绝过期 Token

并发测试

并发开仓
并发平仓同一仓位 (竞争条件)
并发余额查询

3. 限价单测试 (20 个测试)

文件: test_limit_orders.py

类别	测试数	描述
订单放置	6	创建、查询、取消订单
仓位触发	1	验证成交后仓位开启
增加仓位	2	增加多单/空单
减少仓位	2	部分平仓
平仓	2	全额平仓、批量平仓
结算	4	盈亏 (PnL) 计算
积分	3	交易/持仓/盈亏积分

4. 清算测试 (9 个测试)

文件: test_liquidation.py

测试	描述
清算配置	查询所有市场的配置
保险基金	查询基金余额
多单强平价	验证计算准确性
空单强平价	验证计算准确性
清算状态 API	检查端点
市场清算事件	查询历史
用户清算历史	查询历史
杠杆限制	测试最大 50 倍
临近清算场景	监控高杠杆仓位

关键验证点:

最大杠杆: 50x
维持保证金: 0.50%
清算费用: 0.50%
最小保证金: $10

5. 积分第一阶段测试 (16 个测试)

文件: test_points_phase1.py

类别	测试数	描述
API 测试	6	积分, epochs, 排行榜
Epoch 测试	1	状态验证
排行榜	3	类型, 排名, 用户查询
等级测试	2	显示, 逻辑
积分类型	3	交易, 持仓, 盈亏
汇总	1	总额计算

积分公式:

交易积分 = 交易量 × 0.0001 × 等级倍数
盈亏积分 = max(盈亏, 0) × 0.001 × 等级倍数
持仓积分 = 仓位价值 × 0.00001 × 小时数 × 等级倍数
推荐积分 = 被推荐人交易量 × 0.00005 (+ 100pt 首单奖励)
质押积分 = 金额 × 0.0002 × 天数

6. EARN 模块测试

文件: test_earn_api.py, test_earn_e2e.py

完整的 EARN 产品生命周期：

创建产品
开放订阅
用户订阅
激活产品
结算产品
用户领取

7. 压力测试

文件: test_stress_10k.py

渐进式负载测试：

100 → 500 → 1000 → 2000 → 3000 → 5000 → 7500 → 10000 并发
每个阶段：10 秒
生成 JSON 报告

预期结果:

2000 并发下稳定：100% 成功率
峰值 RPS: ~2859 (3000 并发时)

运行测试

单个测试文件

python3 test_api_comprehensive.py

特定测试类别

# 仅运行积分测试
python3 test_points_phase1.py

# 仅运行限价单测试
python3 test_limit_orders.py

运行所有测试并生成报告

./run_api_tests.sh 2>&1 | tee test_report.txt

压力测试并生成报告

python3 test_stress_10k.py
# 生成文件: stress_10k_report_{timestamp}.json

预期结果

所有测试通过

======================================================================
Test Summary
======================================================================
Total tests: 44
  Pass: 44
  Fail: 0
  Skip: 0
Pass rate: 100.0%

🎉 All tests passed!

常见失败原因

错误	原因	解决方案
`UNAUTHORIZED`	Token 无效或过期	重新进行身份验证
`INSUFFICIENT_BALANCE`	USDT 余额不足	为测试账户充值
`POSITION_NOT_FOUND`	仓位已关闭	检查仓位状态
`SIGNATURE_INVALID`	签名格式错误	检查 EIP-712 结构
`CONNECTION_ERROR`	网络问题	检查代理或连接性

调试技巧

1. 检查 API 响应

status, data = await client.get("/api/v1/markets")
print(f"Status: {status}")
print(f"Response: {json.dumps(data, indent=2)}")

2. 详细日志

import logging
logging.basicConfig(level=logging.DEBUG)

3. 检查身份验证

# 测试 nonce 端点
curl https://api.8a27.xyz/api/v1/auth/nonce/0x29F721B203A9fC9c5DDe35A739d8b8E0E4605489

4. 验证签名

# 打印已签名的消息
print(f"Typed data: {json.dumps(typed_data, indent=2)}")
print(f"Signature: {signature}")

测试输出文件

文件	描述
`stress_10k_report_{ts}.json`	压力测试结果
`test_results/`	测试输出目录
`*.log`	调试日志

联系与支持

文档: 本站点
API 问题: 后端团队
测试环境: DevOps 团队
测试脚本: QA 团队

附录：测试文件模板

使用此模板创建新的测试文件：

#!/usr/bin/env python3
"""
在此处添加测试描述
"""

import asyncio
import aiohttp
import ssl
import certifi
from eth_account import Account
from eth_account.messages import encode_typed_data

BASE_URL = "https://api.8a27.xyz"
ADDRESS = "0x29F721B203A9fC9c5DDe35A739d8b8E0E4605489"
PRIVATE_KEY = "0x9b7f11c9a5c41fc4a62ab0aa767a3a18018a16f3bd012b2ca78d3a12ae947041"

class TestClient:
    def __init__(self):
        self.account = Account.from_key(PRIVATE_KEY)
        self.session = None
        self.token = None

    async def connect(self):
        ssl_context = ssl.create_default_context(cafile=certifi.where())
        connector = aiohttp.TCPConnector(ssl=ssl_context)
        self.session = aiohttp.ClientSession(connector=connector)

    async def close(self):
        if self.session:
            await self.session.close()

    async def authenticate(self):
        # 获取 nonce
        async with self.session.get(
            f"{BASE_URL}/api/v1/auth/nonce/{ADDRESS.lower()}"
        ) as resp:
            data = await resp.json()
            typed_data = data["typed_data"]

        # 签名
        typed_data["message"]["timestamp"] = str(int(time.time()))
        signable = encode_typed_data(full_message=typed_data)
        signed = self.account.sign_message(signable)
        signature = f"0x{signed.signature.hex()}"

        # 登录
        async with self.session.post(
            f"{BASE_URL}/api/v1/auth/login",
            json={
                "address": ADDRESS.lower(),
                "signature": signature,
                "timestamp": int(typed_data["message"]["timestamp"])
            }
        ) as resp:
            data = await resp.json()
            self.token = data["token"]

    async def run_tests(self):
        results = []
        # 在此处添加您的测试
        return results

async def main():
    client = TestClient()
    await client.connect()
    await client.authenticate()
    results = await client.run_tests()
    await client.close()
    print(f"Results: {results}")

if __name__ == "__main__":
    asyncio.run(main())

快速开始 (5 分钟)​

1. 安装依赖​

2. 运行所有核心测试​

3. 检查结果​

测试环境​

测试套件概览​

可用测试文件​

快速测试命令​

测试账户设置​

默认测试账户​

使用自己的账户​

测试账户充值​

API 测试指南​

身份验证流程​

常用 API 端点​

测试类别​

1. API 全面测试 (44 个测试)​

2. 场景与边界情况测试 (21 个测试)​

交易场景​

边界情况​

并发测试​

3. 限价单测试 (20 个测试)​

4. 清算测试 (9 个测试)​

5. 积分第一阶段测试 (16 个测试)​

6. EARN 模块测试​

7. 压力测试​

运行测试​

单个测试文件​

特定测试类别​

运行所有测试并生成报告​

压力测试并生成报告​

预期结果​

所有测试通过​

常见失败原因​

调试技巧​

1. 检查 API 响应​

2. 详细日志​

3. 检查身份验证​

4. 验证签名​

测试输出文件​

联系与支持​

附录：测试文件模板​