VoiceStudio 冻结回归测试夹具tests/fixtures/omnivoice_data全解析结构、生成原理与 200 KB 预算约束【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudio本篇指南聚焦 VoiceStudio 仓库中的tests/fixtures/omnivoice_data/冻结回归测试夹具说明它如何被 PR 冒烟测试GATE-01在 macOS / Windows / Linux 三平台加载解释其确定性再生成机制uv run python scripts/seed-test-fixture.py、目录布局、SQLite 建库细节以及 ≤ 200 KB 的尺寸预算约束。读完本文你将掌握该夹具的完整生命周期——从 seed 脚本的字节级确定性生成到test_boot_smoke.py的隔离加载与冒烟断言再到为何该项目不走 alembic 迁移而直接使用backend/core/db.py::init_db()。什么是冻结回归测试夹具tests/fixtures/omnivoice_data/是一份冻结的frozen回归测试夹具一个被原样签入仓库、不可手工编辑、只能通过专用脚本重新生成的固定测试数据快照。它由tests/smoke/test_boot_smoke.py在每一次 PR上加载执行覆盖 macOS、Windows、Linux 三个平台对应仓库中的 GATE-01 冒烟门禁该门禁的原始需求文档已随.planning/目录从仓库移除具体可见 git 历史。它的存在意义在于让每一次 PR 冒烟测试都能在与生产环境一致的数据路径上运行——既有真实 SQLite 数据库文件、又有真实的声音文件与 JSON 镜像从而验证的不只是路由能否 import还包括真正触碰数据库的路径音色列表、历史列表等接口。这正是它区别于tests/test_router_smoke.py的升级之处后者只验证路由导入与最低成本接口前者进一步把后端指向已签入的夹具覆盖 DB 读写链路。目录布局与逐文件说明夹具共四个文件实际占用约 139 KB见下文尺寸预算验证结构如下tests/fixtures/omnivoice_data/ ├── README.md # 夹具说明 再生成路径即本文对应文档 ├── omnivoice.db # 全部 8 张表voice_profiles 恰 1 行历史表 0 行 └── voices/ └── test-voice/ ├── profile.json # voice_profiles 行的 JSON 镜像 └── sample.wav # 1 秒、24 kHz、单声道、16-bit PCM 静音omnivoice.dbSQLite 数据库由backend/core/db.py::init_db()建出的全部 8 张业务表不含sqlite_%系统表表名用途夹具内行数voice_profiles音色档案克隆/设计1test-voicegeneration_history语音生成历史0dub_history配音历史0studio_projects工作台项目0export_history导出历史0glossary_terms术语表0jobs任务队列0job_events任务事件流0以上计数、journal_mode delete、user_version 4均可通过直接打开tests/fixtures/omnivoice_data/omnivoice.db验证。8 张表的完整 DDL 定义在 backend/core/db.py 的_BASE_SCHEMA中——除上述 8 张表外该常量还声明了settings、mcp_client_bindings、pronunciation_entries、remote_workers等后来随版本演进新增的表因此种子脚本建出的实际表数量以init_db()在当前版本下的执行为准脚本运行环境实测为 8 张。voice_profiles表的核心列与profile.json对应包括id主键、name、ref_audio_path、ref_text、instruct、language默认Auto、locked_audio_path、seed、is_locked、created_at等。夹具中的唯一一行即为下文profile.json的内容。voices/test-voice/profile.json行的 JSON 镜像该文件是voice_profiles表唯一一行的 JSON 镜像内容如下排序键、2 空格缩进created_at为固定时间戳{ created_at: 1700000000.0, id: test-voice, instruct: , is_locked: 0, language: Auto, locked_audio_path: , name: Test Voice (silence), ref_audio_path: voices/test-voice/sample.wav, ref_text: silence, seed: null }其中ref_audio_path以相对路径指向同目录下的sample.wav与 backend/core/config.py 中VOICES_DIR DATA_DIR/voices、DB_PATH DATA_DIR/omnivoice.db的目录约定保持一致。voices/test-voice/sample.wav1 秒静音参考音频由scripts/seed-test-fixture.py::write_silence_wav生成的 1 秒、24 kHz、单声道、16-bit PCM 静音 WAV约 48 KB。生成逻辑与tests/test_api.py::make_wav_bytes互相印证setnchannels(1)、setsampwidth(2)、setframerate(24000)并用struct.pack(f{n_samples}h, *([0] * n_samples))写入全零采样。全部零采样值保证了字节级确定性——同一段代码无论在哪台机器上运行产出的 WAV 文件都逐字节相同。确定性再生成seed-test-fixture.py 的字节级原理夹具明确标注Do not edit by hand禁止手工编辑再生成的唯一入口是uv run python scripts/seed-test-fixture.py该脚本的核心设计目标有两个确定性与幂等性。确定性created_at固定为FIXED_CREATED_AT 1700000000.0任意选取的常量即可关键是固定WAV 采样全部为 0。因此重复执行脚本产出逐字节相同的夹具git diff 始终干净。幂等性脚本开头若发现夹具目录已存在会直接shutil.rmtree重建因此可安全反复运行。脚本执行流程对应 scripts/seed-test-fixture.py 的main()清理并重建voices/test-voice/目录调用write_silence_wav写出静音 WAV调用write_profile_json写出 JSON 镜像调用build_database构建 SQLite 数据库写出README.md统计目录总字节数若超过 200 KB 预算则打印错误并以非零退出码结束。build_database 的建库细节build_databasescripts/seed-test-fixture.py是脚本的技术核心有四处值得注意的细节路径注入core.config.DB_PATH是模块导入时确定的因此脚本在import core.config后直接覆盖cfg.DB_PATH str(db_path)再调用init_db()与get_db()——这也是为什么脚本需要先把backend/目录插入sys.path。日志静默任何后端 import 之前先设置os.environ[OMNIVOICE_DISABLE_FILE_LOG] 1避免向不存在的路径写日志文件。插入唯一行通过 SQL 直接向voice_profiles插入与 JSON 完全一致的一行数据。单文件收尾插入后执行PRAGMA wal_checkpoint(TRUNCATE)把 WAL 收拢回主库文件再切换回PRAGMA journal_modeDELETE最后防御性地删除可能残留的-wal/-shm/-journal侧车文件——确保夹具是单一.db文件不会在每次测试后让git status出现脏文件。为什么不用 alembic 而是 init_db()夹具 README 明确回答了这个问题backend/migrations/versions/目录内只有.gitkeep占位注意该目录现在实际包含0001至0011共 11 个迁移文件README 写作时为空从当前仓库看迁移链已随版本演进补齐但夹具构建路径仍刻意跟随init_db()而非 alembic。种子脚本刻意与init_db()对齐是为了与生产路径保持一致性parity with production生产环境首次启动也是走backend/core/db.py::init_db()建库而 alembic 迁移backend/core/db.py 的_run_alembic_upgrade是启动时的后续步骤用于版本升级场景例如 v0.2.7 → v0.3.0。因此夹具用init_db()建出的库才是全新安装语义下最真实的状态。值得一提的细节init_db()内部会把PRAGMA user_version推进到_migrate计算出的版本实测夹具内为 4而_BASE_SCHEMA也通过CREATE TABLE IF NOT EXISTS与_reconcile_additive_columnsbackend/core/db.py实现了无 alembic 也能收敛 schema的兼容路径——这与夹具不用 alembic的决策在精神上一致。冒烟测试如何消费夹具test_boot_smoke.pytests/smoke/test_boot_smoke.py是夹具的唯一消费方也是 GATE-01 的实际执行者。设计目标是在 warm uv 缓存下30 秒内跑完以便在每个 PR 上常驻运行而不拖慢评审。其工作方式有几个关键机制1. 环境准备任何后端 import 之前os.environ.setdefault(OMNIVOICE_MODEL, test) # 短路 2.4 GB 模型加载 os.environ.setdefault(OMNIVOICE_DISABLE_FILE_LOG, 1) # 不写日志文件OMNIVOICE_MODELtest与tests/test_router_smoke.py使用同一约定避免冒烟测试实际加载 2.4 GB 的 OmniVoice 模型。2. 每会话复制一份夹具核心隔离技巧测试不是直接使用签入的夹具而是先把整个夹具目录复制到tempfile.mkdtemp创建的临时目录SQLite 打开文件就会改动文件变更计数器若直接用签入文件git status会变脏后端运行时会在数据目录下创建dub_jobs/、outputs/、preview/等子目录同样会造成脏状态。因此在每个会话开始处shutil.copytree一次签入的冻结产物永远不被改动。3. 模块级 fixture 的 env 气泡clientfixture 用pytest.MonkeyPatch将OMNIVOICE_DATA_DIR指向副本然后_purge_backend_modules()清掉main/core/api/services及其子模块强制下一次 import 以当前环境重新解析core.config中的DB_PATH/VOICES_DIR。teardown 时先清模块再还原环境保证后续测试套件重新 import 时回到原来的数据目录——这是为了避免进程级os.environ泄漏导致本地组合运行pytest tests/ backend/tests/时相互污染的历史问题如 personas 导入写入一个数据目录而断言另一个、audiobook resume 读到的 DB 与写入的不同。4. 四个冒烟断言测试断言内容test_health_returns_okGET /health返回status ok且包含device字段该端点也是 release.yml 使用的存活探针test_profiles_endpoint_lists_fixture_voiceGET /profiles返回列表且包含id test-voice的条目test_system_info_includes_data_dirGET /system/info必须能解析出data_dir字段验证夹具接线路径test_history_endpoint_emptyGET /history返回[]夹具零历史行路由必须真正触达数据库对应实现分别位于 backend/api/routers/profiles.py、backend/api/routers/system.py、backend/api/routers/generation.py。如果夹具缺失测试会直接pytest.fail并提示先运行uv run python scripts/seed-test-fixture.py。200 KB 尺寸预算与验证夹具目录总大小必须 ≤ 200 KBSIZE_BUDGET_BYTES 200 * 1024目的是让每位贡献者的git clone保持轻量。seed 脚本在main()末尾通过directory_size_bytes递归累加所有文件字节数统计总量超过预算即打印错误并返回退出码 1。实测验证当前夹具目录du -sb约为 139727 字节约 139 KB其中omnivoice.db90 KB、sample.wav48 KB、README.md1.1 KB、profile.json267 B处于预算之内。这一预算也反过来约束了夹具内容的选择——1 秒的短静音 WAV 与单行数据库正是为了在真实可测与轻量克隆之间取得平衡。复现与验证路径小结如果你想在本地亲手走一遍夹具的完整生命周期# 1. 再生成夹具幂等输出逐字节一致 uv run python scripts/seed-test-fixture.py # 2. 验证夹具目录大小与内容 du -sb tests/fixtures/omnivoice_data/ # 3. 运行消费它的冒烟测试30 秒内、短路模型加载 uv run pytest tests/smoke/test_boot_smoke.py -v若冒烟测试报错提示夹具缺失按提示执行第一步即可若你改动了夹具内容导致 diff 混乱同样重新执行第一步即可恢复字节级一致的状态。该夹具在整个 CI 矩阵macOS / Windows / Linux上的稳定性正是 GATE-01 冒烟门禁可靠性的基石——这也是它被刻意设计为冻结 确定性再生成 200 KB 预算三重约束的原因。【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
VoiceStudio 冻结回归测试夹具（tests/fixtures/omnivoice_data）全解析：结构、生成原理与 200 KB 预算约束
VoiceStudio 冻结回归测试夹具tests/fixtures/omnivoice_data全解析结构、生成原理与 200 KB 预算约束【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudio本篇指南聚焦 VoiceStudio 仓库中的tests/fixtures/omnivoice_data/冻结回归测试夹具说明它如何被 PR 冒烟测试GATE-01在 macOS / Windows / Linux 三平台加载解释其确定性再生成机制uv run python scripts/seed-test-fixture.py、目录布局、SQLite 建库细节以及 ≤ 200 KB 的尺寸预算约束。读完本文你将掌握该夹具的完整生命周期——从 seed 脚本的字节级确定性生成到test_boot_smoke.py的隔离加载与冒烟断言再到为何该项目不走 alembic 迁移而直接使用backend/core/db.py::init_db()。什么是冻结回归测试夹具tests/fixtures/omnivoice_data/是一份冻结的frozen回归测试夹具一个被原样签入仓库、不可手工编辑、只能通过专用脚本重新生成的固定测试数据快照。它由tests/smoke/test_boot_smoke.py在每一次 PR上加载执行覆盖 macOS、Windows、Linux 三个平台对应仓库中的 GATE-01 冒烟门禁该门禁的原始需求文档已随.planning/目录从仓库移除具体可见 git 历史。它的存在意义在于让每一次 PR 冒烟测试都能在与生产环境一致的数据路径上运行——既有真实 SQLite 数据库文件、又有真实的声音文件与 JSON 镜像从而验证的不只是路由能否 import还包括真正触碰数据库的路径音色列表、历史列表等接口。这正是它区别于tests/test_router_smoke.py的升级之处后者只验证路由导入与最低成本接口前者进一步把后端指向已签入的夹具覆盖 DB 读写链路。目录布局与逐文件说明夹具共四个文件实际占用约 139 KB见下文尺寸预算验证结构如下tests/fixtures/omnivoice_data/ ├── README.md # 夹具说明 再生成路径即本文对应文档 ├── omnivoice.db # 全部 8 张表voice_profiles 恰 1 行历史表 0 行 └── voices/ └── test-voice/ ├── profile.json # voice_profiles 行的 JSON 镜像 └── sample.wav # 1 秒、24 kHz、单声道、16-bit PCM 静音omnivoice.dbSQLite 数据库由backend/core/db.py::init_db()建出的全部 8 张业务表不含sqlite_%系统表表名用途夹具内行数voice_profiles音色档案克隆/设计1test-voicegeneration_history语音生成历史0dub_history配音历史0studio_projects工作台项目0export_history导出历史0glossary_terms术语表0jobs任务队列0job_events任务事件流0以上计数、journal_mode delete、user_version 4均可通过直接打开tests/fixtures/omnivoice_data/omnivoice.db验证。8 张表的完整 DDL 定义在 backend/core/db.py 的_BASE_SCHEMA中——除上述 8 张表外该常量还声明了settings、mcp_client_bindings、pronunciation_entries、remote_workers等后来随版本演进新增的表因此种子脚本建出的实际表数量以init_db()在当前版本下的执行为准脚本运行环境实测为 8 张。voice_profiles表的核心列与profile.json对应包括id主键、name、ref_audio_path、ref_text、instruct、language默认Auto、locked_audio_path、seed、is_locked、created_at等。夹具中的唯一一行即为下文profile.json的内容。voices/test-voice/profile.json行的 JSON 镜像该文件是voice_profiles表唯一一行的 JSON 镜像内容如下排序键、2 空格缩进created_at为固定时间戳{ created_at: 1700000000.0, id: test-voice, instruct: , is_locked: 0, language: Auto, locked_audio_path: , name: Test Voice (silence), ref_audio_path: voices/test-voice/sample.wav, ref_text: silence, seed: null }其中ref_audio_path以相对路径指向同目录下的sample.wav与 backend/core/config.py 中VOICES_DIR DATA_DIR/voices、DB_PATH DATA_DIR/omnivoice.db的目录约定保持一致。voices/test-voice/sample.wav1 秒静音参考音频由scripts/seed-test-fixture.py::write_silence_wav生成的 1 秒、24 kHz、单声道、16-bit PCM 静音 WAV约 48 KB。生成逻辑与tests/test_api.py::make_wav_bytes互相印证setnchannels(1)、setsampwidth(2)、setframerate(24000)并用struct.pack(f{n_samples}h, *([0] * n_samples))写入全零采样。全部零采样值保证了字节级确定性——同一段代码无论在哪台机器上运行产出的 WAV 文件都逐字节相同。确定性再生成seed-test-fixture.py 的字节级原理夹具明确标注Do not edit by hand禁止手工编辑再生成的唯一入口是uv run python scripts/seed-test-fixture.py该脚本的核心设计目标有两个确定性与幂等性。确定性created_at固定为FIXED_CREATED_AT 1700000000.0任意选取的常量即可关键是固定WAV 采样全部为 0。因此重复执行脚本产出逐字节相同的夹具git diff 始终干净。幂等性脚本开头若发现夹具目录已存在会直接shutil.rmtree重建因此可安全反复运行。脚本执行流程对应 scripts/seed-test-fixture.py 的main()清理并重建voices/test-voice/目录调用write_silence_wav写出静音 WAV调用write_profile_json写出 JSON 镜像调用build_database构建 SQLite 数据库写出README.md统计目录总字节数若超过 200 KB 预算则打印错误并以非零退出码结束。build_database 的建库细节build_databasescripts/seed-test-fixture.py是脚本的技术核心有四处值得注意的细节路径注入core.config.DB_PATH是模块导入时确定的因此脚本在import core.config后直接覆盖cfg.DB_PATH str(db_path)再调用init_db()与get_db()——这也是为什么脚本需要先把backend/目录插入sys.path。日志静默任何后端 import 之前先设置os.environ[OMNIVOICE_DISABLE_FILE_LOG] 1避免向不存在的路径写日志文件。插入唯一行通过 SQL 直接向voice_profiles插入与 JSON 完全一致的一行数据。单文件收尾插入后执行PRAGMA wal_checkpoint(TRUNCATE)把 WAL 收拢回主库文件再切换回PRAGMA journal_modeDELETE最后防御性地删除可能残留的-wal/-shm/-journal侧车文件——确保夹具是单一.db文件不会在每次测试后让git status出现脏文件。为什么不用 alembic 而是 init_db()夹具 README 明确回答了这个问题backend/migrations/versions/目录内只有.gitkeep占位注意该目录现在实际包含0001至0011共 11 个迁移文件README 写作时为空从当前仓库看迁移链已随版本演进补齐但夹具构建路径仍刻意跟随init_db()而非 alembic。种子脚本刻意与init_db()对齐是为了与生产路径保持一致性parity with production生产环境首次启动也是走backend/core/db.py::init_db()建库而 alembic 迁移backend/core/db.py 的_run_alembic_upgrade是启动时的后续步骤用于版本升级场景例如 v0.2.7 → v0.3.0。因此夹具用init_db()建出的库才是全新安装语义下最真实的状态。值得一提的细节init_db()内部会把PRAGMA user_version推进到_migrate计算出的版本实测夹具内为 4而_BASE_SCHEMA也通过CREATE TABLE IF NOT EXISTS与_reconcile_additive_columnsbackend/core/db.py实现了无 alembic 也能收敛 schema的兼容路径——这与夹具不用 alembic的决策在精神上一致。冒烟测试如何消费夹具test_boot_smoke.pytests/smoke/test_boot_smoke.py是夹具的唯一消费方也是 GATE-01 的实际执行者。设计目标是在 warm uv 缓存下30 秒内跑完以便在每个 PR 上常驻运行而不拖慢评审。其工作方式有几个关键机制1. 环境准备任何后端 import 之前os.environ.setdefault(OMNIVOICE_MODEL, test) # 短路 2.4 GB 模型加载 os.environ.setdefault(OMNIVOICE_DISABLE_FILE_LOG, 1) # 不写日志文件OMNIVOICE_MODELtest与tests/test_router_smoke.py使用同一约定避免冒烟测试实际加载 2.4 GB 的 OmniVoice 模型。2. 每会话复制一份夹具核心隔离技巧测试不是直接使用签入的夹具而是先把整个夹具目录复制到tempfile.mkdtemp创建的临时目录SQLite 打开文件就会改动文件变更计数器若直接用签入文件git status会变脏后端运行时会在数据目录下创建dub_jobs/、outputs/、preview/等子目录同样会造成脏状态。因此在每个会话开始处shutil.copytree一次签入的冻结产物永远不被改动。3. 模块级 fixture 的 env 气泡clientfixture 用pytest.MonkeyPatch将OMNIVOICE_DATA_DIR指向副本然后_purge_backend_modules()清掉main/core/api/services及其子模块强制下一次 import 以当前环境重新解析core.config中的DB_PATH/VOICES_DIR。teardown 时先清模块再还原环境保证后续测试套件重新 import 时回到原来的数据目录——这是为了避免进程级os.environ泄漏导致本地组合运行pytest tests/ backend/tests/时相互污染的历史问题如 personas 导入写入一个数据目录而断言另一个、audiobook resume 读到的 DB 与写入的不同。4. 四个冒烟断言测试断言内容test_health_returns_okGET /health返回status ok且包含device字段该端点也是 release.yml 使用的存活探针test_profiles_endpoint_lists_fixture_voiceGET /profiles返回列表且包含id test-voice的条目test_system_info_includes_data_dirGET /system/info必须能解析出data_dir字段验证夹具接线路径test_history_endpoint_emptyGET /history返回[]夹具零历史行路由必须真正触达数据库对应实现分别位于 backend/api/routers/profiles.py、backend/api/routers/system.py、backend/api/routers/generation.py。如果夹具缺失测试会直接pytest.fail并提示先运行uv run python scripts/seed-test-fixture.py。200 KB 尺寸预算与验证夹具目录总大小必须 ≤ 200 KBSIZE_BUDGET_BYTES 200 * 1024目的是让每位贡献者的git clone保持轻量。seed 脚本在main()末尾通过directory_size_bytes递归累加所有文件字节数统计总量超过预算即打印错误并返回退出码 1。实测验证当前夹具目录du -sb约为 139727 字节约 139 KB其中omnivoice.db90 KB、sample.wav48 KB、README.md1.1 KB、profile.json267 B处于预算之内。这一预算也反过来约束了夹具内容的选择——1 秒的短静音 WAV 与单行数据库正是为了在真实可测与轻量克隆之间取得平衡。复现与验证路径小结如果你想在本地亲手走一遍夹具的完整生命周期# 1. 再生成夹具幂等输出逐字节一致 uv run python scripts/seed-test-fixture.py # 2. 验证夹具目录大小与内容 du -sb tests/fixtures/omnivoice_data/ # 3. 运行消费它的冒烟测试30 秒内、短路模型加载 uv run pytest tests/smoke/test_boot_smoke.py -v若冒烟测试报错提示夹具缺失按提示执行第一步即可若你改动了夹具内容导致 diff 混乱同样重新执行第一步即可恢复字节级一致的状态。该夹具在整个 CI 矩阵macOS / Windows / Linux上的稳定性正是 GATE-01 冒烟门禁可靠性的基石——这也是它被刻意设计为冻结 确定性再生成 200 KB 预算三重约束的原因。【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考