企业官网建设流程全解析

Glances 测试指南：基于变更文件选择测试套件、运行与调试完整实战

【免费下载链接】glancesGlances an Eye on your system. A top/htop alternative for GNU/Linux, BSD, macOS and Windows operating systems.项目地址: https://gitcode.com/gh_mirrors/gl/glances

本文是一份面向 Glances 开发者的实战测试手册，核心内容来自仓库内 .claude/skills/test.md 技能文档：它定义了"先看 git diff、再按变更文件映射测试套件、最后用 Makefile 目标执行"的标准测试流程。读完本文，你将掌握 Glances 全部make test-*目标的适用场景、底层实际执行的 pytest 命令、单测与集成测试的运行方式，以及测试失败后的分析思路。

一、测试策略总览：先看变更，再选套件

Glances 是一个插件化架构的系统监控工具（CLI、Web UI、REST API、各类导出器一应俱全），因此它的测试也被拆分为多个彼此独立的套件。盲目运行全量测试既慢又难以定位问题，正确做法是根据本次代码变更的影响范围，只运行对应的测试套件。

标准流程（来自 .claude/skills/test.md）：

1. 先用git diff --name-only查看已修改的文件（包含已暂存 staged 与未暂存 unstaged 的变更）。
2. 根据变更文件所在目录，按下表选择要运行的测试套件。
3. 若用户明确指定了测试目标（例如"运行 core 测试"），直接使用该目标，跳过推断。
4. 通过 Makefile 目标执行测试，前提是虚拟环境已就绪（仓库约定为.venv-uv/）。
5. 测试失败时，分析输出并定位问题。

变更文件与测试套件的映射关系

从 Makefile 可以看到，UNIT_TESTS := test-core test-restful test-xmlrpc这三个目标被定义为常规单元测试集合，而test-exports由于涉及真实外部服务（数据库、消息队列等），单独使用 Docker 环境运行。

二、完整的测试命令矩阵

.claude/skills/test.md 提供的全部命令如下，其中每个make目标在 Makefile 中都有明确对应的底层命令：

make test # All tests（全量测试） make test-core # Core unit tests（核心单元测试） make test-plugins # Plugin tests（插件测试） make test-api # API unit tests（API 单元测试） make test-restful # REST API tests（REST API 测试） make test-webui # WebUI tests (Selenium)（WebUI 测试） make test-xmlrpc # XML-RPC tests（XML-RPC 测试） make test-exports # All export integration tests (needs Docker)（全部导出集成测试，需要 Docker） make test-perf # Performance tests（性能测试） make test-memoryleak # Memory leak tests（内存泄漏测试） # 单个测试文件或指定用例： .venv-uv/bin/uv run pytest tests/test_core.py .venv-uv/bin/uv run pytest tests/test_core.py::TestGlances::test_000_update

各目标背后的真实命令

结合 Makefile，每个目标的底层执行逻辑如下：

• make test→.venv-uv/bin/uv run pytest：不带路径参数，pytest 会递归收集tests/下所有测试文件，属于全量回归。
• make test-core→.venv-uv/bin/uv run pytest tests/test_core.py：只跑核心测试文件。
• make test-plugins→.venv-uv/bin/uv run pytest tests/test_plugin_*.py：shell 通配符展开后，会运行 tests 目录下所有test_plugin_*.py文件，例如test_plugin_cpu.py、test_plugin_mem.py、test_plugin_gpu.py、test_plugin_npu.py、test_plugin_smart.py等。
• make test-api→.venv-uv/bin/uv run pytest tests/test_api.py。
• make test-restful→.venv-uv/bin/uv run pytest tests/test_restful.py。
• make test-webui→.venv-uv/bin/uv run pytest tests/test_webui.py。
• make test-xmlrpc→.venv-uv/bin/uv run pytest tests/test_xmlrpc.py。
• make test-memoryleak→.venv-uv/bin/uv run pytest tests/test_memoryleak.py。
• make test-perf→.venv-uv/bin/uv run pytest tests/test_perf.py。
• make test-exports→ 遍历执行./tests/test_export_*.sh下的全部 shell 脚本，包括test_export_csv.sh、test_export_json.sh、test_export_influxdb_v1.sh、test_export_influxdb_v3.sh、test_export_timescaledb.sh、test_export_nats.sh、test_export_clickhouse.sh等。每个脚本会真实启动 Glances 并将数据导出到对应外部服务。

此外还有两个有用的变体：

• make test-with-upgrade：先升级依赖（venv-upgrade）再跑全量测试，用于依赖变更后的回归验证。
• 单目标导出测试：如make test-export-csv只运行./tests/test_export_csv.sh，适合只想验证某个导出器时使用。

