XiTest · User Manual

XiTest 用户手册

从零到跑通 Regression · 一册读完

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

算法 / 硬件 / 工具 / QA 工程师都能读懂

15min

首次跑通

4

角色视角

30+

实战示例

XiTest 用户手册

摘要

本手册面向 XiTest 所有用户角色（算法开发者 / 硬件工程师 / 工具团队 / QA），从环境准备、首次运行、编写用例、CI 集成、HIL 使用、故障排查六个维度提供完整操作指南。目标：15 分钟首次跑通 Smoke Suite，2 小时独立编写首个 Integration 用例。

阅读建议

算法开发者：1 → 2 → 3 → 5（跳过 HIL）
硬件工程师：1 → 2 → 6（HIL）
工具团队：1 → 2 → 7（UI 回归）
QA 工程师：全章节 + 附录 SOP

1. 环境准备

1.1 系统要求

角色	本地要求	服务端
普通用户	Python 3.11+ / Git / Docker Desktop	已部署的 XiTest Server
Runner 开发	同上 + Go 1.22+ / K8s 本地 kind	同上
HIL 用户	物理 HIL 机柜 + JTAG 驱动	同上

1.2 安装 CLI

# Linux / macOS
curl -L https://releases.xisound.com/xitest/v1.0.0/xitest-$(uname -s | tr A-Z a-z)-amd64 -o xitest
chmod +x xitest
sudo mv xitest /usr/local/bin/

# Windows（PowerShell）
iwr https://releases.xisound.com/xitest/v1.0.0/xitest-windows-amd64.exe -OutFile xitest.exe

1.3 获取 Token

访问 https://xitest.xisound.com/profile
点击 "生成 API Token"
选择权限（推荐：Viewer + Contributor）
复制 Token（仅显示一次）

1.4 配置

xitest config set server https://xitest.xisound.com
xitest config set token xitest_xxx_xxx
xitest config test  # 验证连通性

预期输出：

✅ Server reachable: https://xitest.xisound.com (RTT: 45ms)
✅ Token valid: user=alice@xisound.com, roles=[Viewer, Contributor]

2. 首次运行（15 分钟）

2.1 跑一个 Smoke Suite

xitest run --suite smoke --parallel 8

预期：约 3-5 分钟完成，通过率应 100%。

2.2 查看报告

xitest report --last-run --format html --open

浏览器自动打开报告页面，可看到：

总览（通过率 / 耗时）
用例详情（点击展开看 metrics）
失败用例（若有）含 WAV 对比波形

2.3 单用例调试

# 运行单个用例（本地 Docker）
xitest run --case fx-eq-bass-boost-01 --local --verbose

# 本地调试模式保留 Docker 容器，便于 attach
xitest run --case fx-eq-bass-boost-01 --local --keep-container
docker exec -it xitest-debug-xxx bash

3. 编写你的第一个用例

3.1 用例目录结构

your-repo/
├── tests/
│   ├── fx/
│   │   ├── eq_bass_boost.test.yaml       ← 用例定义
│   │   └── golden/
│   │       ├── input_pink_noise.wav      ← 输入金标
│   │       └── output_expected.wav       ← 输出金标
│   └── conftest.yaml                     ← 套件共享配置

3.2 最小用例

# tests/fx/my_first_test.yaml
id: my-first-test
category: integration
description: "我的第一个 XiTest 用例 · 验证 EQ +3dB"

input:
  audio: "golden/input_1khz_sine.wav"
  sample_rate: 48000

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

expected:
  metrics:
    freq_response_at_1000hz: { value: 3.0, tolerance: 0.1 }

timeout: 30

3.3 生成输入金标

# 用 XiTest 工具生成
xitest generate-golden \
  --type sine --freq 1000 --duration 5 --sample-rate 48000 \
  --output tests/fx/golden/input_1khz_sine.wav

# 或用 sox
sox -n -r 48000 -b 24 tests/fx/golden/input_1khz_sine.wav synth 5 sine 1000

3.4 本地运行

xitest run --case my-first-test --local

3.5 提交到仓库

git add tests/fx/my_first_test.yaml tests/fx/golden/
git commit -m "test: add my first XiTest case"
git push

CI 会自动运行，结果在 PR 评论可见。

4. 用例高级技巧

4.1 参数化

id: fx-eq-multi-freq
category: integration
description: "EQ 多频率点验证"

parametrize:
  freq: [60, 100, 1000, 5000, 10000]
  gain: [-6, -3, 0, 3, 6]

input:
  audio: "golden/pink_noise.wav"

pipeline:
  - algorithm: xialgo.fx.eq
    params:
      band1: { freq: "${freq}", gain: "${gain}", Q: 1.0 }

expected:
  metrics:
    freq_response_at_${freq}hz: { value: "${gain}", tolerance: 0.2 }

→ 自动展开为 5×5 = 25 个用例。

4.2 依赖链路

id: e2e-full-chain
category: e2e

