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，得手动处理。