 讲透测试执行器)
第一次在测试脚本里看到runner = unittest.TextTestRunner()这行赋值时，我甚至把变量名看成了unner——不是看错，而是很多教程代码里随手写的变量名确实容易晃眼。它其实是runner，一个真正决定 unittest 结果“怎么被记录、怎么被打印”的对象。很多初学者以为这行只是把某个类实例化一下，甚至以为有了它就能自动跑测试，结果运行完发现毫无输出，转头就把它删掉。事实上，TextTestRunner是 unittest 框架里最容易被低估的执行入口：它负责接收一套TestSuite，逐条调度测试方法，把成功、失败、错误、跳过全部统计成TestResult，最后按 verbosity 的设定输出到终端。这篇文章我会从构造函数到源码流程，把这行代码背后的事情一次讲透，适合刚开始用 unittest 写用例、也想理解测试框架该如何扩展的人。
1. 这行赋值到底创建了什么：从构造函数看 TextTestRunner
1.1 默认参数里藏着的最关键选择
unittest.TextTestRunner()并不是一个无参类。它的构造函数签名在 Python 3.11 及以前大致长这样：
TextTestRunner(stream=None, descriptions=True, verbosity=1, failfast=False, buffer=False, resultclass=None, warnings=None, *, tb_locals=False)在 Python 3.12 之后又增加了durations=None。也就是说，你写runner = unittest.TextTestRunner()时，真正的调用其实是：
runner = unittest.TextTestRunner( stream=None, descriptions=True, verbosity=1, failfast=False, buffer=False, resultclass=None, warnings=None, tb_locals=False, )这里最值得注意的不是verbosity，而是stream=None。很多人以为 TextTestRunner 的输出会走sys.stdout，于是用重定向 stdout 的方式去抓测试日志，结果抓到个空。源码里的逻辑是：
if stream is None: stream = sys.stderr self.stream = stream也就是说，默认输出流是 stderr，而不是 stdout。终端里看起来没区别，因为两者都打到控制台，但一旦做输出捕获、管道重定向或者 CI 日志分类，这个细节就会立刻坑人。
1.2 为什么说 runner 只是“执行外壳”而不是“发现器”
TextTestRunner 本身不会去扫描测试文件，不会自动发现test_*.py，也不知道你的测试类长什么样。它的输入必须是一套已经组装好的TestSuite，也就是一个“按顺序排列的测试集合”。发现测试、加载测试是TestLoader和discover的活，TextTestRunner 只干三件事：
- 根据传入参数创建一个结果对象
result； - 执行
suite.run(result)，让测试方法在内部依次运行； - 测试跑完后由结果对象把错误列表、耗时、汇总统计打印出来。
所以你在很多开源项目里看到的模式是：
suite = unittest.TestLoader().loadTestsFromTestCase(MyTestCase) runner = unittest.TextTestRunner(verbosity=2) result = runner.run(suite)先有 suite，再有 runner，最后调run()。这一步少掉任何一个，测试都不会“自动跑起来”。
了解了这层关系之后，你就能理解为什么unittest.main()看起来那么简单：它内部其实就是用默认的TextTestRunner去跑。main()省事，但它把加载、执行、退出码全部封装成了一个黑盒；而你手动创建 runner，换来的就是对执行过程的完全掌控。
2. 最小可运行示例，带你看完一整轮测试生命周期
2.1 一段能直接跑的代码
先把最简单的情况写出来。假设有一个求和函数和一个测试类：
import unittest def add(a, b): return a + b class TestMath(unittest.TestCase): def test_add_positive(self): self.assertEqual(add(1, 2), 3) def test_add_zero(self): self.assertEqual(add(0, 0), 0) if __name__ == "__main__": suite = unittest.TestLoader().loadTestsFromTestCase(TestMath) runner = unittest.TextTestRunner(verbosity=2) result = runner.run(suite)运行后终端会输出类似这样的内容：
test_add_positive (__main__.TestMath) ... ok test_add_zero (__main__.TestMath) ... ok ---------------------------------------------------------------------- Ran 2 tests in 0.001s OK注意第一行的测试描述test_add_positive (__main__.TestMath)，这是TextTestResult.getDescription()生成的；后面的ok表示成功。如果某个测试断言失败，你会看到FAIL；如果是测试代码自身抛异常，则是ERROR。
runner.run(suite)返回的result对象不是空摆设，它上面挂着几乎你想知道的全部统计信息：
result.testsRun # 实际跑了多少条用例 result.wasSuccessful() # 是否全部通过 result.failures # 失败用例列表 result.errors # 出错用例列表 result.skipped # 跳过用例列表 result.expectedFailures # 预期失败但确实失败 result.unexpectedSuccesses # 预期失败结果却成功了顺手在脚本末尾加一句print(result.testsRun, result.wasSuccessful())，你就能看到这些属性怎么用。
2.2 runner.run(suite) 内部发生了什么
很多人把run()理解成“执行测试方法”的单一入口，其实这一层有完整的调度链路。简化后的源码逻辑大致是：
def run(self, test): result = self._makeResult() result.failfast = self.failfast result.buffer = self.buffer result.tb_locals = self.tb_locals startTestRun = getattr(result, 'startTestRun', None) if startTestRun is not None: startTestRun() try: test(result) finally: stopTestRun = getattr(result, 'stopTestRun', None) if stopTestRun is not None: stopTestRun() result.printErrors() self.stream.writeln(f"Ran {result.testsRun} tests ...") # 根据 wasSuccessful() 打印 OK 或 FAILED return result_makeResult()并不是一个复杂工厂，它把 runner 的三个构造参数透传给了结果类：
def _makeResult(self): return self.resultclass(self.stream, self.descriptions, self.verbosity)重点在test(result)这一行。test是TestSuite对象，TestSuite.__call__内部会遍历自己持有的测试项，逐个执行。如果某个测试项本身还是TestSuite，就递归往下；如果是一个TestCase，就调用它的__call__(self, result)，最终走到TestCase.run(result)：
# 大致流程 result.startTest(test) try: test.setUp() test.testMethod() test.tearDown() except AssertionError as e: result.addFailure(test, sys.exc_info()) except Exception as e: result.addError(test, sys.exc_info()) else: result.addSuccess(test) finally: result.stopTest(test)所以“跑一个测试”不只是执行test_xxx这个方法，还包含setUp、测试方法本身、tearDown三件事，以及异常到addFailure/addError的分发。这也是为什么 unittest 底层有“测试协议”的说法：任何对象，只要实现了run(result)或__call__(self, result)，理论上都可以被TestSuite接收并执行。TextTestRunner 本身不在乎你传进来的是从 loader 拿来的 suite，还是手工拼的TestSuite。
2.3 TextTestResult：统计、格式化、打印三位一体
默认情况下，_makeResult()创建的是TextTestResult。这个类继承了基础的TestResult，额外承担了三件事。
第一是统计。TestResult里有testsRun、failures、errors、skipped等属性，每次addSuccess、addFailure、addError时都会更新。wasSuccessful()挂在基类上，逻辑很简单：只有在没有失败、没有错误、没有非预期成功时才返回 True。
第二是格式化。当某个测试失败或报错时，addFailure和addError都会调用_exc_info_to_string()，把当前的(type, value, traceback)转成一段带Traceback (most recent call last):的字符串，然后存进failures或errors列表。注意这里存的已经是格式化后的文本，不是异常对象，所以你想在自定义结果类里做“失败重试”或者“提取异常类型”，得在写入前的钩子里处理，而不是事后去 parse 字符串。
第三是打印。printErrors()会把errors和failures里积累的内容用分隔线划开逐条输出；startTest()和addSuccess()会根据 verbosity 决定要不要打印测试名、ok、点号等等。这些打印全部写到 runner 的 stream 上，所以 stream 换成io.StringIO()就能把测试输出“装”进内存。
这一段搞清楚后，你对 runner 的认知就不再停留在“能跑测试”这个层面了。下面我们来逐个拆解构造参数。
3. 构造参数逐个拆解：verbosity 之外还有多少控制项
3.1 verbosity 从 0 到 2 到底差在哪
verbosity 参数是最直观的，也是一个最容易描述清楚的东西。它有三个档位：
| verbosity | 每个测试的即时输出 | 典型场景 |
|---|---|---|
| 0 | 无任何逐用例输出 | 安静模式，只看最终汇总 |
| 1 | 一个字符：成功.，失败F，错误E，跳过s | CI 日志、默认模式 |
| 2 | 每个测试一行，显示测试名和 ok/FAIL/ERROR | 本地调试、排查问题 |
我在实际项目中见过不少误解，比如有人以为默认 verbosity=1 时每个测试会显示“点”和“F/E”是 pytest 的行为，其实 unittest 一直就是这样。区别只是 verbosity=2 时，TextTestResult.startTest会先打印self.getDescription(test)，而 addSuccess 等回调会打印ok、FAIL、ERROR；verbosity=1 时则用单字符做进度显示；verbosity=0 则连进度字符都没有，直接跑到最后输出汇总和错误详情。
有一点值得提醒：verbosity=2 下输出的测试描述并不总是“方法名”，当测试方法有 docstring 时，unittest 会把 docstring 当作 short description 显示。比如：
def test_add_positive(self): """正数相加""" self.assertEqual(add(1, 2), 3)verbosity=2 时会显示：
正数相加 (__main__.TestMath) ... ok如果不想让 docstring 掺和进测试名，可以把descriptions=False传进 runner。
3.2 stream 和 descriptions：输出去向与测试描述
stream是 TextTestRunner 最容易出价值也最容易踩坑的参数。它的要求很简单：是一个有write()方法的类文件对象，最好也实现flush()，因为测试过程会频繁写入。常见用法有几种。
第一种，捕获到内存对象：
import io import unittest class TestDemo(unittest.TestCase): def test_ok(self): self.assertEqual(1, 1) suite = unittest.TestLoader().loadTestsFromTestCase(TestDemo) stream = io.StringIO() runner = unittest.TextTestRunner(stream=stream, verbosity=2) result = runner.run(suite) print(stream.getvalue())有人可能疑惑：我都跑了runner.run(suite)，为什么控制台没看到输出？因为上面的代码把输出全写进stream了，控制台当然看不到。拿到stream.getvalue()之后，你可以把它拼进邮件通知、写进日志文件、或者作为 CI 的一个 artifact。
第二种，写入文件：
with open("test_report.txt", "w", encoding="utf-8") as f: runner = unittest.TextTestRunner(stream=f, verbosity=2) runner.run(suite)这样测试报告就落在磁盘上，不干扰终端其他日志。第三种，保留给第三方报告器，比如有人写 HTMLTestRunner 时，本质就是用一个能累积 HTML 片段的流对象替换默认 stderr。
descriptions参数则控制描述来源。默认 True 时，结果类会用test.shortDescription()作为显示描述；如果设为 False，就直接用测试方法的id()，也就是模块名.类名.方法名。这个参数在审计输出、固定报告格式的时候很有用，因为 docstring 一改，报告里的测试名就变了，不利于 diff。
3.3 failfast、buffer、warnings、tb_locals 的实战价值
failfast=True会让 runner 在遇到第一个失败或错误时立刻停止后续测试。注意，它不是“跳过”后面的用例，而是不再执行。底层逻辑是TestResult.stop()设置一个标志位，TestCase.run()在每次执行前检查这个标志。这个参数在冒烟测试和快速反馈场景下很好用，比如你在 CI 上只想确认主流程是否正常，没必要把 500 条用例全部跑完。
buffer=True是我个人很喜欢的参数。它会把每个测试执行期间的stdout和stderr输出缓存起来，如果测试通过，这些输出就不会出现在最终结果里；如果测试失败或报错，缓存的内容会被附加到错误信息里一并展示。这样能有效避免一堆print()调试日志刷屏。实现上它依赖contextlib.redirect_stdout/redirect_stderr，所以子进程或者 C 扩展直接写文件描述符的输出不在捕获范围内，这点要提前有预期。
warnings参数控制测试运行期间 Python 警告的过滤方式，可直接传'ignore'、'always'、'error'等字符串。它最终会被传给warnings.simplefilter()。比较实用的玩法是warnings='error'，把 DeprecationWarning 变成异常，强制暴露某些库的过时 API。
tb_locals=True是 Python 3.5 以后才有的 keyword-only 参数。打开后，测试失败或报错时，traceback 的最后会附带异常发生处的局部变量名和值。这是一个排查利器，尤其在 CI 上没法本机复现问题时特别有用。但要注意：局部变量可能包含密码、token 等敏感信息，打印到日志里要注意脱敏。
3.4 新版本才有的 durations 参数与兼容写法
Python 3.12 给TextTestRunner增加了durations参数。它的用法是传入一个整数，表示要展示最慢的多少个测试：
runner = unittest.TextTestRunner(verbosity=1, durations=5) result = runner.run(suite)运行结束后，stream 里会多出一段类似：
Slowest 5 tests: 0.102s test_slow_query (tests.test_db.TestDB) 0.050s test_big_file (tests.test_io.TestIO) ...这对定位性能瓶颈非常有用。但它只统计耗时超过一定阈值的测试，具体阈值和输出格式在不同小版本里可能有调整。如果你维护的代码要兼容 Python 3.11 及以下，就不能在构造参数里直接写durations=5，否则会报TypeError: __init__() got an unexpected keyword argument 'durations'。
兼容写法有两个思路。一个是用版本号判断：
import sys if sys.version_info >= (3, 12): runner = unittest.TextTestRunner(verbosity=1, durations=10) else: runner = unittest.TextTestRunner(verbosity=1)另一个是用try/except TypeError，因为参数错误只在运行时才暴露。我更推荐版本号判断，因为语义更清楚，代码审查的人一眼就看明白为什么这里要分支。
最后再说resultclass，它是所有参数里扩展性最强的。它本身不是一个“行为开关”，而是一个指向结果类对象的引用，默认是unittest.TextTestResult。你可以传入任何继承了TextTestResult的子类，从而完全接管“测试结果如何记录、如何打印”这两个环节。下一章专门展开。
4. 用 resultclass 重写结果处理逻辑：从普通文本到自定义报告
4.1 自定义结果类要重写哪些钩子
如果你只想调整输出颜色、统计维度、报告格式，不建议去改 TextTestRunner 本身，更优雅的做法是继承TextTestResult，然后通过resultclass注入。
一个结果类的生命周期里有几个关键钩子：
startTestRun()：整套 suite 开始前调用，适合做初始化、计时清零；startTest(test)：每一条用例开始前调用；addSuccess(test)：用例通过；addFailure(test, err)：断言失败；addError(test, err)：用例自身抛异常；addSkip(test, reason)：用例被跳过；addExpectedFailure(test, err)：预期失败但确实失败；addUnexpectedSuccess(test)：预期失败结果却成功；stopTest(test)：每一条用例结束后调用；stopTestRun()：整套 suite 结束后调用，适合做最终汇总、写报告。
特别注意TextTestResult.__init__(self, stream, descriptions, verbosity)这个签名是_makeResult()调用时固定的，自定义结果类若需要额外参数，可以通过 runner 子类或者实例属性传入，但不要改这个初始化签名，否则 runner 会构造失败。
一个最常见的自定义场景是给结果加颜色。比如失败时输出红色的F，成功时输出绿色的点。做法就是重写addSuccess和addFailure，在外层套 ANSI 转义码：
import unittest class ColorTextResult(unittest.TextTestResult): def addSuccess(self, test): super().addSuccess(test) if self.dots: self.stream.write('\033[32m.\033[0m') self.stream.flush() elif self.showAll: self.stream.writeln('\033[32mok\033[0m') def addFailure(self, test, err): super().addFailure(test, err) if self.dots: self.stream.write('\033[31mF\033[0m') self.stream.flush() elif self.showAll: self.stream.writeln('\033[31mFAIL\033[0m') class ColorRunner(unittest.TextTestRunner): resultclass = ColorTextResult调用方式不变：
runner = ColorRunner(verbosity=1) result = runner.run(suite)注意super().addSuccess(test)必须保留，因为基类里除了打印ok之外，还承担了testsRun += 1这类统计任务。如果不调用父类，测试数量会变成 0，最终汇总就是错误的。
4.2 一个基于 TextTestResult 的 JSON 报告器
比加颜色更实际的需求，是把测试结果整理成结构化数据，交给上层平台。这里我给一个可以改造成内部工具的精简示例：
import json import unittest class JsonResult(unittest.TextTestResult): def __init__(self, stream, descriptions, verbosity): super().__init__(stream, descriptions, verbosity) self.records = [] def addSuccess(self, test): super().addSuccess(test) self.records.append({ "name": self.getDescription(test), "status": "success", }) def addFailure(self, test, err): reason = self._exc_info_to_string(err, test) super().addFailure(test, err) self.records.append({ "name": self.getDescription(test), "status": "failure", "reason": reason, }) def addError(self, test, err): reason = self._exc_info_to_string(err, test) super().addError(test, err) self.records.append({ "name": self.getDescription(test), "status": "error", "reason": reason, }) def addSkip(self, test, reason): super().addSkip(test, reason) self.records.append({ "name": self.getDescription(test), "status": "skip", "reason": str(reason), }) class TestSample(unittest.TestCase): def test_ok(self): self.assertEqual(2 + 2, 4) suite = unittest.TestLoader().loadTestsFromTestCase(TestSample) runner = unittest.TextTestRunner(verbosity=0, resultclass=JsonResult) result = runner.run(suite) print(json.dumps(result.records, ensure_ascii=False, indent=2))有人会问：为什么我不直接在addFailure里把异常信息直接存成对象，而要调_exc_info_to_string转成字符串？因为一旦丢给 JSON，traceback 本来也只会被序列化成文本，所以先格式化没有损失。如果有更复杂的需求，比如根据异常类型分类，你可以不调用父类的 addFailure，而是先处理err[0]拿到异常类型，再构造自己的数据结构。
要注意的是：自定义结果类里如果完全绕开父类实现，必须自己维护failures、errors、testsRun等属性的一致性，否则 runner 最后打印的Ran N tests和OK/FAILED就是错的。我的习惯是永远先super()再追加自己的逻辑，除非有极其特殊的原因。
4.3 在 CI 里手动 runner 的正确退出码姿势
手动创建 runner 之后，有一个非常常见的坑：脚本跑完测试，CI 居然显示成功，哪怕测试明明失败了。原因很简单，TextTestRunner.run()只是返回一个result对象，它不会主动设置进程退出码。你需要在脚本最后自己判断：
import sys import unittest suite = unittest.defaultTestLoader.discover("tests") runner = unittest.TextTestRunner(verbosity=1) result = runner.run(suite) sys.exit(0 if result.wasSuccessful() else 1)如果不加这一行，Python 脚本正常结束就是退出码 0，CI 当然认为任务成功。很多 Jenkins 或 GitLab CI 上“假绿”的测试任务，排查到最后都是这个问题。
另外一个更隐蔽的坑是：当测试进程因为failfast=True提前停止时，testsRun可能小于预期的用例总数，但wasSuccessful()依然能正确反映“是否有失败”。CI 汇总时需要区分“全部跑完且成功”和“提前停止但当前未失败”，否则冒烟测试和全量测试的阈值会混淆。
5. 实战中必须绕开的四个坑
5.1 同一个 suite 被重复执行时，脏状态比计数更危险
有段时间我在写一个内部收集测试结果的工具，为了演示方便，把同一个 suite 对象连续run了两次。当时只看返回的 result 计数，发现两次都是“2 tests”，误以为没问题。后来其中一个测试类里用了一个类变量做累加器，第二次运行的结果完全不一样。
问题根源在于：TestSuite里保存的是TestCase实例，而不是“测试方法描述符”。同一个实例被第二次执行时，setUp会再次执行，但实例上已有的属性、mock 状态、类变量累积不会自动重置。也就是说，run()返回的result确实是新创建的，但测试对象本身不是。
所以建议养成习惯：每次运行前都通过TestLoader重新加载测试，而不要复用一个已经跑过的 suite。如果确实需要重复执行同一批测试，例如做稳定性冒烟，应该重新构造TestSuite。
5.2 以为设置了 verbosity 却没看到详细输出的排查链路
常见现象：写了runner = unittest.TextTestRunner(verbosity=2)，但运行后终端仍然只显示点号，或者什么都没有。排查时应按下面思路走一遍。
第一，确认你调用的确实是这个 runner，而不是某处又来了一个unittest.main()。在含有if __name__ == "__main__": unittest.main()的脚本里手动创建 runner，两者混在一起，后者会先执行并把进程退出，前者根本没机会跑。
第二，确认输出去了哪里。如果 stream 被上游代码改成io.StringIO()或文件对象，终端自然看不到。在全套代码里搜TextTestRunner(stream=是否传了非空参数。
第三，确认你的结果类是不是TextTestResult。如果 resultclass 换成了自定义类，并且重写了startTest但没有调用父类，verbosity=2 的“逐条显示测试名”就不会出现。这不一定算 bug，但会让你误以为 verbosity 失效。
第四，注意输出缓冲。因为默认 stream 是 stderr，而很多脚本调试时用 print 观察 stdout，两边混在一起时顺序会很怪。可以先重定向到文件，再确认每一行来自哪个流。
5.3 自定义 resultclass 后“错误全部消失”的根因
自定义 resultclass 最常见的问题不是“没有输出”，而是“明明测试失败了，runner 最后仍然打印 OK”。我见过不少新手在addFailure里只写了self.records.append(...)，忘了调用super().addFailure(test, err)。TextTestResult.wasSuccessful()判断的是基类里failures、errors、unexpectedSuccesses三个列表是否为空。父类addFailure的职责之一就是把用例追加进failures列表。你不调父类，列表就是空的，后续wasSuccessful()自然返回 True。
还有一个连带问题：不调父类，stream上的F字符也不会输出，因为显示逻辑写在父类实现里。所以排查自定义结果类“异常安静”的问题时，第一件事永远是检查super()调用是否完整。
反过来，如果你重写了printErrors，也要注意它依赖self.errors + self.failures这个列表拼接顺序。若你在子类里改了这两个列表的结构，比如存成字典，打印方法会直接崩溃。
5.4 版本差异：tb_locals、durations 与流行为不一致
除durations是 3.12 新增外，tb_locals是 3.5 新增的，result.startTestRun/stopTestRun也是后来补充进协议的。如果你的代码要服务多个 Python 版本，构造 runner 的参数一定要做兼容判断。
另一个版本差异是 buffer 行为的细节。早期版本里，buffer=True只能捕获 Python 层sys.stdout/sys.stderr的写入；到了现代版本，捕获机制已经用contextlib.redirect_stdout/stderr实现，行为更接近“进程内重定向”。但无论如何，C 扩展里直接写 POSIX 文件描述符的输出仍然捕获不到。如果你遇到“明明代码里调了 print，测试失败时却看不到输出”，先确认 print 是否被重定向到了非 stdout 流，或者是否用了第三方的 logging handler 直连文件。
版本差异还有一个容易被忽略的点：TextTestRunner的durations输出格式在不同 patch 版本之间可能变了。如果你们的团队同时跨多个 3.12 小版本，不要对“Slowest N tests”这段文本做精确字符串匹配，最好拿到 datetime 或自定义格式化后再用。
6. 从 runner 到测试框架雏形：我的使用心得
最后说点这些年反复用出来的体会。我在很多项目里看过两种极端：要么所有测试脚本都写成unittest.main()，遇到定制需求就无从下手；要么一上来就上 pytest、nox、tox 这类重量级工具，杀鸡用牛刀。其实runner = unittest.TextTestRunner(resultclass=MyResult, verbosity=1)这一行就是一个轻量测试执行器的核心，很多需求根本不需要引入额外依赖。
我个人的习惯是：单单跑一次验证，直接用unittest.main(verbosity=2)；需要做多模块合并、自定义报告、控制退出码，就手动组合TestLoader和TextTestRunner；需要把结果喂给内部平台，就写一个继承TextTestResult的子类，通过resultclass注入。这样既保留了 unittest 原生的稳定执行链路，又没被框架绑定死。
一个小技巧可以作为扩展起点：把 stream 替换成你自定义的“报告缓冲器”，同时在 resultclass 里记录结构化数据，跑完测试后两者拼成一份 Markdown 或 JSON 报告，既不影响终端输出，又能自动归档。这就是 TextTestRunner 最舒服的用法——它足够简单，简单到你可以轻松接管它的输出，而不是被它的输出接管。
