This document discusses various techniques for writing doctests, including: - Summarizing how doctests allow testing functions through documentation strings. - Handling unpredictable output like object IDs using options like ELLIPSIS. - Working around whitespace issues using tags like <BLANKLINE>. - Specifying test locations within modules or external files. - Documenting functions in external files like .rst files. - Running tests on modules, files, or via a unittest suite. - Isolating test globals and contexts to avoid interference across tests.

1. doctest Testing through documentation Honggang Wang @ Aragon Nov 2010

3. def multiply(a, b):

4. “””

5. This is a demo function.

6. >>> multiply(3, 4)

7. 12

8. >>> multiply('a', 5)

9. 'aaaaa'

10. “””

12. $ python -v foo.py

13. $ python -m doctest -v foo.py

14. Trying:

15. multiply(3, 4)

16. Expecting:

17. 12

18. ok

19. ...

20. 2 passed and 0 failed.

23. Object ids

24. Precision of float values

25. Exceptions

26. And more...

28. class A(object):

29. pass

30. def gene_list(obj):

31. “””

32. Put obj into a list.

33. >>> gene_list(A())

34. [<unpredictable.A object at 0x9c2214c>]

35. “””

36. return [obj]

38. class A(object):

39. pass

40. def gene_list(obj):

41. “””

42. Put obj into a list.

43. >>> gene_list(A()) #doctest: +ELLIPSIS

44. [<unpredictable2.A object at 0x...>]

45. “””

46. return [obj]

48. def double_space(lines):

49. &quot;&quot;&quot;Prints a list of lines double-spaced.

50. >>> double_space(['Line one.', 'Line two.'])

51. Line one.

52. Line two.

53. &quot;&quot;&quot;

54. for l in lines:

55. print l

56. print

57. return

59. def double_space(lines):

60. &quot;&quot;&quot;Prints a list of lines double-spaced.

61. >>> double_space(['Line one.', 'Line two.'])

62. Line one.

63. <BLANKLINE>

64. Line two.

65. <BLANKLINE>

66. &quot;&quot;&quot;

67. for l in lines:

68. print l

69. print

70. return

72. “””

73. >>> A == B

74. False

75. “””

76. class A(object): pass

77. class B(object): pass

79. from b_cls import B

80. __test__ = {

81. 'test001': “””

82. >>> A.__class__

83. <type 'type'>

84. “”” ,

85. 'external': B,

86. }

87. class A(object):

89. “””

90. >>> 1 + 1

91. 3

92. “””

93. class B(object):

94. “”” The class B.

95. >>> B.__name__

96. B

97. “””

98. pass

100. def multiply(a, b):

102. How to use foo2.py

103. ===============

104. For numbers:

105. >>> from foo2 import multiply

106. >>> multiply(3, 7)

107. 21

108. It also works with strings:

109. >>> multiply('s', 7)

113. def add(a, b):

114. return a + b

115. if __name__ == “__main__”:

116. import doctest

118. import utils

119. if __name__ == “__main__”:

120. import doctest

121. doctest.testmod(utils)

123. import doctest

124. if __name__ == “__main__”:

127. import doctest

128. import unittest

129. import doctest_simple

130. suite = unittest.TestSuite()

131. suite.addTest(doctest.DocTestSuite(doctest_simple))

132. suite.addTest(doctest.DocFileSuite('doctest_in_help.rst'))

133. runner = unittest.TextTestRunner(verbosity=2)

134. runner.run(suite)

136. my_function (doctest_simple)

137. Doctest: doctest_simple.my_function ... ok

138. doctest_in_help.rst

139. Doctest: doctest_in_help.rst ... ok

140. ----------------------------------------------------------------------

141. Ran 2 tests in 0.006s

142. OK

144. def one(self):

145. &quot;&quot;&quot;

146. >>> var = 'value'

147. >>> 'var' in globals()

148. True

149. &quot;&quot;&quot;

150. def two(self):

151. &quot;&quot;&quot;

152. >>> 'var' in globals()

153. False

156. Trying:

157. var = 'value'

158. Expecting nothing

159. ok

160. ...

161. 2 items passed all tests:

162. 2 tests in doctest_test_globals.TestGlobals.one

163. 1 tests in doctest_test_globals.TestGlobals.two

164. 3 tests in 4 items.

165. 3 passed and 0 failed.

166. Test passed.

168. class TestGlobals(object):

169. def one(self):

170. &quot;&quot;&quot;

171. >>> TestGlobals().one()

172. >>> 'var' in _module_data

173. True

174. &quot;&quot;&quot;

175. _module_data['var'] = 'value'

176. def two(self):

177. &quot;&quot;&quot;

178. >>> 'var' in _module_data

179. False

180. &quot;&quot;&quot;

182. ...

183. Failed example:

184. 'var' in _module_data

185. Expected:

186. False

187. Got:

188. True

189. ...

190. 3 tests in 4 items.

191. 2 passed and 1 failed.

192. ***Test Failed*** 1 failures.

193. Thanks!