ipytest 是专为在 Jupyter Notebook 中运行 pytest 设计的适配工具，解决直接调用 pytest 导致的 ImportError、SystemExit、路径错误等问题，通过内存模块注入和 pytest Python API 调用实现兼容。
直接运行 pytest 脚本在 Jupyter Notebook 中默认失败——因为 Notebook 的执行模型和 pytest 的 CLI 入口不兼容，ipytest 就是专为解决这个问题而生的胶水工具。
为什么不能直接用 pytest.main() 或命令行 !pytest
常见错误现象包括：
-
ImportError: cannot import name 'main' from 'pytest'（新版 pytest 已移除pytest.main） -
SystemExit: 0或静默退出，单元测试看似“跑完”但没输出结果 -
!pytest test_file.py在 notebook 单元中执行后卡住、无响应，或报错FileNotFoundError（路径解析失败）
根本原因：pytest 默认依赖 sys.argv 解析参数，并期望在独立进程里初始化测试收集器；而 notebook 是交互式、单进程、模块级导入环境，直接调用会绕过其生命周期管理。
安装与基础用法：ipytest 是什么
ipytest 不是 pytest 替代品，而是把 pytest 嵌入 notebook 的适配层。它自动：
- 将当前 notebook 单元中的
def test_*函数临时写入内存模块 - 调用 pytest 的 Python API（非 CLI）执行，避免
sys.argv干扰 - 捕获并内联显示 pytest 的标准输出/错误，支持
-v、-x等常用参数
安装只需一行（确保在 notebook 当前 kernel 对应的环境中执行）：
!pip install ipytest
使用示例：
Python 3.14.3
微软官方的 Python 扩展，是 VS Code 安装量最高的扩展（209M+）。集成 IntelliSense（通过 Pylance）、调试（通过 Python Debugger）、代码检查、格式化、重构和单元测试等功能。支持 Jupyter Notebook、虚拟环境管理和多 Python 版本切换。
import ipytest ipytest.autoconfig() # 自动配置，推荐放在 notebook 开头def test_add(): assert 1 + 1 == 2
def test_fail(): assert False, "故意失败"
ipytest.run() # 执行当前模块中所有 test_* 函数
ipytest.run() 的关键参数与陷阱
多数问题出在参数误用或路径误解上：
-
ipytest.run("-v")✅ 有效；但ipytest.run("test_module.py")❌ 无效——它不接受文件路径，只运行当前上下文定义的函数 - 若测试依赖外部模块（如
from mylib import helper），需确保该模块已导入或已重新加载（import importlib; importlib.reload(mylib)），否则报NameError - 默认只收集当前单元中定义的
test_*函数；跨单元定义需显式传入modules=[...]，但更推荐把测试集中在一个单元或用%run导入测试文件 - 不支持
--pdb，调试需改用assert+print或在函数内加breakpoint()（注意 notebook 对breakpoint的支持依赖 kernel 配置）
测试外部 .py 文件时的正确姿势
想运行磁盘上的 test_math.py？别用 !pytest test_math.py（容易因工作目录错乱失败），改用：
import ipytest # 确保当前工作目录包含 test_math.py import os os.getcwd() # 检查路径方法一：用 ipytest 加载并运行（推荐）
ipytest.run("test_math.py", overwrite=True) # overwrite=True 防止缓存旧版本
方法二：直接调用 pytest API（更底层，需手动处理路径）
import pytest pytest.main(["-v", "test_math.py"])
⚠️ 注意：ipytest.run("test_math.py") 仍依赖当前 kernel 能 import 到该文件——如果 test_math.py 在子目录，需先 sys.path.append("subdir")。
真正容易被忽略的是：每次修改测试函数后，必须重新运行 ipytest.run() 单元；而如果你在测试中动态修改了被测模块（比如 patch 或 reload），要格外注意 Python 模块缓存机制——ipytest 不会自动帮你 reload，得手动处理。
