为什么你应该记录你的测试

有些项目的政策是所有测试都必须有解释性评论——包括我的所有测试。起初，我觉得这很莫名其妙。如果那是你现在，这篇文章是给你的。

我相信你也去过那里：你编码，写一个明显的测试，测试一个明显的东西，你给一个明显的名字。快进一两年。关于那个测试的一切都不再是显而易见的了。在什么情况下测试什么属性可能很明显，但您不知道为什么要测试它。

为了说明这一点，让我们看一下我的一个 Python 项目中的一个简化测试：

def test_eq_false():
    @attr.s(eq=False)
    class C:
        pass
​
    c1 = C()
    c2 = C()
​
    assert hash(c1) != hash(c2)

我们在这里测试什么？代码非常清晰，不需要注释：我们正在测试如果eq参数设置为False，则类实例的哈希值不同. 测试名称表明它eq=False很重要——但为什么呢？

在这种情况下，我们测试该设置eq=False使类可按对象 ID 散列。它们的哈希值不同的事实是我们实际测试的副作用。这在测试中很常见：很多时候，你不能直接提问。相反，您验证某些证明您的代码正在实现其目标的属性。

---

如果你不解释你实际测试的是什么，你就会强迫读者（可能是未来的你）通过查看它的所有属性来推断主要意图。这使得快速扫描文件以进行特定测试或在测试开始失败时了解您实际破坏的内容变得既累人又耗时。

可以说，示例测试名称可能更具描述性。也许test_eq_false_makes_hashable_by_id。但是意图不能总是用几句话来概括，并且您必须受到一些行长限制。此外，对于回归测试，我喜欢添加指向Sentry或错误跟踪器问题的链接——祝你好运将这些信息放入测试名称中。

---

你如何去记录你的测试取决于你选择的语言。对于 Python，我使用文档字符串，对于 Go，我通常descr在表测试中有一个字段。如果有疑问，请添加一个简单的评论。

然而，编写好的测试文档本身就是一门艺术。首先，清晰的写作需要清晰的思维。这可能会让你一开始觉得它放慢了你的速度，但它最终会帮助你更好地理解问题。其次，您不希望在您的评论中有多余的语言样板。我推荐Jonathan Lange 的这篇博文，他从无用的“测试输入是否正确解析”中迭代。对有价值的东西。

分享三个有趣的网站，或许能提高你的学习兴趣，第三个最好玩！

在 Python 中强制他们的存在

缺少测试文档字符串是我在拉取请求中必须提出的最常见问题之一。这对我的贡献者来说是令人沮丧的，这不利于留住贡献者，因此也不利于我的项目。

这就是为什么当我的朋友Lynn Root发布interrogate时我很高兴：这个工具可以帮助您查找 Python 文件中缺少文档字符串的方法、函数、类和模块。

强制所有测试函数和测试方法都有一个文档字符串就像运行一样简单

$ interrogate -vv --fail-under 100 --whitelist-regex "test_.*" tests