MIGRATED

XiTest 产品规格书

摘要

本文档是 XiTest 测试验证平台的完整技术规格书，涵盖框架架构、测试用例格式、执行引擎 API、HIL 协议、报告格式、CI 集成规范。面向测试框架开发者、算法开发者、硬件工程师、DevOps 工程师。

数据来源

规格为 v1.0 GA 目标值（2027 Q4），最终以 Release Notes 为准。

1. 总体架构

1.1 系统总览

graph TB
    CLI[xitest CLI]
    Srv[XiTest Server<br/>Orchestrator]
    CLI --> Srv

    Srv --> UnitW[Unit Worker Pool]
    Srv --> IntegW[Integration Worker Pool]
    Srv --> HILW[HIL Controller]
    Srv --> UIW[UI Worker<br/>Playwright]

    UnitW --> XAlg[XiAlgo 单测]
    IntegW --> XLink[算法链路 E2E]
    HILW --> XDSP[XiDSP EVB]
    UIW --> XStu[XiStudio/XiForge]

    Srv --> DB[(用例数据库<br/>PostgreSQL)]
    Srv --> Store[(金标 WAV 存储<br/>MinIO/S3)]
    Srv --> Report[(报告存档<br/>S3 + ElasticSearch)]

    class CLI xyL4
    class Srv xyL2
    class UnitW,IntegW,HILW,UIW xyL3
    class XAlg xyL3
    class XLink xyL2
    class XDSP xyL0
    class XStu xyL4
    class DB,Store,Report xySuccess

1.2 技术栈

层	技术
编排器	Go + gRPC
执行节点	Docker + containerd
Unit 框架	Google Test / Catch2 + CMake
Integration 引擎	自研 xy-test-runner（Python + NumPy/SciPy）
UI 测试	Playwright + pixelmatch
HIL 控制	Python + 专业声卡驱动 + JTAG
存储	PostgreSQL（用例元数据）· MinIO/S3（WAV）· ES（日志/报告）
监控	Prometheus + Grafana + OpenTelemetry
API	gRPC（内部）+ REST（CI/用户）

1.3 部署拓扑

环境	配置
Dev（单机）	16 核 CPU / 64GB / 本地 Docker
Staging	3 节点 K8s · 32 core 总容量
Production	10+ 节点 K8s · 200+ worker · HIL 集群独立

2. 测试用例格式

2.1 用例定义（YAML）

# tests/fx/eq_boost.test.yaml
id: fx-eq-bass-boost-01
category: integration
tags: [regression, fx, eq]
priority: P1
description: "验证低频增强 EQ 在 60Hz 处 +3dB"

input:
  audio: "golden/input_pink_noise.wav"
  sample_rate: 48000
  channels: 2

pipeline:
  - algorithm: xialgo.fx.eq
    params:
      band1: { freq: 60, gain: 3, Q: 0.707 }

expected:
  audio: "golden/output_pink_noise_60hz_plus3db.wav"
  metrics:
    freq_response_at_60hz: { value: 3.0, tolerance: 0.1 }  # dB
    thd_n: { max: 0.005 }  # 百分比
    rms_overall: { tolerance: 0.5 }  # dB

timeout: 30  # 秒
retry: 2

2.2 用例分类

分类	目录	示例
FX（效果器）	`tests/fx/`	EQ / DRC / Delay / Reverb
NR（降噪）	`tests/nr/`	SNS / 风噪 / 路噪
Audio I/O	`tests/io/`	ADC / DAC / 编解码
链路（E2E）	`tests/e2e/`	完整前装链路 / 后装链路
UI（界面）	`tests/ui/`	XiStudio / XiForge 场景
HIL（硬件）	`tests/hil/`	XiDSP 烧录 + 实时验证

2.3 金标管理

存储位置：golden/ 目录 + MinIO/S3（大文件）
命名规范：<algorithm>_<scenario>_<version>.wav
审批流：
提交新基线 PR（附测量报告 + 评审意见）
算法 lead + QA Review
合并后立即全量回归一次

3. 执行引擎 API

3.1 CLI 命令

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

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

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

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

# 生成报告
xitest report --format html --output report.html

# 列出失败用例
xitest failed --last-run

3.2 REST API

接口	方法	描述
`POST /api/v1/runs`	POST	创建测试运行
`GET /api/v1/runs/{id}`	GET	查询运行状态
`GET /api/v1/runs/{id}/report`	GET	获取 HTML 报告
`GET /api/v1/runs/{id}/failed`	GET	失败用例列表
`POST /api/v1/cases/{id}/baseline`	POST	更新金标（需审批令牌）

3.3 gRPC（节点间内部通信）

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

4. HIL 子系统

4.1 HIL 节点架构

graph LR
    Worker[HIL Worker<br/>Python]
    Worker --> JTAG[JTAG 烧录]
    Worker --> AudioOut[专业声卡<br/>输出]
    Worker --> AudioIn[专业声卡<br/>输入]
    Worker --> EVB[XiDSP EVB]

    JTAG --> EVB
    AudioOut --> EVB
    EVB --> AudioIn

    class Worker xyL2
    class JTAG,AudioOut,AudioIn xyL3
    class EVB xyL0

4.2 HIL 测试流程

烧录：用 XiStudio CLI 烧录算法固件到 EVB
播放：专业声卡向 EVB 输入金标音频
采集：同声卡输入通道采集 EVB 输出
比较：离线计算频响/THD+N/SNR 等指标
判定：与预期对比 + 容差判定

4.3 故障注入能力

类型	方法
电压波动	可编程电源（±20% 波动）
温度	恒温箱 -40 ~ +85°C
EMC	标准化干扰发生器
时钟抖动	可编程时钟模块

