assertEqual 是 Python 内置 unittest 框架中的一个断言方法，用于测试两个值是否相等，如果它们相等，测试继续执行；如果不相等，则会抛出一个 AssertionError,导致测试失败。

核心语法

assertEqual 方法通常在测试类内部使用，作为 unittest.TestCase 类的一个方法。

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

参数详解：

• first: 你期望得到的值,或者第一个进行比较的值。
• second: 实际计算或运行得到的值,或者第二个进行比较的值。
• msg (可选): 当断言失败时显示的自定义错误信息，如果提供，这个信息会出现在测试失败报告中，帮助你更快地定位问题，如果省略，unittest 会自动生成一个默认的错误信息。

工作原理： assertEqual 内部会使用 运算符来判断 first 和 second 是否相等，只要支持 比较的对象（如数字、字符串、列表、字典等）都可以使用此方法进行比较。

基本使用示例

下面是一个完整的、简单的测试用例示例，展示了 assertEqual 的几种常见用法。

我们假设有一个简单的模块 my_math.py,我们要测试它：

my_math.py

def add(a, b):
    """两个数相加"""
    return a + b
def is_even(n):
    """判断一个数是否为偶数"""
    return n % 2 == 0

我们为这个模块编写测试用例：

test_my_math.py

import unittest
from my_math import add, is_even
class TestMyMath(unittest.TestCase):
    """测试 my_math 模块中的函数"""
    def test_add(self):
        """测试 add 函数"""
        # 1. 测试两个正整数相加
        result = add(3, 5)
        self.assertEqual(result, 8, "3 + 5 应该等于 8")
        # 2. 测试一个正数和一个负数相加
        result = add(10, -2)
        self.assertEqual(result, 8, "10 + (-2) 应该等于 8")
        # 3. 测试两个浮点数相加
        # 注意：浮点数比较有时会因精度问题失败，但 assertEqual 会处理
        result = add(0.1, 0.2)
        self.assertAlmostEqual(result, 0.3, places=5) # 更推荐用 assertAlmostEqual
        # self.assertEqual(result, 0.3) # 这个可能会失败或产生警告
    def test_is_even(self):
        """测试 is_even 函数"""
        # 1. 测试一个偶数
        self.assertEqual(is_even(4), True, "4 应该是偶数")
        # 2. 测试一个奇数
        self.assertEqual(is_even(7), False, "7 不应该是偶数")
        # 3. 测试 0
        self.assertEqual(is_even(0), True, "0 应该是偶数")
# --- 运行测试 ---
if __name__ == '__main__':
    unittest.main()

如何运行测试： 在终端中，进入 test_my_math.py 文件所在的目录,然后运行：

python -m unittest test_my_math.py

或者直接运行文件：

python test_my_math.py

预期输出： 如果所有测试都通过,你会看到类似下面的输出：

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

如果某个测试失败，比如我们故意把 add(3, 5) 的期望结果写成 9：

self.assertEqual(add(3, 5), 9, "3 + 5 应该等于 8")

输出会变成：

F..
======================================================================
FAIL: test_add (__main__.TestMyMath)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "test_my_math.py", line 10, in test_add
    self.assertEqual(add(3, 5), 9, "3 + 5 应该等于 8")
AssertionError: 8 != 9 : 3 + 5 应该等于 8
----------------------------------------------------------------------
Ran 3 tests in 0.001s
FAILED (failures=1)

从输出中可以清楚地看到：

• FAIL: 表示 test_add 测试失败了。
• AssertionError: 抛出的异常类型。
• 8 != 9: 自动生成的比较信息，显示实际值是 8，期望值是 9。
• 3 + 5 应该等于 8: 我们提供的自定义错误信息。

重要细节和最佳实践

a. first 和 second 的顺序

虽然 assertEqual(first, second) 和 assertEqual(second, first) 在功能上是等价的，但为了代码的可读性和调试方便，强烈建议将期望值放在 first 位置，实际值放在 second 位置。

推荐做法：

self.assertEqual(actual_result, expected_result)

这样，当测试失败时，错误信息 X != Y 的含义就是 “实际结果 X 不等于期望结果 Y”,非常直观。

b. assertEqual vs assert

Python 有一个内置的 assert 语句，功能上与 unittest 的断言有相似之处。

• assert 语句:

  def add(a, b):
      return a + b
  result = add(3, 5)
  assert result == 8, "加法计算错误" # result != 8，程序会抛出 AssertionError

  assert 主要用于在代码中进行简单的、非测试环境的内部检查，如果条件为假，程序会立即终止，它不适合用于编写正式的测试用例,因为：

  1. 功能受限：只能做简单的布尔判断，不像 unittest 提供了 assertIn, assertRaises 等丰富的断言方法。
  2. 优化问题：Python 在使用 -O (优化) 标志运行时，assert 语句会被禁用,导致检查失效。
  3. 报告不友好：失败时报告的信息不如 unittest 详细和结构化。

• unittest.assertEqual (推荐用于测试):

  1. 功能强大：是测试框架的一部分，可以与其他测试方法（如 setUp, tearDown）无缝集成。
  2. 稳定可靠：不受 -O 标志影响,始终会执行。
  3. 报告清晰：提供标准的测试报告，易于CI/CD工具解析。

c. 与其他断言方法的比较

unittest 提供了多种断言方法,选择正确的工具很重要。

• 语法: self.assertEqual(first, second, msg=None)
• 用途: 在 unittest 测试中验证两个值是否相等。
• 最佳实践:
  • 将期望值 (first) 和实际值 (second) 分开，并保持 期望在前 的顺序。
  • 为重要的断言提供有意义的 msg,方便调试。