pytest-tui需单独安装且依赖兼容终端，安装后通过pytest --help验证--tui选项，windows用户建议重启终端或用python -m pytest --tui，ci环境禁用该参数。
pytest-tui 装了但命令行没反应？检查是否装对了包
pytest-tui 是一个独立终端 UI 插件，不是 pytest 自带功能。很多人用 pip install pytest 后直接跑 pytest --tui，报错 unrecognized arguments: --tui —— 这说明插件根本没装。
- 确保执行的是：
pip install pytest-tui（注意是pytest-tui，不是pytest-ui或pytest-tui-plugin） - 安装后验证：运行
pytest --help | grep tui，能看到--tui选项才表示加载成功 - Windows 用户如果用 PowerShell，可能因缓存没刷新，建议关掉终端重开，或运行
python -m pytest --tui绕过 shell 别名干扰
运行时黑屏 / 卡住 / 一闪而过？终端兼容性是主因
pytest-tui 依赖 rich 和底层终端控制能力，对终端环境敏感。常见现象是启动后空白、无响应、或测试一结束 UI 就消失。
- 必须使用支持 ANSI 控制序列的终端：Windows Terminal、iTerm2、GNOME Terminal 可以；旧版 Windows CMD、某些 IDE 内置终端（如 PyCharm 默认 Terminal）默认不支持，会降级为纯文本输出甚至崩溃
- 避免在 IDE 的“Run”按钮里直接点运行 —— 它通常不分配完整 TTY。改用 IDE 的“Terminal”标签页手动输
pytest --tui - 如果用 VS Code，确保设置了
"terminal.integrated.env.linux": {"TERM": "xterm-256color"}（macOS/WSL 类似），否则rich可能禁用渲染
为什么 test 名字截断、进度条不动、统计数字不准？别忽略 pytest 的默认行为
pytest-tui 不改变 pytest 的执行逻辑，只是套了一层 UI。它显示的内容完全取决于 pytest 实际跑了多少、怎么收集、何时报告。
- 默认情况下，pytest 会提前收集所有 test（
collected 42 items），但--tui的进度条只反映「已执行完」的 case 数，不是「已开始」——所以前几秒可能静止，尤其项目大、conftest.py 重时更明显 - 测试函数名过长会被
rich自动截断，无法拉宽显示；想看清，加-v参数：pytest --tui -v - 如果用了
--tb=short或--disable-warnings，UI 中错误堆栈和警告仍会照常显示，但格式可能被压缩；真要调试，临时去掉--tui更直接
CI/CD 里跑 --tui 报错或失败？它本来就不该上服务器
pytest-tui 是交互式终端工具，依赖 stdin/stdout/tty 状态。CI 环境（GitHub Actions、GitLab CI、Jenkins）基本没有真实 TTY，强行启用只会触发异常退出或静默失败。
- CI 配置中务必移除
--tui，保留--verbose或--tb=short即可 - 本地开发想持续看进度，可以搭配
--looponfail：pytest --tui --looponfail，但它只监听文件变化，不解决 CI 场景 - 没有“轻量版 tui”可选——想在 CI 展示进度，得换方案：比如用
pytest-json-report+ Web UI，或者自己写个 stdout 解析脚本
实际用起来最常卡在终端兼容性和安装路径上。一旦 pytest --help 里看见 --tui，且终端不是 IDE 自带那种阉割版，剩下的就是耐心等第一个 test 跑完——UI 不会提前渲染，它只画已发生的事。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