关于运行环境的重要前提

• 所有测试依赖基于uv管理的虚拟环境.venv-uv/，Makefile 中统一通过UV_RUN := .venv-uv/bin/uv调用。
• 创建虚拟环境的方式见 Makefile：make install-uv创建环境并安装 uv，随后make venv使用uv sync --all-extras --no-group dev安装全部依赖；如需开发依赖（pytest、selenium 等），使用make venv-dev（还会安装 pre-commit hooks）。
• 若仓库中不存在.venv-uv/，需要先按上述步骤初始化，否则make test-*会因找不到解释器而失败。

三、按模块深入：各测试套件在测什么

3.1 Core 测试（tests/test_core.py）

核心测试文件 tests/test_core.py 体量最大（约 1400 行），直接覆盖 Glances 最底层的通用能力，例如：

• 从glances.globals导入的auto_unit、pretty_date、split_esc、string_value_to_float、subsample等工具函数；
• 阈值系统 glances/thresholds.py 中的GlancesThresholdOk/Warning/Careful/Critical与GlancesThresholds；
• 过滤机制GlancesFilter/GlancesFilterList（glances/filter.py）；
• 事件列表GlancesEventsList、条形图Bar、插件 DAG 依赖解析get_plugin_dependencies（glances/plugins/plugin/dag.py）；
• 以及插件模型GlancesPluginModel、ZFS 插件、MPP/NPU 插件等跨平台能力。

测试文件顶部还展示了核心测试的初始化模式（tests/test_core.py）：

testargs = ["glances", "-C", "./conf/glances.conf"] with patch('sys.argv', testargs): core = GlancesMain() test_config = core.get_config() test_args = core.get_args() stats = GlancesStats(config=test_config, args=test_args)

它通过 mocksys.argv以-C ./conf/glances.conf启动GlancesMain，再构建GlancesStats，所有核心测试都围绕这份真实的 stats 实例展开。这解释了为什么运行测试前工作目录必须是仓库根目录——测试依赖./conf/glances.conf相对路径。

3.2 共享 Fixtures（tests/conftest.py）

tests/conftest.py 为多个套件提供了共享的 pytest fixtures：

• glances_stats（session 级）：同样以-C ./conf/glances.conf初始化GlancesMain+GlancesStats，供插件类测试复用。
• glances_stats_no_history：在参数中设置time=1、cached_time=1、disable_history=True，用于需要关闭历史记录的测试（如内存泄漏测试）。
• glances_webserver：启动一个真实的 Glances Web 服务器（端口 61234，带-w --browser），并先检查端口是否被占用——如果 61234 已被占用会直接pytest.fail，防止测试打到残留的旧 Glances 进程上；随后通过轮询http://localhost:61234/api/4/status健康检查端点确认服务就绪。
• web_browser：初始化 headless Chrome（Selenium），若未安装 selenium 则自动 skip WebUI 测试。

3.3 REST API 测试（tests/test_restful.py）

tests/test_restful.py 针对 glances/outputs/glances_restful_api.py 实现：

• 测试服务运行在http://localhost:61234/api/{API_VERSION}，其中API_VERSION直接取自GlancesRestfulApi.API_VERSION，保证测试跟随实现版本；
• 第二个服务运行在端口 61235（CORS_URL），专门用于验证 CORS 凭证防护（对应安全通告 GHSA-fp27-88fp-2phg）；
• 测试会校验 API 返回字段的类型（numbers.Number等），并覆盖 gzip 压缩响应（Accept-encoding: gzip）。

3.4 WebUI 测试（tests/test_webui.py）

tests/test_webui.py 使用Selenium + ChromeDriver做端到端页面测试，其前置条件在文件头有明确说明：

• 需要安装chromedriver（Ubuntu 上为sudo apt install chromium-chromedriver），且要求 Chrome 与 ChromeDriver 的主版本号一致；
• 测试中定义了一组SCREENSHOT_RESOLUTIONS，覆盖 PC（640×480 到 1920×1200）与手机（iPhone 8/8 Plus/XS/11 Pro/15/16 Pro Max、Pixel 7）等多种分辨率，用于响应式布局断言；
• 首页测试访问http://localhost:61234（配合 conftest 的glances_webserverfixture 使用）。

注意：test-webui需要真实浏览器环境，CI 或无头服务器上需确保 chromedriver 可用；否则相关用例会被 skip。

3.5 内存泄漏测试（tests/test_memoryleak.py）

tests/test_memoryleak.py 用 Python 标准库tracemalloc做内存增长检测：