pipeline:
  - algorithm: xialgo.io.codec-decode
  - algorithm: xialgo.nr.sns
    params: { strength: high }
  - algorithm: xialgo.fx.eq
  - algorithm: xialgo.fx.drc

4.3 条件跳过

skip_if: "env.SKIP_HEAVY == 'true'"  # CI 快速模式下跳过

4.4 自定义断言（Python 回调）

id: custom-check-example
assert_script: "assertions/my_check.py"

# assertions/my_check.py
def assert_case(input_wav, output_wav, metrics, ctx):
    assert metrics["thd_n"] < 0.01, f"THD+N too high: {metrics['thd_n']}"
    # 自定义声学分析...
    return True

5. CI 集成实战

5.1 GitHub Actions（推荐）

见 API 规范 · CI 集成。

最佳实践：

PR 触发时跑 integration（20 min 内）
Push main 触发 regression（2h）
每日定时跑 nightly-full
将 XITEST_TOKEN 存入 GitHub Secrets

5.2 本地预跑（防止 CI 浪费）

# 提交前本地跑一遍
xitest run --suite smoke --local

# 或只跑你改动影响的用例
xitest run --affected --base main --local

5.3 失败时的排查

查看 PR 评论：XiTest Bot 会自动贴失败摘要
点击报告链接：查看 WAV 对比波形
本地复现：

xitest run --case <failed-case-id> --local --verbose

查日志：xitest logs <run-id> --case <case-id>

6. HIL 使用指南

6.1 申请 HIL 资源

# 查看可用 HIL 目标
xitest hil targets
# → XiDSP-D1-slot01 (Available)
#   XiDSP-D1-slot02 (Reserved until 2026-05-06 14:00 by bob)

# 预约独占 2h
xitest hil reserve --target XiDSP-D1-slot01 --duration 2h --reason "tapeout regression"

6.2 运行 HIL 套件

xitest run --hil --target XiDSP-D1-slot01 --suite tapeout-full --exclusive

预期：

24-48h 连续运行
进度实时推送到企业微信 / 邮件
完成后自动生成 Tapeout 放行报告

6.3 Tapeout 放行流程

运行 tapeout-full 套件
检查报告：全部通过 + 无假失败
算法 lead review → 签名
CTO review → 签名
归档放行报告到 tapeout-archive/ 仓库
通知硬件团队放行

7. UI 回归指南（工具团队）

7.1 编写 Playwright 脚本

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

test('创建并保存流图', async ({ page }) => {
  await page.goto(process.env.XISTUDIO_URL!);

  // 登录
  await page.fill('#user', 'qa@xisound.com');
  await page.fill('#pass', process.env.QA_PWD!);
  await page.click('button[type=submit]');

  // 创建项目
  await page.click('[data-test="new-project"]');
  await page.fill('[data-test="project-name"]', 'ui-test-01');

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

7.2 生成基准截图

# 首次生成基准
xitest run --ui --update-snapshots

# 后续回归对比
xitest run --ui

7.3 处理视觉差异

预期差异（如刻意 UI 改动）：删除旧基准 → 重新生成
非预期差异（回归）：查看 diff.png 定位像素差 → 修复代码

8. 故障排查

8.1 常见错误码速查

错误	可能原因	解决
`40100 Token invalid`	Token 过期 / 无效	重新生成 Token
`40301 Permission denied`	无金标更新权限	联系 QA Lead 加入 Tapeout-Gate 组
`40901 HIL conflict`	HIL 被占用	`xitest hil targets` 查看空闲
`TIMEOUT`	用例超时	检查 `timeout` 字段 / 本地能否跑通
`假失败高`	环境抖动	查 `xitest logs` 是否网络超时

8.2 性能问题

症状	处理
Unit 很慢	减少外部依赖 · 用 Mock
Integration 慢	减小 WAV 长度 · 仅关键段
CI 超时	拆分套件 · 并行提升
HIL 排队长	预约高峰外 · 或申请扩容

8.3 Debug 工具

# 查看某次运行的日志
xitest logs run-20260505-001 --tail 100

# 查看 Worker 状态
xitest workers --type hil

# 查看金标基线历史
xitest baseline history fx-eq-bass-boost-01

9. 最佳实践

9.1 用例编写

原子性：一个用例只验证一件事
可重复：相同输入 → 相同输出
速度：Integration ≤ 30s · Unit ≤ 100ms
命名：<category>-<subcategory>-<feature>-<index>

9.2 金标管理

金标文件不超过 10MB（用 10s 片段即可）
金标更新必须走审批流
金标文件名含版本号（_v2）
定期 diff 检查历史基线

9.3 CI 策略

PR：Smoke + Integration（≤ 20min）
Push main：Regression（≤ 2h）
Release：Full + HIL + UI
Nightly：Full + 边界探索

10. 附录

10.1 关联文档

10.2 获取帮助

内部 Slack：#xitest-help
邮件：xitest-help@xisound.com
Office Hours：每周四 15:00-16:00

10.3 版本历史

版本	日期	要点
v1.0	2026-05-05	首版 · 覆盖全角色使用指南

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