单位测试文件 [英] Unit test documentation
问题描述
我作为开发人员的经验告诉我，理解旧代码（包括单元测试）是困难的。
那么测试文档中的重要内容呢？测试方法名称什么时候不足以说明文档是否合理？
根据Thorsten79的要求，我将详细说明我的意见作为答案。我的原始评论是：
代码说不幸的是
完全错误，因为
非开发者不能读代码，
，而他可以至少部分阅读
并理解生成的
文档，这样他可以通过
知道测试测试。这是
在客户完全理解
域并且无法读取代码的情况下尤其重要，当
测试时，
变得更加重要还要测试硬件，就像
嵌入式世界一样，因为你测试
可以看到的东西。
当您进行单元测试时，您必须知道您是否为您（或同事）编写它们，或者您是否还为其他人撰写。很多时候，您应该为您的读者编写代码 ，而不是为了方便起见。
在我公司的混合硬件/软件开发客户知道他们想要什么。如果现场设备在接收到某个总线命令时必须进行复位，则必须有一个发送该命令的单元测试，并检查该设备是否被重置。我们现在正在使用NUnit作为单元测试框架，还有一些可以使发送和接收命令（甚至按下按钮）的定制软件和硬件。这很棒，因为唯一的选择是手动执行所有操作。
客户绝对想知道哪些测试在那里，他甚至想自己运行测试。如果测试没有正确记录，他不知道测试是做什么的，不能检查他认为他需要的所有测试都在那里，而在运行测试时，他不知道该怎么做。因为他无法读取代码。他很了解二手总线系统比我们的开发人员更好，但是他们看不懂代码。如果测试失败，他不知道为什么甚至不能说他认为测试应该做什么。这不是一件好事。
正确记录了单元测试，我们有
- 开发人员的代码文档
- 客户的测试文档，可用于证明设备执行的操作，即客户订购的内容
- 以任何格式生成文档的能力，甚至可以传递给其他相关方，如制造商
在这种情况下，正确的是：写出非开发人员可以理解的清晰语言。你可以保持技术性，但不要写东西，只有你能理解。后者对任何其他意见和任何代码当然也很重要。
独立于我们的确切情况，我认为这是我在单元测试中所需要的，即使他们是纯软件。客户可以忽略他不关心的单元测试，如基本功能测试。但是只要把文件放在那里就不会有伤害。
正如我在另一个答案中写的一样：另外，生成的文档也是一个很好的起点，如果您（或您的老板或同事或测试部门）想要检查哪些测试在哪里以及他们做什么，因为您可以浏览它们而不用挖掘代码。
I would like to know from those who document unit tests how they are documenting it. I understand that most TDD followers claim "the code speaks" and thus test documentation is not very important because code should be self-descriptive. Fair enough, but I would like to know how to document unit tests, not whether to document them at all.
My experience as a developer tells me that understanding old code (this includes unit tests) is difficult.
So what is important in a test documentation? When is the test method name not descriptive enough so that documentation is justified?
As requested by Thorsten79, I'll elaborate on my comments as an answer. My original comment was:
"The code speaks" is unfortunately completely wrong, because a non-developer cannot read the code, while he can at least partially read and understand generated documentation, and this way he can know what the tests test. This is especially important in cases where the customer fully understands the domain and just can't read code, and gets even more important when the unit tests also test hardware, like in the embedded world, because then you test things that can be seen.
When you're doing unit tests, you have to know whether you're writing them just for you (or for your co-workers), or if you're also writing them for other people. Many times, you should be writing code for your readers, rather than for your convenience.
In mixed hardware/software development like in my company, the customers know what they want. If their field device has to do a reset when receiving a certain bus command, there must be a unit test that sends that command and checks whether the device was reset. We're doing this here right now with NUnit as the unit test framework, and some custom software and hardware that makes sending and receiving commands (and even pressing buttons) possible. It's great, because the only alternative would be to do all that manually.
The customer absolutely wants to know which tests are there, and he even wants to run the tests himself. If the tests are not properly documented, he doesn't know what the test does and can't check if all tests he think he'll need are there, and when running the test, he doesn't know what it will do. Because he can't read the code. He knows the used bus system better than our developers, but they just can't read the code. If a test fails, he does not know why and cannot even say what he thinks the test should do. That's not a good thing.
Having documented the unit tests properly, we have
- code documentation for the developers
- test documentation for the customer, which can be used to prove that the device does what it should do, i.e. what the customer ordered
- the ability to generate the documentation in any format, which can even be passed to other involved parties, like the manufacturer
Properly in this context means: Write clear language that can be understood by non-developers. You can stay technical, but don't write things only you can understand. The latter is of course also important for any other comments and any code.
Independent of our exact situation, I think that's what I would want in unit tests all the time, even if they're pure software. A customer can ignore a unit test he doesn't care about, like basic function tests. But just having the docs there does never hurt.
As I've written in a comment to another answer: In addition, the generated documentation is also a good starting point if you (or your boss, or co-worker, or the testing department) wants to examine which tests are there and what they do, because you can browse it without digging through the code.
这篇关于单位测试文件的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