4.4 HIL 资源调度

基于优先级队列（P0 Tapeout > P1 发版 > P2 Nightly）
支持独占模式（独占一台 EVB 48 小时）
支持共享模式（多用例共享一台 EVB，用例级切换）

5. UI 测试子系统

5.1 Playwright 脚本规范

// tests/ui/xistudio-open-project.spec.ts
import { test, expect } from '@playwright/test';

test('打开项目并拖拽 EQ 节点', async ({ page }) => {
  await page.goto('http://localhost:5173');
  await page.click('[data-test="open-project"]');
  await page.fill('[data-test="project-name"]', 'demo-eq');

  // 拖拽算法节点
  await page.dragAndDrop(
    '[data-test="algo-lib-eq"]',
    '[data-test="flow-canvas"]'
  );

  // 视觉回归
  await expect(page).toHaveScreenshot('flow-with-eq.png', {
    maxDiffPixelRatio: 0.005
  });
});

5.2 视觉回归

基准图存储：tests/ui/__screenshots__/
对比工具：pixelmatch（默认阈值 0.5%）
分辨率：1920×1080（主）· 2K/4K 可选
差异处理：差异 > 阈值 → 失败 · 生成 diff.png

5.3 跨浏览器支持

Chromium（主）· WebKit（macOS）· Firefox（辅）

6. 报告规范

6.1 HTML 报告结构

总览：通过/失败/跳过数量 + 耗时
分层统计：Unit/Integration/Regression/UI
失败详情：用例 + 错误 + WAV 对比波形 + 堆栈
趋势：最近 10 次运行通过率折线图
性能：每用例耗时 TopN
覆盖率：算法代码覆盖率（LCOV 集成）

6.2 JUnit XML（CI 集成）

<?xml version="1.0" encoding="UTF-8"?>
<testsuites name="XiTest v1.0" tests="1024" failures="2" time="5423.5">
  <testsuite name="fx" tests="128" failures="1">
    <testcase classname="fx.eq" name="fx-eq-bass-boost-01" time="5.2">
      <failure message="freq_response_at_60hz: 3.35 dB (expected 3.0 ±0.1)"/>
    </testcase>
    ...
  </testsuite>
</testsuites>

6.3 通知模板

❌ XiTest Regression Failed
Branch: feature/new-eq
Commit: abc123
Failures: 1 / 1024
  - fx-eq-bass-boost-01 (freq_response_at_60hz out of tolerance)
Report: https://xitest.xisound.com/runs/20260505-001

7. CI 集成规范

7.1 GitHub Actions 示例

# .github/workflows/xitest.yml
name: XiTest
on: [push, pull_request]
jobs:
  test:
    uses: xisound/xitest-actions/.github/workflows/reusable.yml@v1
    with:
      suite: ${{ github.event_name == 'pull_request' && 'integration' || 'smoke' }}
      parallel: 16
    secrets:
      XITEST_TOKEN: ${{ secrets.XITEST_TOKEN }}

7.2 GitLab CI 示例

include:
  - project: xisound/xitest-ci
    ref: v1
    file: /gitlab-ci/xitest.yml

xitest:
  extends: .xitest-base
  variables:
    XITEST_SUITE: smoke

7.3 PR 集成

失败自动评论 PR
Status Check 必须通过才能合并
可配置：新增测试必须有对应用例

8. 非功能规格

8.1 性能

指标	规格
Unit 平均耗时	≤ 100 ms
Integration 平均耗时	≤ 30 s
全量 Regression（1000 用例 / 16 worker）	≤ 2 h
HIL 单用例	≤ 5 min
报告生成	≤ 30 s
并发支持	100+ Worker（集群）

8.2 可靠性

平台可用性 ≥ 99.5%
测试结果可重复性 ≥ 99%
假失败率 ≤ 0.5%
自动重试：失败用例 ≤ 3 次

8.3 安全

用例仓库：企业私有 Git
金标 WAV：加密存储 + 访问审计
CI Token：短时令牌 + 最小权限
报告访问：SSO + RBAC

9. 与其他产品的接口

产品	接口方式	说明
XiAlgo	Git 仓库 + C/C++ 接口	被测对象
XiDSP	JTAG + 声卡 HIL	实时硬件验证
XiStudio	CLI + Playwright	烧录 + UI 回归
XiForge	Playwright	UI 回归
XiMind	REST API（v1.1+）	AI 用例生成
XiTune	数据源	调音结果可导入为测试用例

10. 已知限制与路线

10.1 v1.0 已知限制

不支持：分布式 HIL 跨集群调度（v1.1 启用）
不支持：AI 用例编排（v1.1 启用）
不支持：Enterprise SaaS 对外（v2.0 启用）
UI 跨分辨率：v1.0 仅 1080p，2K/4K 需配置

10.2 路线图

v1.1（2028 Q2）：XiMind AI 编排 + 分布式 HIL
v1.2（2028 Q4）：D2 完整支持 + 故障注入扩展
v2.0（2029）：Enterprise SaaS 对外版

11. 附录

11.1 关联文档

11.2 标准与开源组件

Google Test / Catch2（BSD / BSL）
Playwright（Apache 2.0）
pixelmatch（ISC）
Prometheus + Grafana（Apache 2.0）
OpenTelemetry（Apache 2.0）
JUnit XML 规范

11.3 版本历史

版本	日期	要点
v1.0	2026-05-05	首版 · v1.0 GA 完整技术规格

spec.md · D2-P7-SPEC-001 · v1.0 · 2026-05-05 · Xisound 研发中心 · 测试与工具团队