Python Unittest 框架详细使用指南

Python 的 unittest 模块是一个内置的单元测试框架，它借鉴了 JUnit 的设计理念，遵循 XUnit 架构模型 。其主要目标是验证代码的各个独立单元（如函数、方法、类）是否能按预期工作，从而提升代码的稳定性、可维护性，并在重构时提供安全网 。

一、 核心概念与结构

在使用 unittest 之前，需要理解其四个核心构件 ：

构件名称 作用说明
TestCase 测试用例的基类。我们通过继承该类并定义以 test 开头的方法来创建具体的测试用例。每个 test_xxx 方法都是一个独立的测试点。
TestSuite 测试套件，用于将多个 TestCase、TestSuite 或其子类组装成一个测试集合，便于批量、有组织地运行。
TestFixture 测试固件，代表测试执行前的准备工作和执行后的清理工作。通常通过重写 TestCase 类中的 setUp()（准备）、tearDown()（清理）方法来实现。
TestRunner 测试运行器，负责执行测试并输出结果。最常用的是 unittest.TextTestRunner，它会将结果输出到控制台。

unittest 的工作原理是，TestRunner 根据指定条件（如模块、类、方法名）查找并收集 TestCase，然后执行它们。对于每个 TestCase，TestRunner 会先调用 setUp() 进行初始化，然后执行测试方法，最后调用 tearDown() 进行清理，确保每个测试在独立、干净的环境中运行 。

二、 基础用法：从编写到运行

1. 编写被测代码

首先，我们有一个需要测试的简单模块 calculator.py，它包含一个 Calculator 类 ：

# calculator.py
class Calculator:
    def add(self, a, b):
        return a + b

    def subtract(self, a, b):
        return a - b

    def multiply(self, a, b):
        return a * b

    def divide(self, a, b):
        if b == 0:
            raise ValueError("除数不能为零")
        return a / b

2. 编写测试用例

按照约定，测试文件应以 test_ 开头。我们创建 test_calculator.py，继承 unittest.TestCase 并编写测试方法 。

# test_calculator.py
import unittest
from calculator import Calculator

