XiTest · API Reference

XiTest API 规范

CLI + REST + gRPC + 用例 YAML + Webhooks

文档编号：D2-P7-TECH-002 · 版本：v1.0 · 发布：2026-05-05

一套 API · 覆盖全部自动化场景

20+

REST 接口

4

协议类型

v1

稳定版本

XiTest API 规范

摘要

本文档定义 XiTest v1.0 的完整 API，包括 CLI 命令行、REST API（CI / Web UI 使用）、gRPC API（节点间内部通信）、用例 YAML 规范、Webhooks 通知回调。所有外部接口版本号为 v1，遵循语义化版本承诺，不向后破坏兼容。

版本策略

v1 接口稳定期至 2028 Q4（v1.x 内部）
破坏性变更会提前 3 个月预告 + 提供 v2 并行
扩展字段始终向后兼容

1. CLI 命令参考

1.1 安装与配置

# pip 安装（Python 客户端）
pip install xitest-cli

# 或下载二进制（Go 客户端 · 推荐 CI 使用）
curl -L https://releases.xisound.com/xitest/v1.0.0/xitest-linux-amd64 -o xitest
chmod +x xitest

# 配置
xitest config set server https://xitest.xisound.com
xitest config set token $XITEST_TOKEN

1.2 核心命令

命令	说明
`xitest run`	启动测试运行
`xitest status`	查询运行状态
`xitest report`	生成/下载报告
`xitest failed`	列出失败用例
`xitest baseline`	管理金标基线
`xitest config`	配置管理
`xitest hil`	HIL 资源管理

1.3 `xitest run` 详解

# 运行全量套件
xitest run --suite regression --parallel 16

# 运行指定标签
xitest run --tags smoke,fx --timeout 600

# 运行单个用例
xitest run --case fx-eq-bass-boost-01

# HIL 模式
xitest run --hil --target XiDSP-D1 --suite tapeout-full --exclusive

# UI 模式
xitest run --ui --browser chromium --headed false

# 带环境变量
xitest run --suite smoke --env ALGO_VERSION=v1.2.3

参数表：

参数	类型	默认	说明
`--suite`	string	smoke	套件名
`--tags`	list	-	标签过滤（逗号分隔）
`--case`	string	-	单用例 ID
`--parallel`	int	16	并行 Worker 数
`--timeout`	int	3600	全局超时（秒）
`--hil`	bool	false	启用 HIL 模式
`--target`	string	-	HIL 目标硬件
`--exclusive`	bool	false	独占 HIL 资源
`--ui`	bool	false	启用 UI 模式
`--browser`	string	chromium	UI 浏览器
`--env`	list	-	环境变量传递
`--output`	string	stdout	结果输出路径

1.4 输出示例

[xitest] Run created: run-20260505-001
[xitest] Suite: regression (1024 cases)
[xitest] Parallel: 16 workers
[xitest] Progress: [======>               ] 234/1024 (23%)
[xitest] ETA: 00:42:15
[xitest] Failures so far: 2
[xitest] Press Ctrl+C to abort (graceful)

2. REST API

2.1 认证

所有请求需携带 Bearer Token：

Authorization: Bearer xitest_xxx_xxx
X-Xitest-Version: v1
Content-Type: application/json

2.2 测试运行

2.2.1 创建运行

POST /api/v1/runs

请求体：

{
  "suite": "regression",
  "tags": ["fx", "regression"],
  "parallel": 16,
  "timeout": 7200,
  "trigger": {
    "type": "ci",
    "source": "github-actions",
    "branch": "feature/new-eq",
    "commit": "abc123def"
  },
  "env": {
    "ALGO_VERSION": "v1.2.3"
  }
}

响应（201 Created）：

{
  "run_id": "run-20260505-001",
  "status": "PENDING",
  "created_at": "2026-05-05T10:00:00Z",
  "estimated_duration_seconds": 5400,
  "report_url": "https://xitest.xisound.com/runs/run-20260505-001"
}

