直接用 assert 比较 OpenCV 图像会失败，因 img1 == img2 触发布尔数组广播异常，且浮点误差导致 np.array_equal() 易误判；应使用 np.allclose() 或 cv2.norm() 容差比较，并统一通道顺序、规范基准图管理与断言封装。
为什么直接用 assert 比较 OpenCV 图像会失败
OpenCV 读取的图像是 numpy.ndarray，直接用 assert img1 == img2 会触发布尔数组广播异常，报错 ValueError: The truth value of an array with more than one element is ambiguous。更隐蔽的问题是浮点计算误差（比如缩放、滤波后像素值有微小偏差），哪怕视觉上完全一致，np.array_equal() 也可能返回 False。
- 必须用容差比较：优先用
np.allclose()（支持atol/rtol）或cv2.norm()计算差异范数 - 注意图像通道顺序：
cv2.imread()默认 BGR，而测试基准图若来自 PIL 或 matplotlib 保存，可能是 RGB，需统一转换 - 避免只比 shape：
img1.shape == img2.shape成立不代表内容一致
如何组织测试数据与基准图像
回归测试的核心是「可复现的输入」和「可信的输出快照」。不要把基准图硬编码进测试文件，也不要用相对路径拼接（如 ../data/ref_blur.jpg），容易因工作目录变化失效。
- 用
pytest的testdirfixture 或显式定义TEST_DATA_DIR = Path(__file__).parent / "data" - 基准图命名带算法+参数标识，例如
blur_gaussian_k5_s1.0.jpg，避免output.jpg这类模糊名称 - 首次运行时允许生成基准图（加
--generate-baseline参数），但需人工校验后再提交到版本库 - Git 中禁用 PNG/JPEG 自动换行（
*.{png,jpg,jpeg} binary），防止 diff 失效
写一个稳定可复用的图像断言函数
把图像比对逻辑封装成工具函数，比每次写 np.allclose(img1, img2, atol=1.0) 更可靠，也方便后续统一调整容差策略。
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
def assert_images_similar(
img_actual,
img_expected,
max_norm=10.0, # L2 范数阈值，越小越严格
dtype_tolerance=True,
):
if dtype_tolerance and img_actual.dtype != img_expected.dtype:
img_expected = img_expected.astype(img_actual.dtype)
norm = cv2.norm(img_actual, img_expected, cv2.NORM_L2)
assert norm <= max_norm, f"Image difference norm {norm:.2f} > {max_norm}"
-
max_norm=10.0对 uint8 图像较宽松（全黑→全白最大为 255×√(H×W)），实际常用1.0~5.0 - 不依赖
np.allclose是因为 OpenCV 输出常为uint8，而浮点误差在整型上无意义；cv2.norm更贴近视觉差异 - 测试前确保两图尺寸、通道数、dtype 一致，否则
cv2.norm报错cv2.error: OpenCV(4.x): ... sizes must be equal
pytest 参数化测试不同图像与参数组合
图像算法往往需验证多组输入（不同噪声水平、不同 kernel size），用 @pytest.mark.parametrize 避免重复代码，同时让每个 case 独立失败。
立即学习“Python免费学习笔记（深入）”；
@pytest.mark.parametrize(
"input_name,ksize,sigma,ref_name",
[
("lena_noisy.jpg", 5, 1.0, "lena_denoised_k5_s1.jpg"),
("lena_noisy.jpg", 7, 1.5, "lena_denoised_k7_s15.jpg"),
],
)
def test_gaussian_denoise(input_name, ksize, sigma, ref_name):
img_in = cv2.imread(str(TEST_DATA_DIR / input_name))
img_out = gaussian_denoise(img_in, ksize=ksize, sigma=sigma)
img_ref = cv2.imread(str(TEST_DATA_DIR / ref_name))
assert_images_similar(img_out, img_ref, max_norm=3.0)
- 每个参数组合生成独立测试项，失败时明确提示是哪组参数出问题
- 避免在测试中调用耗时操作（如实时摄像头采集），所有输入必须是静态文件
- 如果算法含随机性（如泊松噪声模拟），务必在测试前设固定
np.random.seed(42)或使用rng = np.random.default_rng(42)
测试里最易被跳过的其实是图像预处理一致性——比如忘了把输入图转成 float32 再送入自定义卷积核，或者基准图是 JPEG 压缩过的而测试图是无损 PNG，这种差异会掩盖算法本身的问题。