• 先跑 3 轮迭代"预热"填充内存，再对后续 10 轮迭代取快照做snapshot_begin/snapshot_end对比；
• 按文件名聚合 diff 后计算每轮迭代的平均内存增长，断言必须小于 15000 字节，否则判定为内存泄漏并输出泄漏量。

该测试需要关闭历史记录（使用glances_stats_no_historyfixture），说明历史数据保留是 Glances 内存占用的主要来源之一。

3.6 导出集成测试（tests/test_export_*.sh）

以 tests/test_export_csv.sh 为例，导出类测试是真实端到端验证：

.venv/bin/python -m glances --export csv --export-csv-file /tmp/glances.csv --stop-after 10 --quiet .venv/bin/python ./tests-data/tools/csvcheck.py -i /tmp/glances.csv -l 9

流程为：启动 Glances 导出 10 轮数据到/tmp/glances.csv（约 20 秒），再用 tests-data/tools/csvcheck.py 校验文件至少有 9 行有效数据。InfluxDB、NATS、ClickHouse、TimescaleDB 等脚本逻辑类似，但目标换成对应数据库/消息系统，因此make test-exports需要 Docker 环境来拉起这些服务。

四、按目录精准定位单个插件测试

当变更仅涉及某个插件时，不必跑全部test_plugin_*。从 tests 目录可以看到每个插件都有独立测试文件：CPU、内存、磁盘、网络、GPU、NPU、容器（Docker/LXD）、虚拟机（virsh）、WiFi、SMART、传感器等。例如只改动了 NPU 插件，直接运行：

.venv-uv/bin/uv run pytest tests/test_plugin_npu.py

只跑某一个用例（文档中的示例语法同样适用）：

.venv-uv/bin/uv run pytest tests/test_core.py::TestGlances::test_000_update

pytest 的::定位语法可以精确到类甚至单个测试方法，配合-k、-x、--tb=short等参数，能极大缩短"改代码 → 验证"的反馈回路。这与文档第 3 步"用户指定目标则直接使用"的原则一致：先精准，后宽泛。

五、多版本 Python 兼容性验证（tox）

除 Makefile 之外，仓库还通过 tox.ini 提供多版本矩阵测试：

• envlist覆盖py39～py313五个 Python 版本；
• 每个测试环境安装psutil、orjson、fastapi、uvicorn、jinja2、pytest等核心依赖；
• 默认命令为python -m pytest tests/test_core.py，即 tox 环境下的"核心测试"回归。

如果你的变更涉及跨版本兼容性（例如datetime.UTC这类有版本差异的 API，参见 tests/test_core.py 中的兼容处理），建议在本地安装 tox 后运行tox验证多个 Python 版本。

六、测试失败的排查思路

文档第 5 步要求"分析输出并建议修复"。结合仓库实际情况，常见的失败原因与对策如下：

1. 环境未就绪：报错找不到.venv-uv/或缺少 pytest/selenium 等包 → 先执行make venv-dev（或make venv+ 安装 dev 依赖）。
2. 端口被占用：REST/WebUI 测试启动的 Web 服务器端口（61234）被残留进程占用 → 杀掉旧 Glances 进程后重跑（conftest 会主动 fail 并给出提示）。
3. WebUI 用例 skip 或失败：Chrome 与 ChromeDriver 版本不匹配 → 对齐两者主版本号。
4. 插件测试与平台相关：部分插件（GPU、NPU、传感器、ZFS）依赖具体硬件或系统环境，在本机不可用时会 skip；若需验证请参考 tests-data 中提供的虚拟文件系统数据（例如tests-data/plugins/npu/、tests-data/plugins/gpu/）。
5. 内存泄漏断言失败：test_memoryleak报告单轮迭代内存增长 ≥ 15000 字节 → 结合tracemalloc输出的文件名聚合结果，定位增长集中在哪个模块。

定位到具体模块后，再回到第一节的映射表，只重跑对应套件，形成高效的测试闭环。

七、小结

Glances 的测试体系遵循"按变更范围选择套件"的工程实践：核心逻辑由tests/test_core.py与共享 fixtures 守护，插件按目录独立成测，REST/WebUI/XML-RPC 分别验证不同接入层，导出器则通过真实外部服务做端到端集成验证（tests 目录中 30+ 个测试文件一一对应）。掌握 .claude/skills/test.md 定义的这套工作流——git diff --name-only→ 映射套件 →make test-*→ 分析修复——就能在改动 Glances 时用最小的测试成本获得最大置信度。

【免费下载链接】glancesGlances an Eye on your system. A top/htop alternative for GNU/Linux, BSD, macOS and Windows operating systems.项目地址: https://gitcode.com/gh_mirrors/gl/glances