2.2.2 查询运行状态

GET /api/v1/runs/{run_id}

响应：

{
  "run_id": "run-20260505-001",
  "status": "RUNNING",
  "suite": "regression",
  "progress": {
    "total": 1024,
    "finished": 234,
    "passed": 232,
    "failed": 2,
    "skipped": 0
  },
  "started_at": "2026-05-05T10:00:12Z",
  "eta_seconds": 2535
}

2.2.3 获取报告

GET /api/v1/runs/{run_id}/report?format=html
GET /api/v1/runs/{run_id}/report?format=junit
GET /api/v1/runs/{run_id}/report?format=json

Query：

参数	值	说明
format	html / junit / json / pdf	报告格式

2.2.4 失败用例列表

GET /api/v1/runs/{run_id}/failed

响应：

{
  "run_id": "run-20260505-001",
  "failed": [
    {
      "case_id": "fx-eq-bass-boost-01",
      "category": "integration",
      "error": "freq_response_at_60hz: 3.35 dB (expected 3.0 ±0.1)",
      "duration_seconds": 5.2,
      "artifacts": {
        "output_wav": "https://xitest.xisound.com/s3/runs/.../output.wav",
        "diff_plot": "https://xitest.xisound.com/s3/runs/.../diff.png"
      }
    }
  ]
}

2.2.5 取消运行

POST /api/v1/runs/{run_id}/cancel

2.3 用例管理

接口	方法	说明
`/api/v1/cases`	GET	列出所有用例
`/api/v1/cases/{id}`	GET	查询单用例
`/api/v1/cases/search`	POST	复杂搜索（按 tags/category）

2.4 金标基线

接口	方法	说明
`/api/v1/cases/{id}/baseline`	GET	获取当前基线
`/api/v1/cases/{id}/baseline`	POST	提交新基线（需审批令牌）
`/api/v1/cases/{id}/baseline/history`	GET	基线版本历史

提交基线（需 Tapeout-Gate 角色）：

POST /api/v1/cases/fx-eq-bass-boost-01/baseline
{
  "wav_url": "s3://xitest/golden/fx-eq-bass-boost-01-v2.wav",
  "reason": "算法 v1.2.3 优化了低频响应",
  "reviewer": "alice@xisound.com",
  "approver_2": "bob@xisound.com"
}

2.5 HIL 资源

接口	方法	说明
`/api/v1/hil/targets`	GET	列出所有 HIL 目标硬件
`/api/v1/hil/reservations`	POST	预约独占 HIL
`/api/v1/hil/reservations/{id}`	DELETE	释放预约

2.6 错误码

HTTP	业务码	含义
400	40001	请求参数错误
400	40002	用例 ID 不存在
401	40100	Token 无效
403	40301	权限不足（非 Tapeout-Gate 试图更新金标）
404	40400	资源不存在
409	40901	HIL 资源冲突（已被预约）
429	42900	速率限制（单用户 100 req/min）
500	50000	内部错误
503	50301	Orchestrator 维护中

3. gRPC API（内部）

3.1 Orchestrator ↔ Worker 协议

syntax = "proto3";
package xisound.xitest.v1;

service TestOrchestrator {
  rpc ScheduleRun(RunRequest) returns (RunResponse);
  rpc StreamLogs(RunID) returns (stream LogLine);
  rpc GetStatus(RunID) returns (RunStatus);
  rpc CancelRun(RunID) returns (CancelResult);
  rpc ReportCaseResult(CaseResult) returns (Ack);
}

message RunRequest {
  string suite = 1;
  repeated string tags = 2;
  int32 parallel = 3;
  int32 timeout_seconds = 4;
  Trigger trigger = 5;
  map<string, string> env = 6;
}

message CaseResult {
  string run_id = 1;
  string case_id = 2;
  Status status = 3;
  double duration_seconds = 4;
  map<string, double> metrics = 5;
  string error = 6;
  repeated Artifact artifacts = 7;
}

