测试

本文档描述了 ffmpeg.wasm 的测试基础设施、方法和流程。它涵盖了单线程 (ST) 和多线程 (MT) 库版本的基于浏览器的测试以及 CI/CD 测试。

1. 测试架构

ffmpeg.wasm 的测试架构旨在验证不同线程模式下的核心 WebAssembly 模块和 JavaScript API 层。

1.1 测试基础设施概览

"自然语言到代码实体空间：基础设施"

测试

1.2 测试组织

测试被组织为四个主要入口点，以覆盖 Core 与 API 以及 ST 与 MT 的组合。

测试入口点目的逻辑文件
测试单线程模式下的低级别 ffmpeg-core
测试多线程模式下的低级别 ffmpeg-core
测试高级别 @ffmpeg/ffmpeg API (ST)
测试高级别 @ffmpeg/ffmpeg API (MT)

2. 测试套件实现

2.1 核心模块测试 (ffmpeg-core.test.js)

这些测试验证 Emscripten 编译模块的直接导出。该套件使用 createFFmpegCore 工厂来实例化模块

被测函数验证的行为
core.reset()将 ret 和 timeout 属性重置为 -1
core.exec()执行 FFmpeg 命令并返回退出码
core.setTimeout()在指定毫秒后终止执行
core.setLogger()通过回调捕获 stdout/stderr
core.setProgress()跟踪转码进度 (0.0 到 1.0)

2.2 API 层测试 (ffmpeg.test.js)

这些测试验证 @ffmpeg/ffmpeg 包装类。它们使用一个 createFFmpeg 辅助函数来初始化具有特定 coreURL 和 thread 配置的 FFmpeg 类

  • VFS 操作: 验证 listDir, createDir, deleteDir 和 rename
  • 文件 I/O: 验证 writeFile 和 readFile 用于文本和二进制 Uint8Array 数据
  • 执行控制:
    • 成功: exec 在成功转码时返回 0
    • 超时: 如果达到超时时间，exec 返回 1
    • 中止: 使用 AbortController 取消活动任务，期望抛出 AbortError

3. 环境设置与安全

ffmpeg.wasm 中的多线程需要 SharedArrayBuffer，这仅在跨源隔离 (Cross-Origin Isolated)环境中可用。

3.1 安全标头

测试服务器必须提供特定的 HTTP 标头。apps/vanilla-app/server.js 的实现提供了参考：

  • Cross-Origin-Opener-Policy: same-origin
  • Cross-Origin-Embedder-Policy: require-corp

3.2 浏览器验证

在运行 MT 测试之前，CI 管道会执行 verify-browser.html 脚本来检查两个条件：

  1. typeof SharedArrayBuffer !== 'undefined'
  2. window.crossOriginIsolated === true

4. 在 CI 中运行测试

GitHub Actions 工作流编排构建和测试过程。

"自然语言到代码实体空间：CI 工作流"

测试

4.1 无头 Chrome 配置

Chrome 使用特定标志启动，以便在无头环境中启用 WebAssembly 功能：

  • --headless
  • --no-sandbox
  • --enable-features=SharedArrayBuffer,CrossOriginIsolation

5. Node.js 环境辅助工具

虽然主要的测试目标是浏览器，但存储库包含用于基于 Node.js 环境的辅助工具（尽管对于 MT 更推荐使用浏览器测试）：

  • test-helper-st.js: 设置 FFMPEG_TYPE = "st" 并加载 ST 核心
  • test-helper-mt.js: 设置 FFMPEG_TYPE = "mt" 并加载 MT 核心