Pyodide 开发测试与基准测试指南:pytest 套件、多运行时驱动、Benchmark 与 Lint 工具链全解析

原创2026-09-21 15:33:441,973 阅读
文章标签:科学计算开发工具

Pyodide 开发测试与基准测试指南:pytest 套件、多运行时驱动、Benchmark 与 Lint 工具链全解析

Pyodide 是一个基于 WebAssembly 的 Python 发行版,可在浏览器与 Node.js 中运行完整的 Python 解释器。由于它同时包含 C 层核心(src/core)、Python 层封装(src/py)、JavaScript 侧 API(src/js)与数十个内置包,其质量保障体系横跨 Python、JS/TS、C 三种语言与 Chrome/Firefox/Node 三种运行时。本文以官方开发文档 docs/development/testing.md 为骨架,结合仓库内真实源码(conftest.py、Makefile、benchmark/benchmark.py)与测试用例,系统讲解如何运行 Python 测试套件、切换浏览器运行时、理解引用泄漏检测机制、执行 JavaScript 测试、开展手动交互测试、跑性能基准以及接入统一 Lint 工具链。读完本文,你将掌握 Pyodide 从「改代码」到「过测试、查性能、过 Lint」的完整开发闭环。

一、测试体系总览

Pyodide 的测试由 pytest 统一驱动,核心依赖是官方插件 pytest-pyodide——它是专门为 Pyodide 及使用 Pyodide 的第三方应用设计的 pytest 插件,负责在真实的浏览器或 Node.js 环境中启动 Pyodide、管理 selenium fixture,并在测试结束时自动执行内存泄漏检查。仓库根目录的 conftest.py 在第 19–20 行直接 from pytest_pyodide import get_global_config 并导入 package_is_built,可见整个测试基础设施都构建在 pytest-pyodide 之上。

pytest 会收集两类测试位置:

从 conftest.py 的 maybe_skip_test(第 123–149 行)可以看到一个关键行为:当某个包未构建时,其对应的 test_*.py 用例会被自动跳过(package '{package_name}' is not built.)。这保证了未参与构建的包不会让测试套件整体失败。

二、运行 Python 测试套件

1. 安装依赖与浏览器驱动

首先将测试依赖安装到默认的 Python 环境中:

pip install pytest-pyodide pytest-httpserver
  • pytest-pyodide:pytest 插件,提供 selenium fixture、--runtime 命令行选项、运行时配置等核心能力;
  • pytest-httpserver:本地 HTTP 测试服务器,用于测试 Pyodide 的 HTTP 相关功能(如 src/tests/test_pyodide_http.py)。

随后安装浏览器驱动 geckodriver(Firefox)或 chromedriver(Chrome),并确保它们位于 PATH 中。Selenium 通过这些驱动与浏览器通信,PATH 中找不到驱动会直接导致测试无法启动。

2. 运行全部测试

在 Pyodide 仓库根目录直接运行:

pytest

该命令会收集上文提到的两类测试位置并逐条执行。如果想只跑某个文件,传入对应路径即可:

pytest src/tests/test_pyproxy.py
pytest packages/numpy/test_numpy.py

3. 指定浏览器运行时:--runtime

不同浏览器对 WebAssembly、JSPI(JavaScript Promise Integration)等特性的实现存在差异,出错信息也详略不一。当遇到难以理解的报错时,官方建议在每个浏览器上分别重跑一遍,通过 --runtime 指定运行环境:

pytest --runtime firefox
pytest --runtime chrome
pytest --runtime node

pytest-pyodide 支持的运行时包括 firefox、chrome、node(safari 也可用,见 conftest.py 第 127 行的正则 firefox|chrome|node|safari)。不同运行时会使用不同的浏览器标志与加载脚本——conftest.py 的 set_configs() 中即为各运行时注入了差异配置:

  • Chrome:追加 --enable-features=WebAssemblyExperimentalJSPI 启动标志(第 28–40 行),并刻意不传 --enable-experimental-webassembly-features,以确保在「有 JSPI 但没有 type reflection」的配置下也能正常工作;
  • Node:追加 --experimental-wasm-jspi 标志(第 42–45 行),并加载 snapshot.bin 快照(第 77–88 行);
  • 无论哪个运行时,测试开始前都会执行一段 initialize_script(第 50–66 行),预先触摸 hiwire 缓存中的全局对象(如 pyodide.globals.get、pyodide._api.package_loader.unpack_buffer 等),避免这些「进入缓存但从不离开」的对象干扰后续引用计数检查。

