pytest 在本地运行一切正常，但提交到 Jenkins 后大量测试用例被跳过，是持续集成中常见的环境问题。这种现象一般不会抛出错误，因此容易被忽略，导致流水线虽然显示通过，实际并未覆盖关键逻辑。要彻底解决，需要从 pytest 的跳过机制、Jenkins 执行环境以及项目配置三个层面逐一排查。
一、理解 pytest 的跳过机制
pytest 提供了多种跳过测试的方式，最常见的是装饰器 @pytest.mark.skip 与 @pytest.mark.skipif。前者是无条件跳过，后者根据表达式结果决定是否跳过。很多项目会借助 skipif 来屏蔽在不具备某些条件的环境中无法运行的用例，例如缺少环境变量、操作系统不匹配或依赖服务不可达。
当本地与 Jenkins 的判断条件不一致时，skipif 中的表达式就会得出不同结果。比如下面这段代码，在本地设置了环境变量 CI=false，而 Jenkins 默认未设置该变量或设置为 true，就会导致用例在流水线中被跳过：
import pytest
import os
# 仅当未运行在 CI 环境时才执行
@pytest.mark.skipif(
os.environ.get("CI") == "true",
reason="CI 环境无外部数据库，跳过依赖测试"
)
def test_connect_db():
# 模拟数据库连接测试
assert os.environ.get("DB_HOST") is not None
除了装饰器，pytest 还支持在收集阶段通过 pytest.skip 函数动态跳过，或在 conftest.py 中统一注册跳过逻辑。这些代码在本地可能因条件不满足而未触发，但在 Jenkins 节点上触发了，就表现为“本地正常、远端全跳”。
二、Jenkins 环境与本地的主要差异
Jenkins 通常以无界面、非登录 shell 的方式启动构建节点，这与开发者本地开着终端的环境差别明显。首先，环境变量集合不同：本地 shell 的 profile 中导出的变量，Jenkins 进程往往读不到。其次，Python 解释器与依赖包版本可能存在细微差异，某些包在旧版本上触发 skipif 中的兼容性判断。
另一个容易被忽视的点是工作目录与文件路径。本地运行 pytest 时一般在项目根目录，而 Jenkins 可能因多分支流水线或自定义 workspace 导致相对路径错位，依赖的配置文件未加载，进而让相关的 skip 条件生效。此外，时区、语言区域（LANG/LC_ALL）也会影响依赖系统时间的测试。
| 差异项 | 本地常见情况 | Jenkins 常见情况 |
|---|---|---|
| 环境变量 | 完整加载用户 profile | 仅基础变量，需手动注入 |
| 执行用户 | 开发者本人 | jenkins 或 agent 专用账号 |
| 工作目录 | 项目根目录 | workspace 子路径 |
| Python 依赖 | 虚拟环境可控 | 节点全局或容器镜像固定 |
三、定位跳过的根本原因
第一步应当查看 Jenkins 构建日志中 pytest 的输出。pytest 在跳过用例时会打印 reason 字段，例如 SKIPPED [1] test_demo.py:10: CI 环境无外部数据库。通过这个原因可以快速反推是哪条 skipif 生效。若日志被截断，可在 Jenkinsfile 中临时加上 -rs 参数强制输出跳过详情。
第二步是在本地模拟 Jenkins 环境。可以在终端执行 env -i pytest -rs 清空环境变量后运行，观察是否复现跳过；也可以显式设置 CI=true 再跑一次。通过对比本地与 Jenkins 的 pytest --collect-only -rs 收集的用例列表，就能确认是否是收集阶段就因条件不同而过滤了用例。
# 本地模拟 Jenkins 的干净环境 env -i PATH=$PATH CI=true python -m pytest --collect-only -rs # 对比正常本地环境 python -m pytest --collect-only -rs
如果发现在干净环境下用例也被跳过，说明问题出在环境假设上；若干净环境下正常，则差异可能来自 Jenkins 节点特有的配置文件或网络限制，此时需要检查节点上的 pytest.ini、tox.ini 或 conftest.py 是否被覆盖。
四、常见场景与对应修复方案
场景一是错误使用 skipif 判断 CI。有些团队会把所有耗时测试都加上 skipif CI，但 Jenkins 正是需要跑这些测试的地方。正确做法是区分“不需要跑”和“没法跑”，仅对真正依赖本地资源的用例跳过，并通过 Jenkins 参数化构建来控制执行范围。
场景二是配置文件未随代码打包。例如本地有 config/local.py，而 Jenkins 拉取代码后该文件因 gitignore 被排除，导致 import 失败并被 pytest 的收集钩子跳过。修复方式是把必要的测试配置纳入版本库，或在 Jenkins 构建步骤中用脚本生成配置。
// Jenkinsfile 片段：构建前写入测试配置
stage('Prepare Config') {
steps {
writeFile file: 'config/local.py', text: """
DB_HOST = '127.0.0.1'
DB_PORT = 5432
"""
sh 'python -m pytest -rs'
}
}
场景三是节点依赖版本不一致。可在 Jenkins 中使用 Python 虚拟环境或 Docker 镜像锁定版本，保证与本地开发环境一致。同时在仓库根目录提供 requirements.txt 或 poetry.lock，让流水线和本地都基于同一份依赖定义安装。
五、在流水线中稳定执行 pytest 的建议
建议在 Jenkinsfile 中显式声明环境变量，而不是依赖节点全局配置。这样每次构建环境都可预期，不会出现“某台机器突然多了一个变量导致跳过”的情况。同时，将 pytest 命令统一为带有 -ra 或 -rs 的形式，确保跳过与未通过的原因都暴露在日志中。
另外，可以为 Jenkins 单独建立一套 pytest 配置，比如 pytest_ci.ini，在其中禁用某些仅本地有用的 marker，并强制所有 skipif 必须给出可读 reason。配合 pytest --strict-markers 还能防止拼写错误的 marker 被静默忽略，从而减少“看似跳过、实则配置错”的隐患。
# pytest_ci.ini 示例
[pytest]
addopts = -rs -ra --strict-markers
markers =
local_only: 仅本地执行的用例
integration: 集成测试
最后，定期在本地用容器模拟 Jenkins 镜像运行一次完整测试，是防止环境漂移的有效手段。当本地与远端执行结果长期一致，pytest 在 Jenkins 中无故跳过的问题也就从根本上消失了。