Both are valuable. I use both doctest and nose taking the place of unittest. I use doctest for cases where the test is giving an example of usage that is actually useful as documentation. Generally I don't make these tests comprehensive, aiming solely for informative. I'm effectively using doctest in reverse: not to test my code is correct based on my doctest, but to check that my documentation is correct based on the code.
The reason is that I find comprehensive doctests will clutter your documentation far too much, so you will either end up with either unusable docstrings, or incomplete testing.
For actually testing the code, the goal is to thoroughly test every case, rather than illustrate what is does by example, which is a different goal which I think is better met by other frameworks.
Once in a while, I'll put some stuff in a docstring that's usable by doctest.
95% of the test cases are unittest.
Why? I like keeping docstrings somewhat shorter and more to the point. Sometimes test cases help clarify a docstring. Most of the time, the application's test cases are too long for a docstring.
Another advantage of doctesting is that you get to make sure your code does what your documentation says it does. After a while, software changes can make your documentation and code do different things. :-)
I work as a bioinformatician, and most of the code I write is "one time, one task" scripts, code that will be run only once or twice and that execute a single specific task.
In this situation, writing big unittests may be overkill, and doctests are an useful compromise. They are quicker to write, and since they are usually incorporated in the code, they allow to always keep an eye on how the code should behave, without having to have another file open. That's useful when writing small script.
Also, doctests are useful when you have to pass your script to a researcher that is not expert in programming. Some people find it very difficult to understand how unittests are structured; on the other hand, doctests are simple examples of usage, so people can just copy and paste them to see how to use them.
So, to resume my answer: doctests are useful when you have to write small scripts, and when you have to pass them or show them to researchers that are not computer scientists.
If you're just getting started with the idea of unit testing, I would start with doctest because it is so simple to use. It also naturally provides some level of documentation. And for more comprehensive testing with doctest, you can place tests in an external file so it doesn't clutter up your documentation.
I would suggest unittest if you're coming from a background of having used JUnit or something similar, where you want to be able to write unit tests in generally the same way as you have been elsewhere.
I don't use doctest as a replacement for unittest. Although they overlap a bit, the two modules don't have the same function:
I use unittest as a unit testing framework, meaning it helps me determine quickly the impact of any modification on the rest of the code.
I use doctest as a guarantee that comments (namely docstrings) are still relevant to current version of the code.
The widely documented benefits of test driven development I get from unittest. doctest solves the far more subtle danger of having outdated comments misleading the maintenance of the code.
Using both is a valid and rather simple option. The doctest module provides the DoctTestSuite and DocFileSuite methods which create a unittest-compatible testsuite from a module or file, respectively.
So I use both and typically use doctest for simple tests with functions that require little or no setup (simple types for arguments). I actually think a few doctest tests help document the function, rather than detract from it.
But for more complicated cases, and for a more comprehensive set of test cases, I use unittest which provides more control and flexibility.
I almost never use doctests. I want my code to be self documenting, and the docstrings provide the documentation to the user. IMO adding hundreds of lines of tests to a module makes the docstrings far less readable. I also find unit tests easier to modify when needed.
def convert():
"""
>>> convert()
'\xe0\xa4\x95'
"""
a = '\xe0\xa4\x95'
return a
import doctest
doctest.testmod()
给出
**********************************************************************
File "hindi.py", line 3, in __main__.convert
Failed example:
convert()
Expected:
'क'
Got:
'\xe0\xa4\x95'
**********************************************************************
1 items had failures:
1 of 1 in __main__.convert
***Test Failed*** 1 failures.
Also 不检查输出的类型。 它只是比较输出字符串。 例如，它创建了某种有理数类型，如果它是整数，则它会像整数一样打印。 然后假设你有返回有理数的函数。 因此，文档测试不会区分输出是有理整数还是整数。
Doctest can some times lead to wrong result. Especially when output contains escape sequences. For example
def convert():
"""
>>> convert()
'\xe0\xa4\x95'
"""
a = '\xe0\xa4\x95'
return a
import doctest
doctest.testmod()
gives
**********************************************************************
File "hindi.py", line 3, in __main__.convert
Failed example:
convert()
Expected:
'क'
Got:
'\xe0\xa4\x95'
**********************************************************************
1 items had failures:
1 of 1 in __main__.convert
***Test Failed*** 1 failures.
Also doesn't check the type of the output. It just compares the output strings. For example it have made some type rational which prints just like integer if it is a whole number. Then suppose you have function which return rational. So, a doctest won't differentiate if the output is rational whole number or a integer number.
发布评论
评论（11）
两者都很有价值。 我使用 doctest 和 nose 代替unittest。 我使用 doctest 来处理测试给出的用法示例，该示例实际上可用作文档。 一般来说，我不会让这些测试变得全面，只是为了提供信息。 我有效地反向使用 doctest：不是根据我的 doctest 测试我的代码是否正确，而是根据代码检查我的文档是否正确。
原因是我发现全面的文档测试会使您的文档变得过于混乱，因此您最终要么得到无法使用的文档字符串，要么得到不完整的测试。
对于实际测试代码，目标是彻底测试每种情况，而不是通过示例说明其作用，这是一个不同的目标，我认为其他框架可以更好地满足这一目标。
Both are valuable. I use both doctest and nose taking the place of unittest. I use doctest for cases where the test is giving an example of usage that is actually useful as documentation. Generally I don't make these tests comprehensive, aiming solely for informative. I'm effectively using doctest in reverse: not to test my code is correct based on my doctest, but to check that my documentation is correct based on the code.
The reason is that I find comprehensive doctests will clutter your documentation far too much, so you will either end up with either unusable docstrings, or incomplete testing.
For actually testing the code, the goal is to thoroughly test every case, rather than illustrate what is does by example, which is a different goal which I think is better met by other frameworks.
我几乎只使用单元测试。
有时，我会将一些内容放入 doctest 可以使用的文档字符串中。
95%的测试用例是单元测试。
为什么？ 我喜欢让文档字符串更短、更切题。 有时测试用例有助于阐明文档字符串。 大多数时候，应用程序的测试用例对于文档字符串来说太长。
I use unittest almost exclusively.
Once in a while, I'll put some stuff in a docstring that's usable by doctest.
95% of the test cases are unittest.
Why? I like keeping docstrings somewhat shorter and more to the point. Sometimes test cases help clarify a docstring. Most of the time, the application's test cases are too long for a docstring.
文档测试的另一个优点是您可以确保您的代码按照文档的说明执行操作。 一段时间后，软件更改可能会使您的文档和代码执行不同的操作。 :-)
Another advantage of doctesting is that you get to make sure your code does what your documentation says it does. After a while, software changes can make your documentation and code do different things. :-)
我是一名生物信息学家，我编写的大部分代码都是“一次、一项任务”脚本，这些代码仅运行一次或两次并执行单个特定任务。
在这种情况下，编写大型单元测试可能有点矫枉过正，而文档测试是一个有用的折衷方案。 它们的编写速度更快，并且由于它们通常合并在代码中，因此可以始终关注代码的行为方式，而无需打开另一个文件。 这在编写小脚本时很有用。
此外，当您必须将脚本传递给不擅长编程的研究人员时，文档测试也很有用。 有些人发现很难理解单元测试的结构； 另一方面，文档测试是简单的用法示例，因此人们只需复制并粘贴它们即可了解如何使用它们。
因此，继续我的回答：当您必须编写小脚本，以及必须通过它们或将它们展示给非计算机科学家的研究人员时，文档测试非常有用。
I work as a bioinformatician, and most of the code I write is "one time, one task" scripts, code that will be run only once or twice and that execute a single specific task.
In this situation, writing big unittests may be overkill, and doctests are an useful compromise. They are quicker to write, and since they are usually incorporated in the code, they allow to always keep an eye on how the code should behave, without having to have another file open. That's useful when writing small script.
Also, doctests are useful when you have to pass your script to a researcher that is not expert in programming. Some people find it very difficult to understand how unittests are structured; on the other hand, doctests are simple examples of usage, so people can just copy and paste them to see how to use them.
So, to resume my answer: doctests are useful when you have to write small scripts, and when you have to pass them or show them to researchers that are not computer scientists.
如果您刚刚开始了解单元测试的想法，我会从 doctest 开始，因为它使用起来非常简单。 它还自然地提供了一定程度的文档。 为了使用
doctest进行更全面的测试，您可以将测试放在外部文件中，这样就不会弄乱您的文档。如果您有使用过 JUnit 或类似工具的背景，并且希望能够以与在其他地方相同的方式编写单元测试，我建议您使用
unittest。If you're just getting started with the idea of unit testing, I would start with
doctestbecause it is so simple to use. It also naturally provides some level of documentation. And for more comprehensive testing withdoctest, you can place tests in an external file so it doesn't clutter up your documentation.I would suggest
unittestif you're coming from a background of having used JUnit or something similar, where you want to be able to write unit tests in generally the same way as you have been elsewhere.我不使用 doctest 作为单元测试的替代品。 尽管它们有一点重叠，但这两个模块没有相同的功能：
我使用
unittest作为单元测试框架，这意味着它可以帮助我快速确定任何修改对其余模块的影响我使用 doctest 来保证注释（即文档字符串）仍然与当前版本的代码相关。
我从
unittest中获得了广泛记录的测试驱动开发的好处。doctest解决了过时注释误导代码维护的更微妙的危险。I don't use doctest as a replacement for unittest. Although they overlap a bit, the two modules don't have the same function:
I use
unittestas a unit testing framework, meaning it helps me determine quickly the impact of any modification on the rest of the code.I use
doctestas a guarantee that comments (namely docstrings) are still relevant to current version of the code.The widely documented benefits of test driven development I get from
unittest.doctestsolves the far more subtle danger of having outdated comments misleading the maintenance of the code.我专门使用单元测试； 我认为 doctest 使主模块变得过于混乱。 这可能与编写彻底的测试有关。
I use unittest exclusively; I think doctest clutters up the main module too much. This probably has to do with writing thorough tests.
两者同时使用是一个有效且相当简单的选择。
doctest模块提供DoctTestSuite和DocFileSuite方法，分别从模块或文件创建与单元测试兼容的测试套件。因此，我使用两者，并且通常使用 doctest 进行简单测试，其功能需要很少或不需要设置（参数的简单类型）。 实际上，我认为一些 doctest 测试帮助记录了该功能，而不是削弱了它。
但对于更复杂的情况，以及更全面的测试用例集，我使用unittest，它提供了更多的控制和灵活性。
Using both is a valid and rather simple option. The
doctestmodule provides theDoctTestSuiteandDocFileSuitemethods which create a unittest-compatible testsuite from a module or file, respectively.So I use both and typically use doctest for simple tests with functions that require little or no setup (simple types for arguments). I actually think a few doctest tests help document the function, rather than detract from it.
But for more complicated cases, and for a more comprehensive set of test cases, I use unittest which provides more control and flexibility.
我几乎从不使用文档测试。 我希望我的代码能够自我记录，并且文档字符串向用户提供文档。 IMO 在模块中添加数百行测试会使文档字符串的可读性大大降低。 我还发现单元测试在需要时更容易修改。
I almost never use doctests. I want my code to be self documenting, and the docstrings provide the documentation to the user. IMO adding hundreds of lines of tests to a module makes the docstrings far less readable. I also find unit tests easier to modify when needed.
Doctest有时会导致错误的结果。 特别是当输出包含转义序列时。 例如给出
Also 不检查输出的类型。 它只是比较输出字符串。 例如，它创建了某种有理数类型，如果它是整数，则它会像整数一样打印。 然后假设你有返回有理数的函数。 因此，文档测试不会区分输出是有理整数还是整数。
Doctestcan some times lead to wrong result. Especially when output contains escape sequences. For examplegives
Also doesn't check the type of the output. It just compares the output strings. For example it have made some type rational which prints just like integer if it is a whole number. Then suppose you have function which return rational. So, a doctest won't differentiate if the output is rational whole number or a integer number.
我更喜欢基于发现的系统（“nose”和“py.test”，目前使用前者）。
当测试也可以作为文档时，doctest 就很好，否则它们往往会使代码变得过于混乱。
I prefer the discovery based systems ("nose" and "py.test", using the former currently).
doctest is nice when the test is also good as a documentation, otherwise they tend to clutter the code too much.