Python unittest.subTest 怎样保留多个失败

在 unittest 里用一个 for 循环测试多组输入时，普通写法遇到第一个断言失败就会退出当前测试方法，后面的样例根本没有机会执行。要在一次测试运行中保留多个失败，应该把每一轮放进 with self.subTest(...) 中，并给它传入能识别样例的参数。

官方地址：https://docs.python.org/3/library/unittest.html

subTest 不会把一组输入拆成多个独立的测试方法，但会让每个子测试失败被单独记录；默认情况下，某一轮失败后循环仍可继续，最终报告会列出失败样例及其参数。

普通循环为什么只看到一个失败

先看最容易误解的写法：把多组输入放进一个测试方法，然后连续调用断言。assertEqual 抛出断言异常后，当前方法立即结束，所以第二个和第三个样例没有执行。

import unittest


class TestNormalize(unittest.TestCase):
    def normalize(self, value):
        # 示例函数只去掉首尾空白，便于集中观察测试报告。
        return value.strip()

    def test_examples_without_subtest(self):
        cases = [
            ("  go  ", "go"),
            ("\tpython", "python"),
            ("java  ", "java"),
        ]
        for raw, expected in cases:
            # 第一个错误会抛出异常，循环不会自动跳到下一项。
            self.assertEqual(self.normalize(raw), expected)


if __name__ == "__main__":
    # -v 只提高输出细节，不会改变失败控制语义。
    unittest.main(verbosity=2)

如果第一个失败发生在第二个样例，报告通常只显示这一个失败，读者需要修复、重跑，再等待下一个失败出现。对于输入表较长的回归测试，这种反馈周期很慢。

用 subTest 给每一轮建立边界

subTest 返回一个上下文管理器。把“处理一个样例”和“断言这个样例”放在上下文中，unittest 就能在子测试结束时把当前参数交给结果对象；失败不会让外层测试方法自动停止，循环可以继续。

import unittest


class TestNormalize(unittest.TestCase):
    def normalize(self, value):
        # 真实项目中这里可以替换成待测的清洗、解析或转换函数。
        return value.strip()

    def test_examples_with_subtest(self):
        cases = [
            {"name": "英文", "raw": "  go  ", "expected": "go"},
            {"name": "制表符", "raw": "\tpython", "expected": "python"},
            {"name": "尾部空格", "raw": "java  ", "expected": "java"},
        ]

        for case in cases:
            # 每轮都有自己的标识；失败报告会带出 name、raw 等参数。
            with self.subTest(name=case["name"], raw=case["raw"]):
                # 断言失败只标记当前子测试，外层循环仍可继续。
                self.assertEqual(
                    self.normalize(case["raw"]),
                    case["expected"],
                )


if __name__ == "__main__":
    # 不使用 -f，否则结果对象会按 failfast 规则提前停止。
    unittest.main(verbosity=2)

这里的 name 是给人看的稳定标签，raw 用来帮助定位输入。参数不必全部塞进去：敏感数据、超长文本或不可序列化对象应改成安全的短标识，例如记录样例编号或业务键。

如何从报告中读出多个失败

运行测试文件时使用 -v 可以看到测试方法级别的名称；子测试失败的详细参数会出现在失败列表中。最终的 Ran 数字仍按测试方法统计，不要把它误读成子测试数量。

# 在包含 test_normalize.py 的目录运行
python -m unittest -v test_normalize.py

# 只运行这个测试类，缩短定位时间
python -m unittest -v test_normalize.TestNormalize

当多个样例失败时，报告会分别列出每个子测试的上下文，例如 [name='英文'] 和 [name='尾部空格']。这些标签不是新的测试方法名，而是 subTest 传给结果收集器的描述信息。

如果只想在代码里收集结果，也可以自定义 TestResult.addSubTest。官方文档说明，子测试成功时 outcome 为 None，失败时是异常信息元组；默认实现会把失败记录为普通失败，因此通常不需要自定义结果类。

subTest 不会替你吞掉所有异常

subTest 适合处理断言失败，但不能把所有异常都当成可继续的样例失败。下面几个边界要分清。

尤其不要在 subTest 外层用一个宽泛的 try/except Exception 把错误改写成“失败样例”。这样会掩盖程序错误，也会让 traceback 失去定位价值。只有业务上明确预期的异常，才用 assertRaises 或相关断言表达。

把数据驱动测试写成可维护的形式

当样例超过几组时，建议把输入和期望结果放在结构清晰的数据表中，测试方法只负责遍历和断言。下面同时展示成功、失败和预期异常三类边界；实际项目应让每个样例的标签保持稳定。

import unittest


class TestParsePort(unittest.TestCase):
    def parse_port(self, text):
        # 把端口文本转换为整数，并拒绝空值和范围外输入。
        if not text.strip():
            raise ValueError("port is empty")
        port = int(text)
        if not 1 

这里将正常输入和非法输入分成两张表，是为了让断言意图一眼可见。若要进一步减少重复，也可以把预期结果、预期异常和样例标签统一成数据结构，但不要为了抽象而让失败报告失去可读性。

常见误区速查

结论很简单：循环负责提供多组输入，subTest 负责给每一轮增加报告边界，断言仍然负责表达预期。想一次看到所有失败时，确保每轮都有稳定标识，并且不要启用 failfast；这样一次运行就能得到更完整的修复清单。

相关问题

• subTest 会增加 unittest 的测试数量吗？不会把一轮变成独立测试方法，Ran 通常仍按外层测试方法统计；但失败列表会分别记录子测试。
• 为什么用了 subTest 还是只看到一个失败？先检查是否启用了 -f，以及失败是否发生在上下文外的 setUp、资源初始化或循环本身。
• 能否嵌套 subTest？可以。官方文档允许任意数量的子测试并支持嵌套，但标签应保持短小，否则报告会难以阅读。