4. 自定义测试标记:引用泄漏检查

Pyodide 对测试的默认要求非常严格:如果某个测试创建了 JavaScript 引用(JsRefs)或 PyProxy 却没有清理,测试会直接失败。这正是 skip_refcount_check 与 skip_pyproxy_check 两个自定义标记存在的意义:

  • @pytest.mark.skip_refcount_check:禁用对 JavaScript 引用(hiwire 键)的泄漏检查;
  • @pytest.mark.skip_pyproxy_check:禁用对 PyProxy 的泄漏检查。

当一个测试已知会泄漏对象、但这是其设计使然时,用这两个标记显式豁免。仓库中大量测试都使用了这些标记,例如 src/tests/test_console.py 与 src/tests/test_database_driver.py。

这两个标记的底层实现位于 conftest.py 的 pytest_runtest_call 钩子(第 247–277 行)与 extra_checks_test_wrapper(第 280–328 行):

  1. 测试运行前记录 init_num_keys(hiwire 键数)与 init_num_proxies(PyProxy 数),并调用 browser.enable_pyproxy_tracing() 开启代理追踪;
  2. 测试结束后在 finally 中禁用追踪、恢复状态,并执行 pyodide._module._clear_method_call_singleton() 清除持有最后一个 JS 方法的单例,避免它干扰检查;
  3. 最后断言 (delta_proxies, delta_keys) == (0, 0) or delta_keys < 0——即 PyProxy 与 JsRef 都不得净增长;若发现泄漏,还会通过 pyproxy_alloc_map 打印出泄漏代理的创建现场(traceback),帮助定位泄漏点。

5. 其他实用的 pytest 选项与标记

从 conftest.py 的 pytest_addoption 与 pytest_collection_modifyitems 中还可以发掘出文档之外、但对日常开发非常实用的能力:

  • pytest --run-xfail:强制运行被标记为 xfail(预期失败)的测试,用于验证某个已知 bug 是否已修复;
  • pytest --skip-passed:跳过上次运行中已通过的测试,缩短迭代周期(注意:即使测试被修改也会跳过,需谨慎使用,见第 113–119 行的警告);
  • @pytest.mark.long_running:标记耗时长的测试,非 CI 环境下默认跳过,只有显式 -m long_running 或设置环境变量 CI=1 才会执行(第 196–205 行);
  • @pytest.mark.db:需要数据库驱动的测试,必须显式 -m db 才会运行(第 207–213 行);
  • 跨浏览器专用标记:only_node、only_chrome、requires_jspi 通过 xfail_browsers 定义(第 94–103 行),用于把只在特定运行时有效的用例自动 xfail 掉。

此外 conftest.py 还借助 pytest_terminal_summary 钩子(第 221–244 行)把每次运行的结果写入 pytest 缓存,为 --skip-passed 提供数据;cwd_relative_nodeid 被 monkey-patch 掉 src/tests/ 与 packages/ 前缀(第 152–170 行),让失败摘要里的测试名更短更易读。

三、运行 JavaScript 测试套件

Pyodide 的 JS 侧 API(src/js/pyodide.ts)有独立的测试与类型检查流程:

cd src/js
npm test

npm test 运行 JS/TS 层的单元与集成测试(用例位于 src/js/test,如 sanity.test.ts、installer.test.ts),测试配置在 src/js/playwright.config.ts 中定义。

类型定义的正确性用 tsd 校验:

npx tsd

tsd 读取 src/js/package.json 中配置的测试入口(src/test-js 目录下的 index.test-d.ts),编译时验证公开类型签名是否可用。

四、手动交互测试

自动化测试之外,Pyodide 还提供了轻量的手动测试路径:

  1. 先构建 Pyodide(可在 docker 镜像中完成构建,详见 docs/development/building-from-sources.md);
  2. 在 docker 镜像外,cd 到构建产物 dist 目录并启动静态文件服务器:
cd dist
python -m http.server
  1. 浏览器访问 http://localhost:<PORT>/console.html 即可开始交互测试。官方明确建议:在浏览器控制台里使用 pyodide.runPython 而非页面自带的 REPL。这是因为 console.html(模板位于 src/templates/console.html)只是一个交互入口,而 pyodide.runPython 能直接在当前上下文执行并返回结果,配合 DevTools 断点与源码映射,调试体验更佳;docs/development/debugging.md 还提到 Chrome 系的 DevTools 对 WASM/C 层的调试支持更好。