class TestCalculator(unittest.TestCase):
    """
    Calculator类的单元测试用例
    """

    # 测试固件：每个测试方法执行前运行
    def setUp(self):
        print("开始执行测试...")
        self.calc = Calculator()  # 为每个测试方法创建一个干净的Calculator实例 

    # 测试固件：每个测试方法执行后运行
    def tearDown(self):
        print("测试执行结束.
")
        # 可以在这里释放资源，如关闭文件、数据库连接等

    # 测试方法1：测试加法
    def test_add(self):
        result = self.calc.add(10, 5)
        self.assertEqual(result, 15)  # 断言：期望结果等于15 

    # 测试方法2：测试减法
    def test_subtract(self):
        result = self.calc.subtract(10, 5)
        self.assertEqual(result, 5)

    # 测试方法3：测试乘法
    def test_multiply(self):
        result = self.calc.multiply(10, 5)
        self.assertEqual(result, 50)

    # 测试方法4：测试除法（正常情况）
    def test_divide_normal(self):
        result = self.calc.divide(10, 5)
        self.assertEqual(result, 2)
        # 也可以使用assertAlmostEqual来比较浮点数，避免精度问题 
        result2 = self.calc.divide(1, 3)
        self.assertAlmostEqual(result2, 0.333333, places=6)

    # 测试方法5：测试除法异常（除数为零）
    def test_divide_by_zero(self):
        # 断言：期望调用calc.divide(10, 0)会抛出ValueError异常 
        with self.assertRaises(ValueError) as context:
            self.calc.divide(10, 0)
        # 还可以进一步检查异常信息
        self.assertEqual(str(context.exception), "除数不能为零")

# 允许直接运行此脚本
if __name__ == '__main__':
    unittest.main()

3. 运行测试

有多种方式可以运行上述测试：

  • 直接运行测试脚本：在命令行中执行 python test_calculator.py。unittest.main() 提供了运行测试的入口，它会自动发现并运行当前模块中以 test 开头的方法 。
  • 使用命令行模块：在项目根目录下，使用 python -m unittest 命令。这是更推荐的方式，因为它可以灵活地发现和运行多个测试模块 。
    • python -m unittest test_calculator：运行指定测试模块。
    • python -m unittest test_calculator.TestCalculator：运行指定测试类。
    • python -m unittest test_calculator.TestCalculator.test_add：运行指定的单个测试方法。
    • python -m unittest discover：自动发现并运行当前目录及其子目录下所有以 test*.py 命名的测试文件 。

执行后，控制台会输出类似以下的结果，其中 . 表示测试通过，F 表示失败，E 表示错误。

开始执行测试...
测试执行结束.
.
开始执行测试...
测试执行结束.
.
...（其余输出）...
----------------------------------------------------------------------
Ran 5 tests in 0.001s
OK

三、 进阶特性详解

1. 丰富的断言方法

unittest.TestCase 提供了大量断言方法用于验证测试结果，是测试逻辑的核心 。

断言方法 用途说明 示例
assertEqual(a, b) 验证 a == b self.assertEqual(result, 15)
assertNotEqual(a, b) 验证 a != b self.assertNotEqual(result, 0)
assertTrue(x) 验证 x 为 True self.assertTrue(is_valid)
assertFalse(x) 验证 x 为 False self.assertFalse(is_empty)
assertIs(a, b) 验证 a is b (同一对象) self.assertIs(obj, None)
assertIsNot(a, b) 验证 a is not b self.assertIsNot(obj, None)
assertIsNone(x) 验证 x is None self.assertIsNone(error)
assertIsNotNone(x) 验证 x is not None self.assertIsNotNone(result)
assertIn(a, b) 验证 a in b self.assertIn(‘item‘, list)
assertNotIn(a, b) 验证 a not in b self.assertNotIn(‘item‘, list)
assertIsInstance(obj, cls) 验证 obj 是 cls 的实例 self.assertIsInstance(response, dict)
assertNotIsInstance(obj, cls) 验证 obj 不是 cls 的实例 self.assertNotIsInstance(value, str)
assertRaises(exc, callable, *args, **kwds) 验证调用 callable(*args, **kwds) 会引发 exc 异常 with self.assertRaises(ValueError): func()
assertAlmostEqual(a, b) 验证浮点数 a 约等于 b（默认精度7位小数） self.assertAlmostEqual(a, 3.14159, places=5)
assertNotAlmostEqual(a, b) 验证浮点数 a 不约等于 b self.assertNotAlmostEqual(a, b)
assertGreater(a, b) 验证 a > b self.assertGreater(score, 60)
assertGreaterEqual(a, b) 验证 a >= b self.assertGreaterEqual(len(list), 1)
assertLess(a, b) 验证 a < b self.assertLess(time_spent, 10)
assertLessEqual(a, b) 验证 a <= b self.assertLessEqual(count, max_limit)
assertCountEqual(a, b) 验证序列 a 和 b 包含相同元素，不考虑顺序 self.assertCountEqual(list_a, list_b)

2. 测试固件 (Fixture) 的层级

除了为每个测试方法运行的 setUp/tearDown，unittest 还提供了类级别和模块级别的固件 。

import unittest

class TestAdvancedFixture(unittest.TestCase):

    @classmethod
    def setUpClass(cls):
        """类级别Fixture：在整个测试类开始执行前运行一次，用于昂贵的初始化（如数据库连接）。"""
        print("=== 整个TestAdvancedFixture测试类开始 ===")
        cls.shared_conn = create_database_connection()  # 模拟共享连接

    @classmethod
    def tearDownClass(cls):
        """类级别Fixture：在整个测试类所有方法执行完毕后运行一次，用于清理资源。"""
        cls.shared_conn.close()
        print("=== 整个TestAdvancedFixture测试类结束 ===")

    def setUp(self):
        """方法级别Fixture：每个测试方法执行前运行。"""
        print(f"  准备执行测试方法: {self._testMethodName}")
        self.data = [1, 2, 3]  # 每个测试方法拥有独立的数据副本

    def tearDown(self):
        """方法级别Fixture：每个测试方法执行后运行。"""
        print(f"  清理测试方法: {self._testMethodName}")

    def test_example_1(self):
        self.assertIn(2, self.data)
        self.assertIsNotNone(self.shared_conn)

    def test_example_2(self):
        self.assertEqual(len(self.data), 3)

3. 跳过测试与预期失败

有时需要临时跳过某些测试，或标记已知但尚未修复的问题 。

import unittest
import sys

class TestSkipAndExpectedFailure(unittest.TestCase):

    @unittest.skip("无条件跳过这个测试，并说明原因")
    def test_skipped(self):
        self.fail("这个测试不会被执行")

    @unittest.skipIf(sys.version_info < (3, 7), "Python版本低于3.7时跳过")
    def test_skip_if(self):
        # 只有在Python 3.7+环境下才会运行
        self.assertTrue(True)

    @unittest.skipUnless(sys.platform.startswith("win"), "非Windows平台跳过")
    def test_skip_unless(self):
        # 只有在Windows平台上才会运行
        self.assertTrue(True)

    @unittest.expectedFailure  # 标记此测试预期会失败，如果它失败了，结果不算失败而是“预期失败”
    def test_buggy_feature(self):
        # 这是一个已知有Bug的功能，测试会失败，但这是预期的
        self.assertEqual(1, 2)  # 这显然会失败

if __name__ == '__main__':
    unittest.main()

4. 组织测试套件 (TestSuite)

当项目有多个测试模块或需要自定义测试顺序和组合时，可以使用 TestSuite 。

# test_suite_demo.py
import unittest
# 导入你的测试模块和类
from test_calculator import TestCalculator
# 假设有另一个测试模块 test_string_utils.py
# from test_string_utils import TestStringUtils

def create_suite():
    """手动创建测试套件"""
    suite = unittest.TestSuite()
    # 添加整个测试类
    suite.addTest(unittest.makeSuite(TestCalculator))
    # 添加单个测试方法
    # suite.addTest(TestCalculator('test_add'))
    # 添加另一个测试类
    # suite.addTest(unittest.makeSuite(TestStringUtils))
    return suite

if __name__ == '__main__':
    # 创建运行器并执行套件
    runner = unittest.TextTestRunner(verbosity=2)  # verbosity=2 输出更详细信息
    suite = create_suite()
    runner.run(suite)

更常见的做法是使用 TestLoader 自动加载测试 ：

# 使用TestLoader自动发现并加载
loader = unittest.TestLoader()
# 从指定模块加载测试
suite1 = loader.loadTestsFromModule(test_calculator)
# 从指定类加载测试
suite2 = loader.loadTestsFromTestCase(TestCalculator)
# 从指定名称（字符串）加载测试
suite3 = loader.loadTestsFromName(‘test_calculator.TestCalculator‘)

# 组合多个套件
master_suite = unittest.TestSuite([suite1, suite2])
runner.run(master_suite)

5. 参数化测试（使用 subTest）

对于需要测试多组不同输入输出数据的场景，可以使用 subTest 上下文管理器，它能在同一个测试方法内运行多个子测试，即使某个子测试失败，其他子测试仍会继续执行 。

import unittest

class TestParameterizedWithSubTest(unittest.TestCase):

    def test_multiplication_with_subtest(self):
        """使用subTest进行参数化测试"""
        test_cases = [
            (1, 5, 5),
            (2, 0, 0),
            (-3, 4, -12),
            (-2, -2, 4),
        ]
        for a, b, expected in test_cases:
            # 为每组参数创建一个子测试上下文
            with self.subTest(a=a, b=b, expected=expected):
                result = a * b
                self.assertEqual(result, expected, f"{a} * {b} 应该等于 {expected}")

四、 生成测试报告

虽然 TextTestRunner 输出简洁，但在持续集成或需要存档时，生成格式化的 HTML 报告更为直观。可以使用第三方库如 HTMLTestRunner 或 unittest-xml-reporting。

以下是使用 HTMLTestRunner 的一个示例（需先安装：pip install html-testRunner）：

import unittest
import HtmlTestRunner
from test_calculator import TestCalculator

# 创建测试套件
suite = unittest.TestLoader().loadTestsFromTestCase(TestCalculator)

# 使用HtmlTestRunner运行并生成报告
runner = HtmlTestRunner.HTMLTestRunner(
    output=‘./reports‘,        # 报告输出目录
    report_name=‘Calculator_Test_Report‘, # 报告文件名
    report_title=‘Calculator模块单元测试报告‘, # 报告标题
    descriptions=‘测试加减乘除功能‘, # 报告描述
    combine_reports=True       # 合并多个报告
)
runner.run(suite)

运行后，会在 ./reports 目录下生成一个格式美观的 HTML 报告，包含通过/失败/跳过的测试统计、详细信息以及错误追踪 。

五、 最佳实践与总结

  1. 测试独立性：每个测试方法应相互独立，不依赖其他测试的执行顺序或状态。setUp 和 tearDown 正是为此而设计。
  2. 命名规范：测试类名建议以 Test 开头，测试方法名以 test_ 开头，这样能被测试发现器自动识别。
  3. 单一职责：一个测试方法应只验证一个明确的功能点或场景，保持测试简洁。
  4. 使用恰当的断言：选择最能清晰表达验证意图的断言方法，并提供有意义的失败信息（如 self.assertEqual(actual, expected, “详细错误说明”)）。
  5. 测试异常和边界：不仅要测试正常路径（happy path），更要测试异常输入、边界条件（如空值、极值、非法参数）。
  6. 保持测试快速：单元测试应该执行迅速，避免依赖网络、数据库等外部慢速服务。必要时使用模拟（Mock）对象。
  7. 持续集成：将单元测试集成到版本控制系统的钩子（如 Git Hooks）或持续集成/持续部署（CI/CD）管道中，确保每次代码变更都经过测试。

通过以上从基础到进阶的详细示例和解释，你应该能够理解 unittest 框架的结构，并开始为自己的 Python 项目编写有效的单元测试。核心步骤是：导入 unittest 模块 -> 创建继承 unittest.TestCase 的测试类 -> 在类中定义 test_ 开头的测试方法 -> 在方法中使用断言验证结果 -> 利用固件 (setUp/tearDown) 管理测试环境 -> 使用 unittest.main() 或命令行来运行测试 。

参考来源

 

# python
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

WalkingLab 组织入驻 AtomGit，释放高校智能体开源科研成果

avatar AtomGit开源社区
cover

拼手速！GLM-5.2免费Token每天10点准点开抢！

avatar AtomGit开源社区
cover

AtomGit 2026年6月三方库下载量排行榜重磅发布！双榜格局稳固，生态深耕持续发力

avatar AtomGit开源社区