什么是 assertEqual？

assertEqual 是 Python unittest 框架中的一个核心断言方法,它的主要作用是在单元测试中验证两个值是否相等。

如果两个值相等，测试会正常通过，程序继续执行，如果两个值不相等，assertEqual 会立即抛出一个 AssertionError，从而标记该测试用例为失败（Failed）。

它的作用就是：“断言这两个东西应该相等，如果不相等，测试就失败！”

语法

assertEqual 通常在测试类的方法中使用,其基本语法如下：

self.assertEqual(first, second, msg=None)

参数说明：

• first: 你期望的实际值（通常是你的函数或代码块执行后的返回结果）。
• second: 你期望的、与之比较的预期值（也称为“测试值”或“期望值”）。
• msg (可选): 如果断言失败时，你想显示的自定义错误信息，如果不提供，unittest 会默认生成一个信息,告诉你哪个值不等于哪个值。

注意： self.assertEqual(first, second) 和 self.assertEqual(second, first) 在功能上是完全等价的，它们都只是检查 first == second 的结果是否为 True。

如何使用（代码示例）

要使用 assertEqual，你需要遵循 unittest 框架的基本结构：

1. 导入 unittest 模块。
2. 创建一个继承自 unittest.TestCase 的测试类。
3. 在测试类中，创建以 test_ 开头的方法（这些就是你的测试用例）。
4. 在测试方法中，调用 self.assertEqual() 来进行断言。
5. 在脚本末尾，使用 unittest.main() 来运行测试。

示例 1：最简单的用法

假设我们有一个简单的函数需要测试：

# my_calculator.py
def add(a, b):
    """一个简单的加法函数"""
    return a + b

我们为这个函数编写测试用例：

# test_my_calculator.py
import unittest
from my_calculator import add
class TestMyCalculator(unittest.TestCase):
    """测试 MyCalculator 类的测试用例"""
    def test_add_positive_numbers(self):
        """测试两个正数相加"""
        # 1. 准备测试数据
        a = 2
        b = 3
        expected_result = 5
        # 2. 调用被测函数
        actual_result = add(a, b)
        # 3. 使用 assertEqual 进行断言
        # 检查实际结果是否等于预期结果
        self.assertEqual(actual_result, expected_result)
    def test_add_negative_numbers(self):
        """测试两个负数相加"""
        result = add(-1, -5)
        expected = -6
        self.assertEqual(result, expected)
    def test_add_zero(self):
        """测试一个数和零相加"""
        self.assertEqual(add(10, 0), 10)
        self.assertEqual(add(0, -10), -10)
# 这行代码会自动发现并运行所有以 'test_' 开头的方法
if __name__ == '__main__':
    unittest.main()

如何运行测试？

1. 确保你的文件 my_calculator.py 和 test_my_calculator.py 在同一个目录下。
2. 在终端中，运行 python test_my_calculator.py。

输出结果（成功时）：

...
----------------------------------------------------------------------
Ran 3 tests in 0.001s
OK

这里的 代表 3 个测试点都通过了。

示例 2：断言失败的情况

我们故意在 test_add_positive_numbers 中写一个错误的预期值,看看会发生什么。

# 修改 test_my_calculator.py 中的一个测试
def test_add_positive_numbers(self):
    a = 2
    b = 3
    # 故意写错预期值
    expected_result = 6  # 应该是 5
    actual_result = add(a, b)
    self.assertEqual(actual_result, expected_result)

再次运行测试：

输出结果（失败时）：

F..
======================================================================
FAIL: test_add_positive_numbers (__main__.TestMyCalculator)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "test_my_calculator.py", line 15, in test_add_positive_numbers
    self.assertEqual(actual_result, expected_result)
AssertionError: 5 != 6  # 错误信息清晰地显示了实际值和预期值
----------------------------------------------------------------------
Ran 3 tests in 0.001s
FAILED (failures=1)

输出解读：

• F..：第一个测试用例失败（F），后两个成功（）。
• FAIL: test_add_positive_numbers：明确指出了是哪个测试用例失败了。
• AssertionError: 5 != 6：这是核心错误信息，告诉我们 assertEqual 发现 5 不等于 6。
• FAILED (failures=1)：总结报告，显示总共 1 个测试失败。

示例 3：使用自定义错误信息

当测试失败时，默认的错误信息通常已经足够清晰，但在某些复杂场景下,你可能需要提供更多上下文。

def test_add_with_custom_message(self):
    result = add(100, 200)
    # 如果失败，会显示我们自定义的错误信息
    self.assertEqual(result, 300, "计算 100 + 200 时发生了意外错误！")

如果这个测试因为 result 不是 300 而失败,错误信息会变成：

AssertionError: 计算 100 + 200 时发生了意外错误！: 300 != 400

这比默认信息更具描述性。

assertEqual 与其他断言方法的比较

unittest 提供了多种断言方法，选择合适的能让你的测试更精确、更具可读性。

最佳实践：

• 优先使用 assertEqual：当你想检查两个值是否相等时，assertEqual 是最直接、最可读的选择。
• 避免 assertTrue(result == 5)：虽然 self.assertTrue(result == 5) 也能工作，但它不如 self.assertEqual(result, 5) 清晰，如果断言失败，assertEqual 会自动打印出 5 != 6 这样的信息，而 assertTrue 只会告诉你 False is not true,你需要自己去猜哪里出了问题。
• 为复杂断言使用特定方法：对于检查对象身份（is）、成员关系（in）等，使用 assertIs、assertIn 等特定方法会让测试意图更加明确。

assertEqual 是 Python 单元测试的基石之一，它简单、强大，并且提供了清晰的失败反馈,掌握它的用法是编写有效自动化测试的第一步。

unittest 的核心思想：

1. 准备 -> 执行 -> 断言。
2. 使用 self.assertEqual() 来验证你的代码是否按预期工作。