五、性能基准测试(Benchmarking)

运行基准测试的前置条件与测试相同(安装 pytest-pyodide 等依赖与浏览器驱动)。Pyodide 用一个 Makefile target 串联起整套基准流程:

PYODIDE_PACKAGES="numpy,matplotlib" make benchmark

PYODIDE_PACKAGES 指定需要先构建进发行版的包(基准脚本依赖 numpy 等)。从 Makefile 可以看到该 target 实际执行两步:

$(HOSTPYTHON) benchmark/benchmark.py all --output dist/benchmarks.json
$(HOSTPYTHON) benchmark/plot_benchmark.py dist/benchmarks.json dist/benchmarks.png

即先运行 benchmark/benchmark.py 收集所有基准数据到 dist/benchmarks.json,再由 benchmark/plot_benchmark.py 生成可视化图表 dist/benchmarks.png。

benchmark.py 的工作原理

从 benchmark/benchmark.py 源码可以了解基准测试的精确行为:

  • 基准集划分:内置 pystone 与 numpy 两类基准,分别来自 benchmark/benchmarks/pystone_benchmarks 与 benchmark/benchmarks/numpy_benchmarks(后者包含 30+ 个数值计算脚本,如 fft、grayscott、mandel、julia 等);SKIP = {"fft", "hyantes"}(第 17 行)会跳过这两个不稳定基准;
  • 基准文件格式:每个脚本以 # setup: ... 与 # run: ... 注释声明 setup 与 run 代码(parse_benchmark 第 75–83 行),run 代码末尾须 print 一个数值结果;
  • 计时方式:基于 timeit.Timer,repeat=5, number=5(第 86–107 行),去掉最大与最小值后取平均,抑制抖动;
  • native 对照:run_native(第 28–42 行)在宿主 Python 中执行同一份代码,作为 WebAssembly 性能的天然参照;
  • wasm 运行:run_wasm(第 45–60 行)通过 selenium.run 在浏览器中执行,并测试有无 interrupt buffer 两种模式(带中断缓冲记为 (w/ ib),用于评估 setInterruptBuffer 对性能的影响),见 run_all(第 63–72 行);
  • 命令行参数(parse_args 第 127–155 行):target 可指定 pystone、numpy 或 all;-o/--output 默认输出到 dist/benchmarks.json;--timeout 默认 1200 秒,用于控制每个基准的浏览器超时;--dist-dir 指定 Pyodide 的 dist 目录。

因此除 make benchmark 外,也可以直接调用 benchmark.py 只跑某类基准,例如 python benchmark/benchmark.py numpy。

六、Lint 工具链

Pyodide 的 Lint 统一由 prek 调度(官方文档原文为 prek,即仓库使用的 pre-commit 封装入口):

  • Python:ruff(lint + format)与 mypy,对应配置在 pyproject.toml(第 1 行 [tool.mypy]、第 49 行 [tool.ruff])中;
  • JavaScript / TypeScript:biome,配置见 biome.json;
  • C:clang-format。

一键执行全部检查:

prek -a

如果想在每次 commit 时自动触发 Lint,可以安装并启用 prek 的 git hook:

pip install prek
prek install

不再需要时可随时卸载:

prek uninstall

即使本地漏掉了 Lint,pre-commit.ci 也会在推送分支时自动修复部分 lint 错误并 push 修复到你的分支——这意味着你需要先拉取远程改动(或 force push)才能继续提交新 commit。

七、小结:一条完整的开发验证流水线

综合以上内容,Pyodide 贡献者的典型验证流程可以概括为:

  1. 改代码:涉及 Python/JS/TS/C 任一语言;
  2. 跑针对性测试:pytest src/tests/test_xxx.py --runtime chrome(必要时 --skip-passed 加速迭代),记得利用 skip_refcount_check / skip_pyproxy_check 处理已知泄漏用例;
  3. 跑 JS 侧:cd src/js && npm test,再 npx tsd 校验类型;
  4. 验性能:PYODIDE_PACKAGES="numpy,matplotlib" make benchmark,对照 native 基线分析 WASM 性能;
  5. 过 Lint:prek -a 全量检查,或 prek install 挂上 commit hook。

这套「pytest + selenium 多运行时 + 引用泄漏检测 + benchmark + prek」的组合,正是 Pyodide 能在浏览器、Node.js 两种环境下持续保持稳定与性能的工程根基,也是第三方项目使用 pytest-pyodide 复刻这套测试模式的最佳参考样板。

登录后查看全文
pyodide