enum Status {
  PENDING = 0;
  RUNNING = 1;
  PASSED = 2;
  FAILED = 3;
  TIMEOUT = 4;
  SKIPPED = 5;
}

3.2 Worker 注册与心跳

service WorkerRegistry {
  rpc Register(WorkerInfo) returns (WorkerID);
  rpc Heartbeat(WorkerID) returns (HeartbeatAck);
  rpc FetchTask(WorkerID) returns (Task);
}

4. 用例 YAML 规范

4.1 完整字段

# 必填字段
id: fx-eq-bass-boost-01
category: integration  # unit | integration | regression | ui | hil
description: "验证低频增强 EQ 在 60Hz 处 +3dB"

# 可选字段
tags: [regression, fx, eq]
priority: P1  # P0 | P1 | P2 | P3
timeout: 30  # 秒
retry: 2
skip_if: "env.PLATFORM == 'macOS'"  # 条件跳过
owner: alice@xisound.com

# 输入
input:
  audio: "golden/input_pink_noise.wav"
  sample_rate: 48000
  channels: 2
  duration_seconds: 10

# 算法管道（Integration 专用）
pipeline:
  - algorithm: xialgo.fx.eq
    version: ">=1.2.0"
    params:
      band1: { freq: 60, gain: 3, Q: 0.707 }
  - algorithm: xialgo.fx.drc
    params:
      threshold: -20
      ratio: 3

# 期望
expected:
  audio: "golden/output_pink_noise_60hz_plus3db.wav"
  metrics:
    freq_response_at_60hz: { value: 3.0, tolerance: 0.1, unit: dB }
    thd_n: { max: 0.005, unit: percent }
    rms_overall: { tolerance: 0.5, unit: dB }
    latency_samples: { value: 128, tolerance: 10 }

# HIL 专用
hil:
  target: XiDSP-D1
  firmware: "firmware/d1-default-v1.2.bin"
  fault_injection:
    voltage_ripple: 5  # 百分比
    temperature: 70  # 摄氏度

# UI 专用
ui:
  browser: chromium
  viewport: [1920, 1080]
  screenshot_tolerance: 0.005

4.2 JSON Schema（片段）

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "XiTest Case",
  "type": "object",
  "required": ["id", "category", "description"],
  "properties": {
    "id": { "type": "string", "pattern": "^[a-z0-9-]+$" },
    "category": { "enum": ["unit", "integration", "regression", "ui", "hil"] },
    "priority": { "enum": ["P0", "P1", "P2", "P3"], "default": "P2" },
    "timeout": { "type": "integer", "minimum": 1, "maximum": 86400 }
  }
}

完整 Schema：https://xitest.xisound.com/schema/v1/case.json

5. Webhooks

5.1 配置 Webhook

POST /api/v1/webhooks

{
  "url": "https://your-service.example.com/xitest-callback",
  "events": ["run.completed", "run.failed", "baseline.updated"],
  "secret": "wh_secret_xxx"
}

5.2 事件负载

run.completed：

{
  "event": "run.completed",
  "timestamp": "2026-05-05T12:34:56Z",
  "data": {
    "run_id": "run-20260505-001",
    "status": "PASSED",
    "suite": "regression",
    "duration_seconds": 5400,
    "total": 1024,
    "passed": 1022,
    "failed": 2,
    "report_url": "https://xitest.xisound.com/runs/run-20260505-001"
  }
}

5.3 签名验证

每个 Webhook 请求头携带 X-Xitest-Signature，值为：

sha256=<HMAC-SHA256(secret, body)>

接收方必须校验签名，否则拒绝请求。

6. CI 集成模板

6.1 GitHub Actions

