/usr/lib/python3/dist-packages/zope/testing/doctestcase.py is in python3-zope.testing 4.5.0-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 | r"""Doctests in TestCase classes
The original ``doctest`` unittest integration was based on
``unittest`` test suites, which have fallen out of favor. This module
provides a way to define doctests inside of unittest ``TestCase``
classes. It also provides better integration with unittest test
fixtures, because doctests use setup provided by the containing test
case class. It also provides access to unittest assertion
methods.
You can define doctests in 4 ways:
- references to named files
- strings
- decorated functions with docstrings
- reference to named files decorating test-specific setup functions
.. some setup
>>> __name__ = 'tests'
Here are some examples::
from zope.testing import doctestcase
import doctest
import unittest
g = 'global'
class MyTest(unittest.TestCase):
def setUp(self):
self.a = 1
self.globs = dict(c=9)
test1 = doctestcase.file('test1.txt', optionflags=doctest.ELLIPSIS)
test2 = doctestcase.docteststring('''
>>> self.a, g, c
(1, 'global', 9)
''')
@doctestcase.doctestmethod(optionflags=doctest.ELLIPSIS)
def test3(self):
'''
>>> self.a, self.x, g, c
(1, 3, 'global', 9)
'''
self.x = 3
@doctestcase.doctestfile('test4.txt')
def test4(self):
self.x = 5
In this example, 3 constructors were used:
doctestfile (alias: file)
doctestfile makes a file-based test case.
This can be used as a decorator, in which case, the decorated
function is called before the test is run, to provide test-specific
setup.
docteststring (alias string)
docteststring constructs a doctest from a string.
doctestmethod (alias method)
doctestmethod constructs a doctest from a method.
The method's docstring provides the test. The method's body provides
optional test-specific setup.
Note that short aliases are provided, which may be useful in certain
import styles.
Tests have access to the following data:
- Tests created with the ``docteststring`` and ``doctestmethod``
constructors have access to the module globals of the defining
module.
- In tests created with the ``docteststring`` and ``doctestmethod``
constructors, the test case instance is available as the ``self``
variable.
- In tests created with the ``doctestfile`` constructor, the test case
instance is available as the ``test`` variable.
- If a test case defines a globs attribute, it must be a dictionary
and its contents are added to the test globals.
The constructors accept standard doctest ``optionflags`` and
``checker`` arguments.
Note that the doctest IGNORE_EXCEPTION_DETAIL option flag is
added to optionflags.
"""
import doctest
import inspect
import os
import re
import sys
import types
__all__ = ['doctestmethod', 'docteststring', 'doctestfile']
_parser = doctest.DocTestParser()
def _testify(name):
if not name.startswith('test'):
name = 'test_' + name
return name
def doctestmethod(test=None, optionflags=0, checker=None):
"""Define a doctest from a method within a unittest.TestCase.
The method's doc string provides the test source. Its body is
called before the test and may perform test-specific setup.
You can pass doctest option flags and a custon checker.
Variables defined in the enclosing module are available in the test.
If a test case defines a globs attribute, it must be a dictionary
and its contents are added to the test globals.
The test object is available as the variable ``self`` in the test.
"""
if test is None:
return lambda test: _doctestmethod(test, optionflags, checker)
return _doctestmethod(test, optionflags, checker)
method = doctestmethod
def _doctestmethod(test, optionflags, checker):
doc = test.__doc__
if not doc:
raise ValueError(test, "has no docstring")
setup = test
name = test.__name__
path = inspect.getsourcefile(test)
lineno = inspect.getsourcelines(test)[1]
fglobs = sys._getframe(3).f_globals
def test_method(self):
setup(self)
_run_test(self, doc, fglobs.copy(), name, path,
optionflags, checker, lineno=lineno)
test_method.__name__ = _testify(name)
return test_method
def docteststring(test, optionflags=0, checker=None, name=None):
"""Define a doctest from a string within a unittest.TestCase.
You can pass doctest option flags and a custon checker.
Variables defined in the enclosing module are available in the test.
If a test case defines a globs attribute, it must be a dictionary
and its contents are added to the test globals.
The test object is available as the variable ``self`` in the test.
"""
fglobs = sys._getframe(2).f_globals
def test_string(self):
_run_test(self, test, fglobs.copy(), '<string>', '<string>',
optionflags, checker)
if name:
test_string.__name__ = _testify(name)
return test_string
string = docteststring
_not_word = re.compile('\W')
def doctestfile(path, optionflags=0, checker=None):
"""Define a doctest from a test file within a unittest.TestCase.
The file path may be relative or absolute. If its relative (the
common case), it will be interpreted relative to the directory
containing the referencing module.
You can pass doctest option flags and a custon checker.
If a test case defines a globs attribute, it must be a dictionary
and its contents are added to the test globals.
The test object is available as the variable ``test`` in the test.
The resulting object can be used as a function decorator. The
decorated method is called before the test and may perform
test-specific setup. (The decorated method's doc string is ignored.)
"""
base = os.path.dirname(os.path.abspath(
sys._getframe(2).f_globals['__file__']
))
path = os.path.join(base, path)
with open(path) as f:
test = f.read()
name = os.path.basename(path)
def test_file(self):
if isinstance(self, types.FunctionType):
setup = self
def test_file_w_setup(self):
setup(self)
_run_test(self, test, {}, name, path, optionflags, checker,
'test')
test_file_w_setup.__name__ = _testify(setup.__name__)
test_file_w_setup.filepath = path
test_file_w_setup.filename = os.path.basename(path)
return test_file_w_setup
_run_test(self, test, {}, name, path, optionflags, checker, 'test')
test_file.__name__ = name_from_path(path)
test_file.filepath = path
test_file.filename = os.path.basename(path)
return test_file
file = doctestfile
def doctestfiles(*paths, **kw):
"""Define doctests from test files in a decorated class.
Multiple files can be specified. A member is added to the
decorated class for each file.
The file paths may be relative or absolute. If relative (the
common case), they will be interpreted relative to the directory
containing the referencing module.
You can pass doctest option flags and a custon checker.
If a test case defines a globs attribute, it must be a dictionary
and its contents are added to the test globals.
The test object is available as the variable ``test`` in the test.
The resulting object must be used as a class decorator.
"""
def doctestfiles_(class_):
for path in paths:
name = name_from_path(path)
test = doctestfile(path, **kw)
test.__name__ = name
setattr(class_, name, test)
return class_
return doctestfiles_
files = doctestfiles
def name_from_path(path):
return _testify(
_not_word.sub('_', os.path.splitext(os.path.basename(path))[0])
)
def _run_test(self, test, globs, name, path,
optionflags, checker, testname='self', lineno=0):
globs.update(getattr(self, 'globs', ()))
globs[testname] = self
optionflags |= doctest.IGNORE_EXCEPTION_DETAIL
doctest.DocTestCase(
_parser.get_doctest(test, globs, name, path, lineno),
optionflags=optionflags,
checker=checker,
).runTest()
|