Python项目集成GitHub Actions运行pytest指南

本文深入解析了在GitHub Actions中运行pytest时高频出现的四大痛点：ModuleNotFoundError环境配置问题、CI触发范围失控、失败日志不清晰、以及本地通过但CI超时或资源溢出，并给出精准、可落地的解决方案——从用python -m pytest和pip install -e .规避PATH与包发现陷阱，到通过on: [push, pull_request]配合branches: [main]实现高效触发，再到添加--tb=short和--timeout=30提升诊断效率与稳定性，最后直击runner资源限制本质，推荐禁用多进程、内存数据库和轻量HTTP mock。每一条建议都源于真实踩坑经验，帮你告别“本地OK、线上挂”的玄学调试，真正让CI可靠、快速、可读。

GitHub Actions里跑pytest总报ModuleNotFoundError

根本原因是工作目录没切对，或者Python环境没装好依赖。默认checkout后路径在仓库根目录，但pytest如果从子目录运行、或项目结构含src/布局，就容易找不到包。

• 在.github/workflows/test.yml里加cd src或--rootdir=src参数前，先用ls -R确认实际目录结构
• 用python -m pytest代替pytest命令，避免PATH中混入本地安装的旧版本
• pip install -e .比pip install .更稳妥，尤其当setup.py或pyproject.toml里定义了packages或find:时

怎么让GitHub Actions只在push到main和PR时跑测试

不是所有分支都需要跑CI，盲目触发既慢又占额度。关键是用on字段精准控制事件和分支过滤，而不是靠脚本里判断GITHUB_REF。

• 写成on: [push, pull_request]，再补上branches: [main]——注意pull_request默认对所有分支生效，push才受branches限制
• 如果只想测PR合并前（pre-merge），去掉push，只留pull_request；如果还要覆盖main直推，必须显式列出
• 避免用on: push: branches: ['*']，通配符会匹配feature/xxx等临时分支，浪费资源

测试失败时看不到详细日志，怎么快速定位

默认pytest输出被折叠，失败时只显示摘要，根本看不出是哪个断言崩了、哪个fixture没初始化。

• 加--tb=short或--tb=auto参数，避免长traceback刷屏，又保留关键上下文
• 用python -m pytest -v --tb=short tests/test_api.py::test_login这种粒度调试，比全量跑快得多
• 在workflow里加continue-on-error: true配合run: python -m pytest ... || echo "Test failed, check above"，防止一步失败就中断，错过后续日志

为什么本地能过、CI里总超时或内存溢出

GitHub Actions的ubuntu-latest runner是4核2GB内存，比你笔记本差得多。耗时操作（比如启动Docker、读大文件、mock大量HTTP）很容易踩线。

• 禁用pytest的--numprocesses（即-n），CI里多进程反而抢资源，单进程更稳
• 把time.sleep(0.1)换成pytest-timeout插件+--timeout=30，主动掐断卡死用例
• 数据库测试改用sqlite:///:memory:，别连真实PostgreSQL容器；HTTP mock优先用responses或httpx_mock，别启真实server

CI配置最麻烦的从来不是YAML语法，而是环境差异带来的“本地OK、线上挂”——路径、依赖、资源、时间精度，每一处都得对着runner日志一行行抠。

到这里，我们也就讲完了《Python项目集成GitHub Actions运行pytest指南》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！