# .github/workflows/xitest.yml
name: XiTest Regression
on:
  push:
    branches: [main, develop]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install xitest CLI
        run: |
          curl -L https://releases.xisound.com/xitest/v1.0.0/xitest-linux-amd64 -o xitest
          chmod +x xitest && sudo mv xitest /usr/local/bin/

      - name: Run XiTest
        env:
          XITEST_TOKEN: ${{ secrets.XITEST_TOKEN }}
        run: |
          xitest run \
            --suite ${{ github.event_name == 'pull_request' && 'integration' || 'smoke' }} \
            --parallel 16 \
            --output junit.xml

      - name: Publish Test Results
        uses: EnricoMi/publish-unit-test-result-action@v2
        if: always()
        with:
          files: junit.xml

6.2 GitLab CI

# .gitlab-ci.yml
xitest:
  stage: test
  image: xisound/xitest-cli:v1.0
  variables:
    XITEST_SERVER: https://xitest.xisound.com
  script:
    - xitest run --suite smoke --parallel 16 --output junit.xml
  artifacts:
    reports:
      junit: junit.xml

6.3 Jenkins

pipeline {
  agent any
  stages {
    stage('XiTest') {
      steps {
        withCredentials([string(credentialsId: 'xitest-token', variable: 'TOKEN')]) {
          sh '''
            xitest run --suite regression --parallel 16 --output junit.xml
          '''
        }
      }
      post {
        always {
          junit 'junit.xml'
        }
      }
    }
  }
}

7. 速率限制与配额

维度	默认限制
REST API（单 Token）	100 req/min
REST API（单 IP）	500 req/min
并发运行数（单用户）	10
HIL 独占预约时长	最长 72h
Webhook 重试	失败后 3 次 · 间隔 ⅕/30 min

超配额返回 429 Too Many Requests，Response Header 含 Retry-After。

8. SDK 语言支持

语言	包	维护
Python	`xitest-cli`	官方
Go	`github.com/xisound/xitest-go`	官方
TypeScript	`@xisound/xitest-sdk`	官方
Java	`com.xisound:xitest-java`	社区

9. 变更历史与兼容性

9.1 v1.0 API 首发（2027 Q4）

REST / gRPC / CLI / YAML 四通道
稳定承诺至 2028 Q4

9.2 v1.x 扩展承诺

仅新增字段 · 不删除/重命名
新增 endpoint 不影响老 endpoint
gRPC 字段保留 tag 号

10. 附录

10.1 关联文档

10.2 参考标准

JUnit XML 规范
JSON Schema Draft 07
RFC 6750（Bearer Token）
RFC 8725（Webhook 签名最佳实践）

10.3 版本历史

版本	日期	要点
v1.0	2026-05-05	首版 · v1.0 API 全量规范

api.md · D2-P7-TECH-002 · v1.0 · 2026-05-05 · Xisound 研发中心 · 测试与工具团队

XiTest API 规范

XiTest API 规范

1. CLI 命令参考

1.1 安装与配置

1.2 核心命令

1.3 xitest run 详解

1.4 输出示例

2. REST API

2.1 认证

2.2 测试运行

2.2.1 创建运行

2.2.2 查询运行状态

2.2.3 获取报告

2.2.4 失败用例列表

2.2.5 取消运行

2.3 用例管理

2.4 金标基线

2.5 HIL 资源

2.6 错误码

3. gRPC API（内部）

3.1 Orchestrator ↔ Worker 协议

3.2 Worker 注册与心跳

4. 用例 YAML 规范

4.1 完整字段

4.2 JSON Schema（片段）

5. Webhooks

5.1 配置 Webhook

5.2 事件负载

5.3 签名验证

6. CI 集成模板

6.1 GitHub Actions

6.2 GitLab CI

6.3 Jenkins

7. 速率限制与配额

8. SDK 语言支持

9. 变更历史与兼容性

9.1 v1.0 API 首发（2027 Q4）

9.2 v1.x 扩展承诺

10. 附录

10.1 关联文档

10.2 参考标准

10.3 版本历史

1.3 `xitest run` 详解