PK4~7zope/__init__.py# namespace package boilerplate try: __import__('pkg_resources').declare_namespace(__name__) except ImportError, e: from pkgutil import extend_path __path__ = extend_path(__path__, __name__) PK45Wfzope/__init__.pyc; rtDc@sOyedieWn1ej o%ZdklZeeeZnXdS(s pkg_resources(s extend_pathN(s __import__sdeclare_namespaces__name__s ImportErrorsespkgutils extend_paths__path__(ses extend_paths__path__((s+build/bdist.linux-i686/egg/zope/__init__.pys?s PK͆3zEy{{zope/testing/doctestunit.py############################################################################## # # Copyright (c) 2003 Zope Corporation and Contributors. # All Rights Reserved. # # This software is subject to the provisions of the Zope Public License, # Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution. # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS # FOR A PARTICULAR PURPOSE. # ############################################################################## """Extension to use doctest tests as unit tests This module provides a DocTestSuite contructor for converting doctest tests to unit tests. $Id: doctestunit.py 28304 2004-10-31 17:59:45Z jim $ """ from doctest import DocFileSuite, DocTestSuite from doctest import debug_src, debug def pprint(): from pprint import PrettyPrinter def pprint(ob, **opts): if 'width' not in opts: opts['width'] = 1 return PrettyPrinter(**opts).pprint(ob) return pprint pprint = pprint() PK4Պg~~zope/testing/__init__.py############################################################################## # # Copyright (c) 2001, 2002 Zope Corporation and Contributors. # All Rights Reserved. # # This software is subject to the provisions of the Zope Public License, # Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution. # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS # FOR A PARTICULAR PURPOSE. # ############################################################################## """Set up testing environment $Id: __init__.py 68482 2006-06-04 14:58:55Z jim $ """ import os def patchTracebackModule(): """Use the ExceptionFormatter to show more info in tracebacks. """ from zope.exceptions.exceptionformatter import format_exception import traceback traceback.format_exception = format_exception # Don't use the new exception formatter by default, since it # doesn't show filenames. if os.environ.get('NEW_ZOPE_EXCEPTION_FORMATTER', 0): patchTracebackModule() PK͆3l<7wwzope/testing/tests.py############################################################################## # # Copyright (c) 2004 Zope Corporation and Contributors. # All Rights Reserved. # # This software is subject to the provisions of the Zope Public License, # Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution. # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS # FOR A PARTICULAR PURPOSE. # ############################################################################## """Tests for the testing framework. $Id: tests.py 30492 2005-05-24 20:28:53Z jim $ """ import os import sys import unittest from zope.testing import doctest, testrunner def test_suite(): return unittest.TestSuite(( doctest.DocTestSuite('zope.testing.renormalizing'), doctest.DocFileSuite('formparser.txt'), doctest.DocTestSuite('zope.testing.loggingsupport'), testrunner.test_suite(), )) if __name__ == '__main__': unittest.main(defaultTest='test_suite') PKv454uVzope/testing/doctest.py# Module doctest. # Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org). # Major enhancements and refactoring by: # Jim Fulton # Edward Loper # Provided as-is; use at your own risk; no warranty; no promises; enjoy! r"""Module doctest -- a framework for running examples in docstrings. In simplest use, end each module M to be tested with: def _test(): import doctest doctest.testmod() if __name__ == "__main__": _test() Then running the module as a script will cause the examples in the docstrings to get executed and verified: python M.py This won't display anything unless an example fails, in which case the failing example(s) and the cause(s) of the failure(s) are printed to stdout (why not stderr? because stderr is a lame hack <0.2 wink>), and the final line of output is "Test failed.". Run it with the -v switch instead: python M.py -v and a detailed report of all examples tried is printed to stdout, along with assorted summaries at the end. You can force verbose mode by passing "verbose=True" to testmod, or prohibit it by passing "verbose=False". In either of those cases, sys.argv is not examined by testmod. There are a variety of other ways to run doctests, including integration with the unittest framework, and support for running non-Python text files containing doctests. There are also many ways to override parts of doctest's default behaviors. See the Library Reference Manual for details. """ __docformat__ = 'reStructuredText en' __all__ = [ # 0, Option Flags 'register_optionflag', 'DONT_ACCEPT_TRUE_FOR_1', 'DONT_ACCEPT_BLANKLINE', 'NORMALIZE_WHITESPACE', 'ELLIPSIS', 'IGNORE_EXCEPTION_DETAIL', 'COMPARISON_FLAGS', 'REPORT_UDIFF', 'REPORT_CDIFF', 'REPORT_NDIFF', 'REPORT_ONLY_FIRST_FAILURE', 'REPORTING_FLAGS', # 1. Utility Functions 'is_private', # 2. Example & DocTest 'Example', 'DocTest', # 3. Doctest Parser 'DocTestParser', # 4. Doctest Finder 'DocTestFinder', # 5. Doctest Runner 'DocTestRunner', 'OutputChecker', 'DocTestFailure', 'UnexpectedException', 'DebugRunner', # 6. Test Functions 'testmod', 'testfile', 'run_docstring_examples', # 7. Tester 'Tester', # 8. Unittest Support 'DocTestSuite', 'DocFileSuite', 'set_unittest_reportflags', # 9. Debugging Support 'script_from_examples', 'testsource', 'debug_src', 'debug', ] import __future__ import sys, traceback, inspect, linecache, os, re, types import unittest, difflib, pdb, tempfile import warnings from StringIO import StringIO # Don't whine about the deprecated is_private function in this # module's tests. warnings.filterwarnings("ignore", "is_private", DeprecationWarning, __name__, 0) class UnusedFootnoteWarning(Warning): """Warn about a footnote that is defined, but never referenced.""" real_pdb_set_trace = pdb.set_trace # There are 4 basic classes: # - Example: a pair, plus an intra-docstring line number. # - DocTest: a collection of examples, parsed from a docstring, plus # info about where the docstring came from (name, filename, lineno). # - DocTestFinder: extracts DocTests from a given object's docstring and # its contained objects' docstrings. # - DocTestRunner: runs DocTest cases, and accumulates statistics. # # So the basic picture is: # # list of: # +------+ +---------+ +-------+ # |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results| # +------+ +---------+ +-------+ # | Example | # | ... | # | Example | # +---------+ # Option constants. OPTIONFLAGS_BY_NAME = {} def register_optionflag(name): flag = 1 << len(OPTIONFLAGS_BY_NAME) OPTIONFLAGS_BY_NAME[name] = flag return flag DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1') DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE') NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE') ELLIPSIS = register_optionflag('ELLIPSIS') IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL') COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 | DONT_ACCEPT_BLANKLINE | NORMALIZE_WHITESPACE | ELLIPSIS | IGNORE_EXCEPTION_DETAIL) REPORT_UDIFF = register_optionflag('REPORT_UDIFF') REPORT_CDIFF = register_optionflag('REPORT_CDIFF') REPORT_NDIFF = register_optionflag('REPORT_NDIFF') REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE') REPORTING_FLAGS = (REPORT_UDIFF | REPORT_CDIFF | REPORT_NDIFF | REPORT_ONLY_FIRST_FAILURE) INTERPRET_FOOTNOTES = register_optionflag('INTERPRET_FOOTNOTES') # Special string markers for use in `want` strings: BLANKLINE_MARKER = '' ELLIPSIS_MARKER = '...' ###################################################################### ## Table of Contents ###################################################################### # 1. Utility Functions # 2. Example & DocTest -- store test cases # 3. DocTest Parser -- extracts examples from strings # 4. DocTest Finder -- extracts test cases from objects # 5. DocTest Runner -- runs test cases # 6. Test Functions -- convenient wrappers for testing # 7. Tester Class -- for backwards compatibility # 8. Unittest Support # 9. Debugging Support # 10. Example Usage ###################################################################### ## 1. Utility Functions ###################################################################### def is_private(prefix, base): """prefix, base -> true iff name prefix + "." + base is "private". Prefix may be an empty string, and base does not contain a period. Prefix is ignored (although functions you write conforming to this protocol may make use of it). Return true iff base begins with an (at least one) underscore, but does not both begin and end with (at least) two underscores. >>> is_private("a.b", "my_func") False >>> is_private("____", "_my_func") True >>> is_private("someclass", "__init__") False >>> is_private("sometypo", "__init_") True >>> is_private("x.y.z", "_") True >>> is_private("_x.y.z", "__") False >>> is_private("", "") # senseless but consistent False """ warnings.warn("is_private is deprecated; it wasn't useful; " "examine DocTestFinder.find() lists instead", DeprecationWarning, stacklevel=2) return base[:1] == "_" and not base[:2] == "__" == base[-2:] def _extract_future_flags(globs): """ Return the compiler-flags associated with the future features that have been imported into the given namespace (globs). """ flags = 0 for fname in __future__.all_feature_names: feature = globs.get(fname, None) if feature is getattr(__future__, fname): flags |= feature.compiler_flag return flags def _normalize_module(module, depth=2): """ Return the module specified by `module`. In particular: - If `module` is a module, then return module. - If `module` is a string, then import and return the module with that name. - If `module` is None, then return the calling module. The calling module is assumed to be the module of the stack frame at the given depth in the call stack. """ if inspect.ismodule(module): return module elif isinstance(module, (str, unicode)): return __import__(module, globals(), locals(), ["*"]) elif module is None: return sys.modules[sys._getframe(depth).f_globals['__name__']] else: raise TypeError("Expected a module, string, or None") def _indent(s, indent=4): """ Add the given number of space characters to the beginning every non-blank line in `s`, and return the result. """ # This regexp matches the start of non-blank lines: return re.sub('(?m)^(?!$)', indent*' ', s) def _exception_traceback(exc_info): """ Return a string containing a traceback message for the given exc_info tuple (as returned by sys.exc_info()). """ # Get a traceback message. excout = StringIO() exc_type, exc_val, exc_tb = exc_info traceback.print_exception(exc_type, exc_val, exc_tb, file=excout) return excout.getvalue() # Override some StringIO methods. class _SpoofOut(StringIO): def getvalue(self): result = StringIO.getvalue(self) # If anything at all was written, make sure there's a trailing # newline. There's no way for the expected output to indicate # that a trailing newline is missing. if result and not result.endswith("\n"): result += "\n" # Prevent softspace from screwing up the next test case, in # case they used print with a trailing comma in an example. if hasattr(self, "softspace"): del self.softspace return result def truncate(self, size=None): StringIO.truncate(self, size) if hasattr(self, "softspace"): del self.softspace # Worst-case linear-time ellipsis matching. def _ellipsis_match(want, got): """ Essentially the only subtle case: >>> _ellipsis_match('aa...aa', 'aaa') False """ if ELLIPSIS_MARKER not in want: return want == got # Find "the real" strings. ws = want.split(ELLIPSIS_MARKER) assert len(ws) >= 2 # Deal with exact matches possibly needed at one or both ends. startpos, endpos = 0, len(got) w = ws[0] if w: # starts with exact match if got.startswith(w): startpos = len(w) del ws[0] else: return False w = ws[-1] if w: # ends with exact match if got.endswith(w): endpos -= len(w) del ws[-1] else: return False if startpos > endpos: # Exact end matches required more characters than we have, as in # _ellipsis_match('aa...aa', 'aaa') return False # For the rest, we only need to find the leftmost non-overlapping # match for each piece. If there's no overall match that way alone, # there's no overall match period. for w in ws: # w may be '' at times, if there are consecutive ellipses, or # due to an ellipsis at the start or end of `want`. That's OK. # Search for an empty string succeeds, and doesn't change startpos. startpos = got.find(w, startpos, endpos) if startpos < 0: return False startpos += len(w) return True def _comment_line(line): "Return a commented form of the given line" line = line.rstrip() if line: return '# '+line else: return '#' class _OutputRedirectingPdb(pdb.Pdb): """ A specialized version of the python debugger that redirects stdout to a given stream when interacting with the user. Stdout is *not* redirected when traced code is executed. """ def __init__(self, out): self.__out = out self.__debugger_used = False pdb.Pdb.__init__(self) def set_trace(self): self.__debugger_used = True pdb.Pdb.set_trace(self) def set_continue(self): # Calling set_continue unconditionally would break unit test coverage # reporting, as Bdb.set_continue calls sys.settrace(None). if self.__debugger_used: pdb.Pdb.set_continue(self) def trace_dispatch(self, *args): # Redirect stdout to the given stream. save_stdout = sys.stdout sys.stdout = self.__out # Call Pdb's trace dispatch method. result = pdb.Pdb.trace_dispatch(self, *args) # Restore stdout. sys.stdout = save_stdout return result # [XX] Normalize with respect to os.path.pardir? def _module_relative_path(module, path): if not inspect.ismodule(module): raise TypeError('Expected a module: %r' % module) if path.startswith('/'): raise ValueError('Module-relative files may not have absolute paths') # Find the base directory for the path. if hasattr(module, '__file__'): # A normal module/package basedir = os.path.split(module.__file__)[0] elif module.__name__ == '__main__': # An interactive session. if len(sys.argv)>0 and sys.argv[0] != '': basedir = os.path.split(sys.argv[0])[0] else: basedir = os.curdir else: # A module w/o __file__ (this includes builtins) raise ValueError("Can't resolve paths relative to the module " + module + " (it has no __file__)") # Combine the base directory and the path. return os.path.join(basedir, *(path.split('/'))) ###################################################################### ## 2. Example & DocTest ###################################################################### ## - An "example" is a pair, where "source" is a ## fragment of source code, and "want" is the expected output for ## "source." The Example class also includes information about ## where the example was extracted from. ## ## - A "doctest" is a collection of examples, typically extracted from ## a string (such as an object's docstring). The DocTest class also ## includes information about where the string was extracted from. class Example: """ A single doctest example, consisting of source code and expected output. `Example` defines the following attributes: - source: A single Python statement, always ending with a newline. The constructor adds a newline if needed. - want: The expected output from running the source code (either from stdout, or a traceback in case of exception). `want` ends with a newline unless it's empty, in which case it's an empty string. The constructor adds a newline if needed. - exc_msg: The exception message generated by the example, if the example is expected to generate an exception; or `None` if it is not expected to generate an exception. This exception message is compared against the return value of `traceback.format_exception_only()`. `exc_msg` ends with a newline unless it's `None`. The constructor adds a newline if needed. - lineno: The line number within the DocTest string containing this Example where the Example begins. This line number is zero-based, with respect to the beginning of the DocTest. - indent: The example's indentation in the DocTest string. I.e., the number of space characters that preceed the example's first prompt. - options: A dictionary mapping from option flags to True or False, which is used to override default options for this example. Any option flags not contained in this dictionary are left at their default value (as specified by the DocTestRunner's optionflags). By default, no options are set. """ def __init__(self, source, want, exc_msg=None, lineno=0, indent=0, options=None): # Normalize inputs. if not source.endswith('\n'): source += '\n' if want and not want.endswith('\n'): want += '\n' if exc_msg is not None and not exc_msg.endswith('\n'): exc_msg += '\n' # Store properties. self.source = source self.want = want self.lineno = lineno self.indent = indent if options is None: options = {} self.options = options self.exc_msg = exc_msg class DocTest: """ A collection of doctest examples that should be run in a single namespace. Each `DocTest` defines the following attributes: - examples: the list of examples. - globs: The namespace (aka globals) that the examples should be run in. - name: A name identifying the DocTest (typically, the name of the object whose docstring this DocTest was extracted from). - filename: The name of the file that this DocTest was extracted from, or `None` if the filename is unknown. - lineno: The line number within filename where this DocTest begins, or `None` if the line number is unavailable. This line number is zero-based, with respect to the beginning of the file. - docstring: The string that the examples were extracted from, or `None` if the string is unavailable. """ def __init__(self, examples, globs, name, filename, lineno, docstring): """ Create a new DocTest containing the given examples. The DocTest's globals are initialized with a copy of `globs`. """ assert not isinstance(examples, basestring), \ "DocTest no longer accepts str; use DocTestParser instead" self.examples = examples self.docstring = docstring self.globs = globs.copy() self.name = name self.filename = filename self.lineno = lineno def __repr__(self): if len(self.examples) == 0: examples = 'no examples' elif len(self.examples) == 1: examples = '1 example' else: examples = '%d examples' % len(self.examples) return ('' % (self.name, self.filename, self.lineno, examples)) # This lets us sort tests by name: def __cmp__(self, other): if not isinstance(other, DocTest): return -1 return cmp((self.name, self.filename, self.lineno, id(self)), (other.name, other.filename, other.lineno, id(other))) ###################################################################### ## 3. DocTestParser ###################################################################### class DocTestParser: """ A class used to parse strings containing doctest examples. """ # This regular expression is used to find doctest examples in a # string. It defines three groups: `source` is the source code # (including leading indentation and prompts); `indent` is the # indentation of the first (PS1) line of the source code; and # `want` is the expected output (including leading indentation). _EXAMPLE_RE = re.compile(r''' # Source consists of a PS1 line followed by zero or more PS2 lines. (?P (?:^(?P [ ]*) >>> .*) # PS1 line (?:\n [ ]* \.\.\. .*)*) # PS2 lines \n? # Want consists of any non-blank lines that do not start with PS1. (?P (?:(?![ ]*$) # Not a blank line (?![ ]*>>>) # Not a line starting with PS1 .*$\n? # But any other line )*) ''', re.MULTILINE | re.VERBOSE) # A regular expression for handling `want` strings that contain # expected exceptions. It divides `want` into three pieces: # - the traceback header line (`hdr`) # - the traceback stack (`stack`) # - the exception message (`msg`), as generated by # traceback.format_exception_only() # `msg` may have multiple lines. We assume/require that the # exception message is the first non-indented line starting with a word # character following the traceback header line. _EXCEPTION_RE = re.compile(r""" # Grab the traceback header. Different versions of Python have # said different things on the first traceback line. ^(?P Traceback\ \( (?: most\ recent\ call\ last | innermost\ last ) \) : ) \s* $ # toss trailing whitespace on the header. (?P .*?) # don't blink: absorb stuff until... ^ (?P \w+ .*) # a line *starts* with alphanum. """, re.VERBOSE | re.MULTILINE | re.DOTALL) # A callable returning a true value iff its argument is a blank line # or contains a single comment. _IS_BLANK_OR_COMMENT = re.compile(r'^[ ]*(#.*)?$').match # Find footnote references. _FOOTNOTE_REFERENCE_RE = re.compile(r'\[([^\]]+)]_') # Find footnote definitions. _FOOTNOTE_DEFINITION_RE = re.compile( r'^\.\.\s*\[\s*([^\]]+)\s*\].*$', re.MULTILINE) # End of footnote regex. Just looks for any unindented line. _FOOTNOTE_END_RE = re.compile(r'^\S+', re.MULTILINE) def parse(self, string, name='', optionflags=0): """ Divide the given string into examples and intervening text, and return them as a list of alternating Examples and strings. Line numbers for the Examples are 0-based. The optional argument `name` is a name identifying this string, and is only used for error messages. """ string = string.expandtabs() # If all lines begin with the same indentation, then strip it. min_indent = self._min_indent(string) if min_indent > 0: string = '\n'.join([l[min_indent:] for l in string.split('\n')]) output = [] charno, lineno = 0, 0 # Find all doctest examples in the string: for m in self._EXAMPLE_RE.finditer(string): # Add the pre-example text to `output`. output.append(string[charno:m.start()]) # Update lineno (lines before this example) lineno += string.count('\n', charno, m.start()) # Extract info from the regexp match. (source, options, want, exc_msg) = \ self._parse_example(m, name, lineno) # Create an Example, and add it to the list. if not self._IS_BLANK_OR_COMMENT(source): output.append( Example(source, want, exc_msg, lineno=lineno, indent=min_indent+len(m.group('indent')), options=options) ) # Update lineno (lines inside this example) lineno += string.count('\n', m.start(), m.end()) # Update charno. charno = m.end() # Add any remaining post-example text to `output`. output.append(string[charno:]) if optionflags & INTERPRET_FOOTNOTES: footnotes = {} in_footnote = False # collect all the footnotes for x in output: if in_footnote: footnote.append(x) # we're collecting prose and examples for a footnote if isinstance(x, Example): x._footnote_name = name elif self._FOOTNOTE_END_RE.search(x): # this looks like prose that ends a footnote in_footnote = False footnotes[name] = footnote del name del footnote if not in_footnote: if not isinstance(x, Example): matches = list( self._FOOTNOTE_DEFINITION_RE.finditer(x)) if matches: # all but the last one don't have any code # note: we intentionally reuse the "leaked" value # of match below for match in matches: footnotes[match.group(1)] = [] in_footnote = True name = match.group(1) footnote = [] # if we were still collecting a footnote when the loop ended, # stash it away so it's not lost if in_footnote: footnotes[name] = footnote # inject each footnote into the point(s) at which it is referenced new_output = [] defined_footnotes = [] used_footnotes = [] for x in output: if isinstance(x, Example): # we don't want to execute footnotes where they're defined if hasattr(x, '_footnote_name'): defined_footnotes.append(x._footnote_name) continue else: m = None for m in self._FOOTNOTE_REFERENCE_RE.finditer(x): name = m.group(1) if name not in footnotes: raise KeyError( 'A footnote was referred to, but never' ' defined: %r' % name) new_output.append(x) new_output.extend(footnotes[name]) used_footnotes.append(name) if m is not None: continue new_output.append(x) output = new_output # make sure that all of the footnotes found were actually used unused_footnotes = set(defined_footnotes) - set(used_footnotes) for x in unused_footnotes: warnings.warn('a footnote was defined, but never used: %r' % x, UnusedFootnoteWarning) return output def get_doctest(self, string, globs, name, filename, lineno, optionflags=0): """ Extract all doctest examples from the given string, and collect them into a `DocTest` object. `globs`, `name`, `filename`, and `lineno` are attributes for the new `DocTest` object. See the documentation for `DocTest` for more information. """ return DocTest(self.get_examples(string, name, optionflags), globs, name, filename, lineno, string) def get_examples(self, string, name='', optionflags=0): """ Extract all doctest examples from the given string, and return them as a list of `Example` objects. Line numbers are 0-based, because it's most common in doctests that nothing interesting appears on the same line as opening triple-quote, and so the first interesting line is called \"line 1\" then. The optional argument `name` is a name identifying this string, and is only used for error messages. """ return [x for x in self.parse(string, name, optionflags) if isinstance(x, Example)] def _parse_example(self, m, name, lineno): """ Given a regular expression match from `_EXAMPLE_RE` (`m`), return a pair `(source, want)`, where `source` is the matched example's source code (with prompts and indentation stripped); and `want` is the example's expected output (with indentation stripped). `name` is the string's name, and `lineno` is the line number where the example starts; both are used for error messages. """ # Get the example's indentation level. indent = len(m.group('indent')) # Divide source into lines; check that they're properly # indented; and then strip their indentation & prompts. source_lines = m.group('source').split('\n') self._check_prompt_blank(source_lines, indent, name, lineno) self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno) source = '\n'.join([sl[indent+4:] for sl in source_lines]) # Divide want into lines; check that it's properly indented; and # then strip the indentation. Spaces before the last newline should # be preserved, so plain rstrip() isn't good enough. want = m.group('want') want_lines = want.split('\n') if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]): del want_lines[-1] # forget final newline & spaces after it self._check_prefix(want_lines, ' '*indent, name, lineno + len(source_lines)) want = '\n'.join([wl[indent:] for wl in want_lines]) # If `want` contains a traceback message, then extract it. m = self._EXCEPTION_RE.match(want) if m: exc_msg = m.group('msg') else: exc_msg = None # Extract options from the source. options = self._find_options(source, name, lineno) return source, options, want, exc_msg # This regular expression looks for option directives in the # source code of an example. Option directives are comments # starting with "doctest:". Warning: this may give false # positives for string-literals that contain the string # "#doctest:". Eliminating these false positives would require # actually parsing the string; but we limit them by ignoring any # line containing "#doctest:" that is *followed* by a quote mark. _OPTION_DIRECTIVE_RE = re.compile(r'#\s*doctest:\s*([^\n\'"]*)$', re.MULTILINE) def _find_options(self, source, name, lineno): """ Return a dictionary containing option overrides extracted from option directives in the given source string. `name` is the string's name, and `lineno` is the line number where the example starts; both are used for error messages. """ options = {} # (note: with the current regexp, this will match at most once:) for m in self._OPTION_DIRECTIVE_RE.finditer(source): option_strings = m.group(1).replace(',', ' ').split() for option in option_strings: if (option[0] not in '+-' or option[1:] not in OPTIONFLAGS_BY_NAME): raise ValueError('line %r of the doctest for %s ' 'has an invalid option: %r' % (lineno+1, name, option)) flag = OPTIONFLAGS_BY_NAME[option[1:]] options[flag] = (option[0] == '+') if options and self._IS_BLANK_OR_COMMENT(source): raise ValueError('line %r of the doctest for %s has an option ' 'directive on a line with no example: %r' % (lineno, name, source)) return options # This regular expression finds the indentation of every non-blank # line in a string. _INDENT_RE = re.compile('^([ ]*)(?=\S)', re.MULTILINE) def _min_indent(self, s): "Return the minimum indentation of any non-blank line in `s`" indents = [len(indent) for indent in self._INDENT_RE.findall(s)] if len(indents) > 0: return min(indents) else: return 0 def _check_prompt_blank(self, lines, indent, name, lineno): """ Given the lines of a source string (including prompts and leading indentation), check to make sure that every prompt is followed by a space character. If any line is not followed by a space character, then raise ValueError. """ for i, line in enumerate(lines): if len(line) >= indent+4 and line[indent+3] != ' ': raise ValueError('line %r of the docstring for %s ' 'lacks blank after %s: %r' % (lineno+i+1, name, line[indent:indent+3], line)) def _check_prefix(self, lines, prefix, name, lineno): """ Check that every line in the given list starts with the given prefix; if any line does not, then raise a ValueError. """ for i, line in enumerate(lines): if line and not line.startswith(prefix): raise ValueError('line %r of the docstring for %s has ' 'inconsistent leading whitespace: %r' % (lineno+i+1, name, line)) ###################################################################### ## 4. DocTest Finder ###################################################################### class DocTestFinder: """ A class used to extract the DocTests that are relevant to a given object, from its docstring and the docstrings of its contained objects. Doctests can currently be extracted from the following object types: modules, functions, classes, methods, staticmethods, classmethods, and properties. """ def __init__(self, verbose=False, parser=DocTestParser(), recurse=True, _namefilter=None, exclude_empty=True): """ Create a new doctest finder. The optional argument `parser` specifies a class or function that should be used to create new DocTest objects (or objects that implement the same interface as DocTest). The signature for this factory function should match the signature of the DocTest constructor. If the optional argument `recurse` is false, then `find` will only examine the given object, and not any contained objects. If the optional argument `exclude_empty` is false, then `find` will include tests for objects with empty docstrings. """ self._parser = parser self._verbose = verbose self._recurse = recurse self._exclude_empty = exclude_empty # _namefilter is undocumented, and exists only for temporary backward- # compatibility support of testmod's deprecated isprivate mess. self._namefilter = _namefilter def find(self, obj, name=None, module=None, globs=None, extraglobs=None, optionflags=0): """ Return a list of the DocTests that are defined by the given object's docstring, or by any of its contained objects' docstrings. The optional parameter `module` is the module that contains the given object. If the module is not specified or is None, then the test finder will attempt to automatically determine the correct module. The object's module is used: - As a default namespace, if `globs` is not specified. - To prevent the DocTestFinder from extracting DocTests from objects that are imported from other modules. - To find the name of the file containing the object. - To help find the line number of the object within its file. Contained objects whose module does not match `module` are ignored. If `module` is False, no attempt to find the module will be made. This is obscure, of use mostly in tests: if `module` is False, or is None but cannot be found automatically, then all objects are considered to belong to the (non-existent) module, so all contained objects will (recursively) be searched for doctests. The globals for each DocTest is formed by combining `globs` and `extraglobs` (bindings in `extraglobs` override bindings in `globs`). A new copy of the globals dictionary is created for each DocTest. If `globs` is not specified, then it defaults to the module's `__dict__`, if specified, or {} otherwise. If `extraglobs` is not specified, then it defaults to {}. """ # If name was not specified, then extract it from the object. if name is None: name = getattr(obj, '__name__', None) if name is None: raise ValueError("DocTestFinder.find: name must be given " "when obj.__name__ doesn't exist: %r" % (type(obj),)) # Find the module that contains the given object (if obj is # a module, then module=obj.). Note: this may fail, in which # case module will be None. if module is False: module = None elif module is None: module = inspect.getmodule(obj) # Read the module's source code. This is used by # DocTestFinder._find_lineno to find the line number for a # given object's docstring. try: file = inspect.getsourcefile(obj) or inspect.getfile(obj) source_lines = linecache.getlines(file) if not source_lines: source_lines = None except TypeError: source_lines = None # Initialize globals, and merge in extraglobs. if globs is None: if module is None: globs = {} else: globs = module.__dict__.copy() else: globs = globs.copy() if extraglobs is not None: globs.update(extraglobs) # Recursively expore `obj`, extracting DocTests. tests = [] self._find(tests, obj, name, module, source_lines, globs, {}, optionflags=optionflags) return tests def _filter(self, obj, prefix, base): """ Return true if the given object should not be examined. """ return (self._namefilter is not None and self._namefilter(prefix, base)) def _from_module(self, module, object): """ Return true if the given object is defined in the given module. """ if module is None: return True elif inspect.isfunction(object): return module.__dict__ is object.func_globals elif inspect.isclass(object): return module.__name__ == object.__module__ elif inspect.getmodule(object) is not None: return module is inspect.getmodule(object) elif hasattr(object, '__module__'): return module.__name__ == object.__module__ elif isinstance(object, property): return True # [XX] no way not be sure. else: raise ValueError("object must be a class or function") def _find(self, tests, obj, name, module, source_lines, globs, seen, optionflags): """ Find tests for the given object and any contained objects, and add them to `tests`. """ if self._verbose: print 'Finding tests in %s' % name # If we've already processed this object, then ignore it. if id(obj) in seen: return seen[id(obj)] = 1 # Find a test for this object, and add it to the list of tests. test = self._get_test(obj, name, module, globs, source_lines, optionflags) if test is not None: tests.append(test) # Look for tests in a module's contained objects. if inspect.ismodule(obj) and self._recurse: for valname, val in obj.__dict__.items(): # Check if this contained object should be ignored. if self._filter(val, name, valname): continue valname = '%s.%s' % (name, valname) # Recurse to functions & classes. if ((inspect.isfunction(val) or inspect.isclass(val)) and self._from_module(module, val)): self._find(tests, val, valname, module, source_lines, globs, seen, optionflags) # Look for tests in a module's __test__ dictionary. if inspect.ismodule(obj) and self._recurse: for valname, val in getattr(obj, '__test__', {}).items(): if not isinstance(valname, basestring): raise ValueError("DocTestFinder.find: __test__ keys " "must be strings: %r" % (type(valname),)) if not (inspect.isfunction(val) or inspect.isclass(val) or inspect.ismethod(val) or inspect.ismodule(val) or isinstance(val, basestring)): raise ValueError("DocTestFinder.find: __test__ values " "must be strings, functions, methods, " "classes, or modules: %r" % (type(val),)) valname = '%s.__test__.%s' % (name, valname) self._find(tests, val, valname, module, source_lines, globs, seen, optionflags) # Look for tests in a class's contained objects. if inspect.isclass(obj) and self._recurse: for valname, val in obj.__dict__.items(): # Check if this contained object should be ignored. if self._filter(val, name, valname): continue # Special handling for staticmethod/classmethod. if isinstance(val, staticmethod): val = getattr(obj, valname) if isinstance(val, classmethod): val = getattr(obj, valname).im_func # Recurse to methods, properties, and nested classes. if ((inspect.isfunction(val) or inspect.isclass(val) or isinstance(val, property)) and self._from_module(module, val)): valname = '%s.%s' % (name, valname) self._find(tests, val, valname, module, source_lines, globs, seen, optionflags) def _get_test(self, obj, name, module, globs, source_lines, optionflags): """ Return a DocTest for the given object, if it defines a docstring; otherwise, return None. """ # Extract the object's docstring. If it doesn't have one, # then return None (no test for this object). if isinstance(obj, basestring): docstring = obj else: try: if obj.__doc__ is None: docstring = '' else: docstring = obj.__doc__ if not isinstance(docstring, basestring): docstring = str(docstring) except (TypeError, AttributeError): docstring = '' # Find the docstring's location in the file. lineno = self._find_lineno(obj, source_lines) # Don't bother if the docstring is empty. if self._exclude_empty and not docstring: return None # Return a DocTest for this object. if module is None: filename = None else: filename = getattr(module, '__file__', module.__name__) if filename[-4:] in (".pyc", ".pyo"): filename = filename[:-1] return self._parser.get_doctest(docstring, globs, name, filename, lineno, optionflags) def _find_lineno(self, obj, source_lines): """ Return a line number of the given object's docstring. Note: this method assumes that the object has a docstring. """ lineno = None # Find the line number for modules. if inspect.ismodule(obj): lineno = 0 # Find the line number for classes. # Note: this could be fooled if a class is defined multiple # times in a single file. if inspect.isclass(obj): if source_lines is None: return None pat = re.compile(r'^\s*class\s*%s\b' % getattr(obj, '__name__', '-')) for i, line in enumerate(source_lines): if pat.match(line): lineno = i break # Find the line number for functions & methods. if inspect.ismethod(obj): obj = obj.im_func if inspect.isfunction(obj): obj = obj.func_code if inspect.istraceback(obj): obj = obj.tb_frame if inspect.isframe(obj): obj = obj.f_code if inspect.iscode(obj): lineno = getattr(obj, 'co_firstlineno', None)-1 # Find the line number where the docstring starts. Assume # that it's the first line that begins with a quote mark. # Note: this could be fooled by a multiline function # signature, where a continuation line begins with a quote # mark. if lineno is not None: if source_lines is None: return lineno+1 pat = re.compile('(^|.*:)\s*\w*("|\')') for lineno in range(lineno, len(source_lines)): if pat.match(source_lines[lineno]): return lineno # We couldn't find the line number. return None ###################################################################### ## 5. DocTest Runner ###################################################################### class DocTestRunner: """ A class used to run DocTest test cases, and accumulate statistics. The `run` method is used to process a single DocTest case. It returns a tuple `(f, t)`, where `t` is the number of test cases tried, and `f` is the number of test cases that failed. >>> tests = DocTestFinder().find(_TestClass) >>> runner = DocTestRunner(verbose=False) >>> for test in tests: ... print runner.run(test) (0, 2) (0, 1) (0, 2) (0, 2) The `summarize` method prints a summary of all the test cases that have been run by the runner, and returns an aggregated `(f, t)` tuple: >>> runner.summarize(verbose=1) 4 items passed all tests: 2 tests in _TestClass 2 tests in _TestClass.__init__ 2 tests in _TestClass.get 1 tests in _TestClass.square 7 tests in 4 items. 7 passed and 0 failed. Test passed. (0, 7) The aggregated number of tried examples and failed examples is also available via the `tries` and `failures` attributes: >>> runner.tries 7 >>> runner.failures 0 The comparison between expected outputs and actual outputs is done by an `OutputChecker`. This comparison may be customized with a number of option flags; see the documentation for `testmod` for more information. If the option flags are insufficient, then the comparison may also be customized by passing a subclass of `OutputChecker` to the constructor. The test runner's display output can be controlled in two ways. First, an output function (`out) can be passed to `TestRunner.run`; this function will be called with strings that should be displayed. It defaults to `sys.stdout.write`. If capturing the output is not sufficient, then the display output can be also customized by subclassing DocTestRunner, and overriding the methods `report_start`, `report_success`, `report_unexpected_exception`, and `report_failure`. """ # This divider string is used to separate failure messages, and to # separate sections of the summary. DIVIDER = "*" * 70 def __init__(self, checker=None, verbose=None, optionflags=0): """ Create a new test runner. Optional keyword arg `checker` is the `OutputChecker` that should be used to compare the expected outputs and actual outputs of doctest examples. Optional keyword arg 'verbose' prints lots of stuff if true, only failures if false; by default, it's true iff '-v' is in sys.argv. Optional argument `optionflags` can be used to control how the test runner compares expected output to actual output, and how it displays failures. See the documentation for `testmod` for more information. """ self._checker = checker or OutputChecker() if verbose is None: verbose = '-v' in sys.argv self._verbose = verbose self.optionflags = optionflags self.original_optionflags = optionflags # Keep track of the examples we've run. self.tries = 0 self.failures = 0 self._name2ft = {} # Create a fake output target for capturing doctest output. self._fakeout = _SpoofOut() #///////////////////////////////////////////////////////////////// # Reporting methods #///////////////////////////////////////////////////////////////// def report_start(self, out, test, example): """ Report that the test runner is about to process the given example. (Only displays a message if verbose=True) """ if self._verbose: if example.want: out('Trying:\n' + _indent(example.source) + 'Expecting:\n' + _indent(example.want)) else: out('Trying:\n' + _indent(example.source) + 'Expecting nothing\n') def report_success(self, out, test, example, got): """ Report that the given example ran successfully. (Only displays a message if verbose=True) """ if self._verbose: out("ok\n") def report_failure(self, out, test, example, got): """ Report that the given example failed. """ out(self._failure_header(test, example) + self._checker.output_difference(example, got, self.optionflags)) def report_unexpected_exception(self, out, test, example, exc_info): """ Report that the given example raised an unexpected exception. """ out(self._failure_header(test, example) + 'Exception raised:\n' + _indent(_exception_traceback(exc_info))) def _failure_header(self, test, example): out = [self.DIVIDER] if test.filename: if test.lineno is not None and example.lineno is not None: lineno = test.lineno + example.lineno + 1 else: lineno = '?' out.append('File "%s", line %s, in %s' % (test.filename, lineno, test.name)) else: out.append('Line %s, in %s' % (example.lineno+1, test.name)) out.append('Failed example:') source = example.source out.append(_indent(source)) return '\n'.join(out) #///////////////////////////////////////////////////////////////// # DocTest Running #///////////////////////////////////////////////////////////////// def __run(self, test, compileflags, out): """ Run the examples in `test`. Write the outcome of each example with one of the `DocTestRunner.report_*` methods, using the writer function `out`. `compileflags` is the set of compiler flags that should be used to execute examples. Return a tuple `(f, t)`, where `t` is the number of examples tried, and `f` is the number of examples that failed. The examples are run in the namespace `test.globs`. """ # Keep track of the number of failures and tries. failures = tries = 0 # Save the option flags (since option directives can be used # to modify them). original_optionflags = self.optionflags SUCCESS, FAILURE, BOOM = range(3) # `outcome` state check = self._checker.check_output # Process each example. for examplenum, example in enumerate(test.examples): # If REPORT_ONLY_FIRST_FAILURE is set, then supress # reporting after the first failure. quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and failures > 0) # Merge in the example's options. self.optionflags = original_optionflags if example.options: for (optionflag, val) in example.options.items(): if val: self.optionflags |= optionflag else: self.optionflags &= ~optionflag # Record that we started this example. tries += 1 if not quiet: self.report_start(out, test, example) # Use a special filename for compile(), so we can retrieve # the source code during interactive debugging (see # __patched_linecache_getlines). filename = '' % (test.name, examplenum) # Run the example in the given context (globs), and record # any exception that gets raised. (But don't intercept # keyboard interrupts.) try: # Don't blink! This is where the user's code gets run. exec compile(example.source, filename, "single", compileflags, 1) in test.globs self.debugger.set_continue() # ==== Example Finished ==== exception = None except KeyboardInterrupt: raise except: exception = sys.exc_info() self.debugger.set_continue() # ==== Example Finished ==== got = self._fakeout.getvalue() # the actual output self._fakeout.truncate(0) outcome = FAILURE # guilty until proved innocent or insane # If the example executed without raising any exceptions, # verify its output. if exception is None: if check(example.want, got, self.optionflags): outcome = SUCCESS # The example raised an exception: check if it was expected. else: exc_info = sys.exc_info() exc_msg = traceback.format_exception_only(*exc_info[:2])[-1] if not quiet: got += _exception_traceback(exc_info) # If `example.exc_msg` is None, then we weren't expecting # an exception. if example.exc_msg is None: outcome = BOOM # We expected an exception: see whether it matches. elif check(example.exc_msg, exc_msg, self.optionflags): outcome = SUCCESS # Another chance if they didn't care about the detail. elif self.optionflags & IGNORE_EXCEPTION_DETAIL: m1 = re.match(r'[^:]*:', example.exc_msg) m2 = re.match(r'[^:]*:', exc_msg) if m1 and m2 and check(m1.group(0), m2.group(0), self.optionflags): outcome = SUCCESS # Report the outcome. if outcome is SUCCESS: if not quiet: self.report_success(out, test, example, got) elif outcome is FAILURE: if not quiet: self.report_failure(out, test, example, got) failures += 1 elif outcome is BOOM: if not quiet: self.report_unexpected_exception(out, test, example, exc_info) failures += 1 else: assert False, ("unknown outcome", outcome) # Restore the option flags (in case they were modified) self.optionflags = original_optionflags # Record and return the number of failures and tries. self.__record_outcome(test, failures, tries) return failures, tries def __record_outcome(self, test, f, t): """ Record the fact that the given DocTest (`test`) generated `f` failures out of `t` tried examples. """ f2, t2 = self._name2ft.get(test.name, (0,0)) self._name2ft[test.name] = (f+f2, t+t2) self.failures += f self.tries += t __LINECACHE_FILENAME_RE = re.compile(r'[\w\.]+)' r'\[(?P\d+)\]>$') def __patched_linecache_getlines(self, filename, module_globals=None): m = self.__LINECACHE_FILENAME_RE.match(filename) if m and m.group('name') == self.test.name: example = self.test.examples[int(m.group('examplenum'))] return example.source.splitlines(True) else: if module_globals is None: return self.save_linecache_getlines(filename) else: return self.save_linecache_getlines(filename, module_globals) def run(self, test, compileflags=None, out=None, clear_globs=True): """ Run the examples in `test`, and display the results using the writer function `out`. The examples are run in the namespace `test.globs`. If `clear_globs` is true (the default), then this namespace will be cleared after the test runs, to help with garbage collection. If you would like to examine the namespace after the test completes, then use `clear_globs=False`. `compileflags` gives the set of flags that should be used by the Python compiler when running the examples. If not specified, then it will default to the set of future-import flags that apply to `globs`. The output of each example is checked using `DocTestRunner.check_output`, and the results are formatted by the `DocTestRunner.report_*` methods. """ self.test = test if compileflags is None: compileflags = _extract_future_flags(test.globs) save_stdout = sys.stdout if out is None: out = save_stdout.write sys.stdout = self._fakeout # Patch pdb.set_trace to restore sys.stdout during interactive # debugging (so it's not still redirected to self._fakeout). # Note that the interactive output will go to *our* # save_stdout, even if that's not the real sys.stdout; this # allows us to write test cases for the set_trace behavior. save_set_trace = pdb.set_trace self.debugger = _OutputRedirectingPdb(save_stdout) self.debugger.reset() pdb.set_trace = self.debugger.set_trace # Patch linecache.getlines, so we can see the example's source # when we're inside the debugger. self.save_linecache_getlines = linecache.getlines linecache.getlines = self.__patched_linecache_getlines try: return self.__run(test, compileflags, out) finally: sys.stdout = save_stdout pdb.set_trace = save_set_trace linecache.getlines = self.save_linecache_getlines if clear_globs: test.globs.clear() #///////////////////////////////////////////////////////////////// # Summarization #///////////////////////////////////////////////////////////////// def summarize(self, verbose=None): """ Print a summary of all the test cases that have been run by this DocTestRunner, and return a tuple `(f, t)`, where `f` is the total number of failed examples, and `t` is the total number of tried examples. The optional `verbose` argument controls how detailed the summary is. If the verbosity is not specified, then the DocTestRunner's verbosity is used. """ if verbose is None: verbose = self._verbose notests = [] passed = [] failed = [] totalt = totalf = 0 for x in self._name2ft.items(): name, (f, t) = x assert f <= t totalt += t totalf += f if t == 0: notests.append(name) elif f == 0: passed.append( (name, t) ) else: failed.append(x) if verbose: if notests: print len(notests), "items had no tests:" notests.sort() for thing in notests: print " ", thing if passed: print len(passed), "items passed all tests:" passed.sort() for thing, count in passed: print " %3d tests in %s" % (count, thing) if failed: print self.DIVIDER print len(failed), "items had failures:" failed.sort() for thing, (f, t) in failed: print " %3d of %3d in %s" % (f, t, thing) if verbose: print totalt, "tests in", len(self._name2ft), "items." print totalt - totalf, "passed and", totalf, "failed." if totalf: print "***Test Failed***", totalf, "failures." elif verbose: print "Test passed." return totalf, totalt #///////////////////////////////////////////////////////////////// # Backward compatibility cruft to maintain doctest.master. #///////////////////////////////////////////////////////////////// def merge(self, other): d = self._name2ft for name, (f, t) in other._name2ft.items(): if name in d: print "*** DocTestRunner.merge: '" + name + "' in both" \ " testers; summing outcomes." f2, t2 = d[name] f = f + f2 t = t + t2 d[name] = f, t class OutputChecker: """ A class used to check the whether the actual output from a doctest example matches the expected output. `OutputChecker` defines two methods: `check_output`, which compares a given pair of outputs, and returns true if they match; and `output_difference`, which returns a string describing the differences between two outputs. """ def check_output(self, want, got, optionflags): """ Return True iff the actual output from an example (`got`) matches the expected output (`want`). These strings are always considered to match if they are identical; but depending on what option flags the test runner is using, several non-exact match types are also possible. See the documentation for `TestRunner` for more information about option flags. """ # Handle the common case first, for efficiency: # if they're string-identical, always return true. if got == want: return True # The values True and False replaced 1 and 0 as the return # value for boolean comparisons in Python 2.3. if not (optionflags & DONT_ACCEPT_TRUE_FOR_1): if (got,want) == ("True\n", "1\n"): return True if (got,want) == ("False\n", "0\n"): return True # can be used as a special sequence to signify a # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used. if not (optionflags & DONT_ACCEPT_BLANKLINE): # Replace in want with a blank line. want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER), '', want) # If a line in got contains only spaces, then remove the # spaces. got = re.sub('(?m)^\s*?$', '', got) if got == want: return True # This flag causes doctest to ignore any differences in the # contents of whitespace strings. Note that this can be used # in conjunction with the ELLIPSIS flag. if optionflags & NORMALIZE_WHITESPACE: got = ' '.join(got.split()) want = ' '.join(want.split()) if got == want: return True # The ELLIPSIS flag says to let the sequence "..." in `want` # match any substring in `got`. if optionflags & ELLIPSIS: if _ellipsis_match(want, got): return True # We didn't find any match; return false. return False # Should we do a fancy diff? def _do_a_fancy_diff(self, want, got, optionflags): # Not unless they asked for a fancy diff. if not optionflags & (REPORT_UDIFF | REPORT_CDIFF | REPORT_NDIFF): return False # If expected output uses ellipsis, a meaningful fancy diff is # too hard ... or maybe not. In two real-life failures Tim saw, # a diff was a major help anyway, so this is commented out. # [todo] _ellipsis_match() knows which pieces do and don't match, # and could be the basis for a kick-ass diff in this case. ##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want: ## return False # ndiff does intraline difference marking, so can be useful even # for 1-line differences. if optionflags & REPORT_NDIFF: return True # The other diff types need at least a few lines to be helpful. return want.count('\n') > 2 and got.count('\n') > 2 def output_difference(self, example, got, optionflags): """ Return a string describing the differences between the expected output for a given example (`example`) and the actual output (`got`). `optionflags` is the set of option flags used to compare `want` and `got`. """ want = example.want # If s are being used, then replace blank lines # with in the actual output string. if not (optionflags & DONT_ACCEPT_BLANKLINE): got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got) # Check if we should use diff. if self._do_a_fancy_diff(want, got, optionflags): # Split want & got into lines. want_lines = want.splitlines(True) # True == keep line ends got_lines = got.splitlines(True) # Use difflib to find their differences. if optionflags & REPORT_UDIFF: diff = difflib.unified_diff(want_lines, got_lines, n=2) diff = list(diff)[2:] # strip the diff header kind = 'unified diff with -expected +actual' elif optionflags & REPORT_CDIFF: diff = difflib.context_diff(want_lines, got_lines, n=2) diff = list(diff)[2:] # strip the diff header kind = 'context diff with expected followed by actual' elif optionflags & REPORT_NDIFF: engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK) diff = list(engine.compare(want_lines, got_lines)) kind = 'ndiff with -expected +actual' else: assert 0, 'Bad diff option' # Remove trailing whitespace on diff output. diff = [line.rstrip() + '\n' for line in diff] return 'Differences (%s):\n' % kind + _indent(''.join(diff)) # If we're not using diff, then simply list the expected # output followed by the actual output. if want and got: return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got)) elif want: return 'Expected:\n%sGot nothing\n' % _indent(want) elif got: return 'Expected nothing\nGot:\n%s' % _indent(got) else: return 'Expected nothing\nGot nothing\n' class DocTestFailure(Exception): """A DocTest example has failed in debugging mode. The exception instance has variables: - test: the DocTest object being run - excample: the Example object that failed - got: the actual output """ def __init__(self, test, example, got): self.test = test self.example = example self.got = got def __str__(self): return str(self.test) class UnexpectedException(Exception): """A DocTest example has encountered an unexpected exception The exception instance has variables: - test: the DocTest object being run - excample: the Example object that failed - exc_info: the exception info """ def __init__(self, test, example, exc_info): self.test = test self.example = example self.exc_info = exc_info def __str__(self): return str(self.test) class DebugRunner(DocTestRunner): r"""Run doc tests but raise an exception as soon as there is a failure. If an unexpected exception occurs, an UnexpectedException is raised. It contains the test, the example, and the original exception: >>> runner = DebugRunner(verbose=False) >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42', ... {}, 'foo', 'foo.py', 0) >>> try: ... runner.run(test) ... except UnexpectedException, failure: ... pass >>> failure.test is test True >>> failure.example.want '42\n' >>> exc_info = failure.exc_info >>> raise exc_info[0], exc_info[1], exc_info[2] Traceback (most recent call last): ... KeyError We wrap the original exception to give the calling application access to the test and example information. If the output doesn't match, then a DocTestFailure is raised: >>> test = DocTestParser().get_doctest(''' ... >>> x = 1 ... >>> x ... 2 ... ''', {}, 'foo', 'foo.py', 0) >>> try: ... runner.run(test) ... except DocTestFailure, failure: ... pass DocTestFailure objects provide access to the test: >>> failure.test is test True As well as to the example: >>> failure.example.want '2\n' and the actual output: >>> failure.got '1\n' If a failure or error occurs, the globals are left intact: >>> del test.globs['__builtins__'] >>> test.globs {'x': 1} >>> test = DocTestParser().get_doctest(''' ... >>> x = 2 ... >>> raise KeyError ... ''', {}, 'foo', 'foo.py', 0) >>> runner.run(test) Traceback (most recent call last): ... UnexpectedException: >>> del test.globs['__builtins__'] >>> test.globs {'x': 2} But the globals are cleared if there is no error: >>> test = DocTestParser().get_doctest(''' ... >>> x = 2 ... ''', {}, 'foo', 'foo.py', 0) >>> runner.run(test) (0, 1) >>> test.globs {} """ def run(self, test, compileflags=None, out=None, clear_globs=True): r = DocTestRunner.run(self, test, compileflags, out, False) if clear_globs: test.globs.clear() return r def report_unexpected_exception(self, out, test, example, exc_info): raise UnexpectedException(test, example, exc_info) def report_failure(self, out, test, example, got): raise DocTestFailure(test, example, got) ###################################################################### ## 6. Test Functions ###################################################################### # These should be backwards compatible. # For backward compatibility, a global instance of a DocTestRunner # class, updated by testmod. master = None def testmod(m=None, name=None, globs=None, verbose=None, isprivate=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, exclude_empty=False): """m=None, name=None, globs=None, verbose=None, isprivate=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, exclude_empty=False Test examples in docstrings in functions and classes reachable from module m (or the current module if m is not supplied), starting with m.__doc__. Unless isprivate is specified, private names are not skipped. Also test examples reachable from dict m.__test__ if it exists and is not None. m.__test__ maps names to functions, classes and strings; function and class docstrings are tested even if the name is private; strings are tested directly, as if they were docstrings. Return (#failures, #tests). See doctest.__doc__ for an overview. Optional keyword arg "name" gives the name of the module; by default use m.__name__. Optional keyword arg "globs" gives a dict to be used as the globals when executing examples; by default, use m.__dict__. A copy of this dict is actually used for each docstring, so that each docstring's examples start with a clean slate. Optional keyword arg "extraglobs" gives a dictionary that should be merged into the globals that are used to execute examples. By default, no extra globals are used. This is new in 2.4. Optional keyword arg "verbose" prints lots of stuff if true, prints only failures if false; by default, it's true iff "-v" is in sys.argv. Optional keyword arg "report" prints a summary at the end when true, else prints nothing at the end. In verbose mode, the summary is detailed, else very brief (in fact, empty if all tests passed). Optional keyword arg "optionflags" or's together module constants, and defaults to 0. This is new in 2.3. Possible values (see the docs for details): DONT_ACCEPT_TRUE_FOR_1 DONT_ACCEPT_BLANKLINE NORMALIZE_WHITESPACE ELLIPSIS IGNORE_EXCEPTION_DETAIL REPORT_UDIFF REPORT_CDIFF REPORT_NDIFF REPORT_ONLY_FIRST_FAILURE Optional keyword arg "raise_on_error" raises an exception on the first unexpected exception or failure. This allows failures to be post-mortem debugged. Deprecated in Python 2.4: Optional keyword arg "isprivate" specifies a function used to determine whether a name is private. The default function is treat all functions as public. Optionally, "isprivate" can be set to doctest.is_private to skip over functions marked as private using the underscore naming convention; see its docs for details. Advanced tomfoolery: testmod runs methods of a local instance of class doctest.Tester, then merges the results into (or creates) global Tester instance doctest.master. Methods of doctest.master can be called directly too, if you want to do something unusual. Passing report=0 to testmod is especially useful then, to delay displaying a summary. Invoke doctest.master.summarize(verbose) when you're done fiddling. """ global master if isprivate is not None: warnings.warn("the isprivate argument is deprecated; " "examine DocTestFinder.find() lists instead", DeprecationWarning) # If no module was given, then use __main__. if m is None: # DWA - m will still be None if this wasn't invoked from the command # line, in which case the following TypeError is about as good an error # as we should expect m = sys.modules.get('__main__') # Check that we were actually given a module. if not inspect.ismodule(m): raise TypeError("testmod: module required; %r" % (m,)) # If no name was given, then use the module's name. if name is None: name = m.__name__ # Find, parse, and run all tests in the given module. finder = DocTestFinder(_namefilter=isprivate, exclude_empty=exclude_empty) if raise_on_error: runner = DebugRunner(verbose=verbose, optionflags=optionflags) else: runner = DocTestRunner(verbose=verbose, optionflags=optionflags) for test in finder.find(m, name, globs=globs, extraglobs=extraglobs): runner.run(test) if report: runner.summarize() if master is None: master = runner else: master.merge(runner) return runner.failures, runner.tries def testfile(filename, module_relative=True, name=None, package=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, parser=DocTestParser(), encoding=None): """ Test examples in the given file. Return (#failures, #tests). Optional keyword arg "module_relative" specifies how filenames should be interpreted: - If "module_relative" is True (the default), then "filename" specifies a module-relative path. By default, this path is relative to the calling module's directory; but if the "package" argument is specified, then it is relative to that package. To ensure os-independence, "filename" should use "/" characters to separate path segments, and should not be an absolute path (i.e., it may not begin with "/"). - If "module_relative" is False, then "filename" specifies an os-specific path. The path may be absolute or relative (to the current working directory). Optional keyword arg "name" gives the name of the test; by default use the file's basename. Optional keyword argument "package" is a Python package or the name of a Python package whose directory should be used as the base directory for a module relative filename. If no package is specified, then the calling module's directory is used as the base directory for module relative filenames. It is an error to specify "package" if "module_relative" is False. Optional keyword arg "globs" gives a dict to be used as the globals when executing examples; by default, use {}. A copy of this dict is actually used for each docstring, so that each docstring's examples start with a clean slate. Optional keyword arg "extraglobs" gives a dictionary that should be merged into the globals that are used to execute examples. By default, no extra globals are used. Optional keyword arg "verbose" prints lots of stuff if true, prints only failures if false; by default, it's true iff "-v" is in sys.argv. Optional keyword arg "report" prints a summary at the end when true, else prints nothing at the end. In verbose mode, the summary is detailed, else very brief (in fact, empty if all tests passed). Optional keyword arg "optionflags" or's together module constants, and defaults to 0. Possible values (see the docs for details): DONT_ACCEPT_TRUE_FOR_1 DONT_ACCEPT_BLANKLINE NORMALIZE_WHITESPACE ELLIPSIS IGNORE_EXCEPTION_DETAIL REPORT_UDIFF REPORT_CDIFF REPORT_NDIFF REPORT_ONLY_FIRST_FAILURE Optional keyword arg "raise_on_error" raises an exception on the first unexpected exception or failure. This allows failures to be post-mortem debugged. Optional keyword arg "parser" specifies a DocTestParser (or subclass) that should be used to extract tests from the files. Optional keyword arg "encoding" specifies an encoding that should be used to convert the file to unicode. Advanced tomfoolery: testmod runs methods of a local instance of class doctest.Tester, then merges the results into (or creates) global Tester instance doctest.master. Methods of doctest.master can be called directly too, if you want to do something unusual. Passing report=0 to testmod is especially useful then, to delay displaying a summary. Invoke doctest.master.summarize(verbose) when you're done fiddling. """ global master if package and not module_relative: raise ValueError("Package may only be specified for module-" "relative paths.") # Relativize the path if module_relative: package = _normalize_module(package) filename = _module_relative_path(package, filename) # If no name was given, then use the file's name. if name is None: name = os.path.basename(filename) # Assemble the globals. if globs is None: globs = {} else: globs = globs.copy() if extraglobs is not None: globs.update(extraglobs) if raise_on_error: runner = DebugRunner(verbose=verbose, optionflags=optionflags) else: runner = DocTestRunner(verbose=verbose, optionflags=optionflags) # Read the file, convert it to a test, and run it. s = open(filename).read() if encoding is None: encoding = pep263_encoding(s) if encoding is not None: s = s.decode(encoding) test = parser.get_doctest(s, globs, name, filename, 0) runner.run(test) if report: runner.summarize() if master is None: master = runner else: master.merge(runner) return runner.failures, runner.tries pep263_re_search = re.compile("coding[:=]\s*([-\w.]+)").search def pep263_encoding(s): """Try to find the encoding of a string by looking for a pep263 coding. """ for line in s.split('\n')[:2]: r = pep263_re_search(line) if r: return r.group(1) def run_docstring_examples(f, globs, verbose=False, name="NoName", compileflags=None, optionflags=0): """ Test examples in the given object's docstring (`f`), using `globs` as globals. Optional argument `name` is used in failure messages. If the optional argument `verbose` is true, then generate output even if there are no failures. `compileflags` gives the set of flags that should be used by the Python compiler when running the examples. If not specified, then it will default to the set of future-import flags that apply to `globs`. Optional keyword arg `optionflags` specifies options for the testing and output. See the documentation for `testmod` for more information. """ # Find, parse, and run all tests in the given module. finder = DocTestFinder(verbose=verbose, recurse=False) runner = DocTestRunner(verbose=verbose, optionflags=optionflags) for test in finder.find(f, name, globs=globs): runner.run(test, compileflags=compileflags) ###################################################################### ## 7. Tester ###################################################################### # This is provided only for backwards compatibility. It's not # actually used in any way. class Tester: def __init__(self, mod=None, globs=None, verbose=None, isprivate=None, optionflags=0): warnings.warn("class Tester is deprecated; " "use class doctest.DocTestRunner instead", DeprecationWarning, stacklevel=2) if mod is None and globs is None: raise TypeError("Tester.__init__: must specify mod or globs") if mod is not None and not inspect.ismodule(mod): raise TypeError("Tester.__init__: mod must be a module; %r" % (mod,)) if globs is None: globs = mod.__dict__ self.globs = globs self.verbose = verbose self.isprivate = isprivate self.optionflags = optionflags self.testfinder = DocTestFinder(_namefilter=isprivate) self.testrunner = DocTestRunner(verbose=verbose, optionflags=optionflags) def runstring(self, s, name): test = DocTestParser().get_doctest(s, self.globs, name, None, None, self.optionflags) if self.verbose: print "Running string", name (f,t) = self.testrunner.run(test) if self.verbose: print f, "of", t, "examples failed in string", name return (f,t) def rundoc(self, object, name=None, module=None): f = t = 0 tests = self.testfinder.find(object, name, module=module, globs=self.globs) for test in tests: (f2, t2) = self.testrunner.run(test) (f,t) = (f+f2, t+t2) return (f,t) def rundict(self, d, name, module=None): import new m = new.module(name) m.__dict__.update(d) if module is None: module = False return self.rundoc(m, name, module) def run__test__(self, d, name): import new m = new.module(name) m.__test__ = d return self.rundoc(m, name) def summarize(self, verbose=None): return self.testrunner.summarize(verbose) def merge(self, other): self.testrunner.merge(other.testrunner) ###################################################################### ## 8. Unittest Support ###################################################################### _unittest_reportflags = 0 def set_unittest_reportflags(flags): """Sets the unittest option flags. The old flag is returned so that a runner could restore the old value if it wished to: >>> old = _unittest_reportflags >>> set_unittest_reportflags(REPORT_NDIFF | ... REPORT_ONLY_FIRST_FAILURE) == old True # XXX this test fails and I didn't do it, so just commenting it out (JBY). # >>> import doctest # >>> doctest._unittest_reportflags == (REPORT_NDIFF | # ... REPORT_ONLY_FIRST_FAILURE) # True Only reporting flags can be set: >>> set_unittest_reportflags(ELLIPSIS) Traceback (most recent call last): ... ValueError: ('Only reporting flags allowed', 8) >>> set_unittest_reportflags(old) == (REPORT_NDIFF | ... REPORT_ONLY_FIRST_FAILURE) True """ global _unittest_reportflags if (flags & REPORTING_FLAGS) != flags: raise ValueError("Only reporting flags allowed", flags) old = _unittest_reportflags _unittest_reportflags = flags return old _para_re = re.compile(r'\s*\n\s*\n\s*') def _unittest_count(docstring): words = 0 count = 0 for p in _para_re.split(docstring): p = p.strip() if not p: continue if p.startswith('>>> '): if words: count += 1 words = 0 else: words = 1 return count or 1 class DocTestFailureException(AssertionError): """Use custom exception for doctest unit test failures """ class DocTestCase(unittest.TestCase): def __init__(self, test, optionflags=0, setUp=None, tearDown=None, checker=None): unittest.TestCase.__init__(self) self._dt_optionflags = optionflags self._dt_checker = checker self._dt_test = test self._dt_globs = test.globs.copy() self._dt_setUp = setUp self._dt_tearDown = tearDown self._dt_count = _unittest_count(test.docstring) def countTestCases(self): return self._dt_count def setUp(self): test = self._dt_test if self._dt_setUp is not None: self._dt_setUp(test) def tearDown(self): test = self._dt_test if self._dt_tearDown is not None: self._dt_tearDown(test) # restore the original globs test.globs.clear() test.globs.update(self._dt_globs) failureException = DocTestFailureException def runTest(self): test = self._dt_test old = sys.stdout new = StringIO() optionflags = self._dt_optionflags if not (optionflags & REPORTING_FLAGS): # The option flags don't include any reporting flags, # so add the default reporting flags optionflags |= _unittest_reportflags runner = DocTestRunner(optionflags=optionflags, checker=self._dt_checker, verbose=False) try: runner.DIVIDER = "-"*70 failures, tries = runner.run( test, out=new.write, clear_globs=False) finally: sys.stdout = old if failures: raise self.failureException(self.format_failure(new.getvalue())) def format_failure(self, err): test = self._dt_test if test.lineno is None: lineno = 'unknown line number' else: lineno = '%s' % test.lineno lname = '.'.join(test.name.split('.')[-1:]) return ('Failed doctest test for %s\n' ' File "%s", line %s, in %s\n\n%s' % (test.name, test.filename, lineno, lname, err) ) def debug(self): r"""Run the test case without results and without catching exceptions The unit test framework includes a debug method on test cases and test suites to support post-mortem debugging. The test code is run in such a way that errors are not caught. This way a caller can catch the errors and initiate post-mortem debugging. The DocTestCase provides a debug method that raises UnexpectedException errors if there is an unexepcted exception: >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42', ... {}, 'foo', 'foo.py', 0) >>> case = DocTestCase(test) >>> try: ... case.debug() ... except UnexpectedException, failure: ... pass The UnexpectedException contains the test, the example, and the original exception: >>> failure.test is test True >>> failure.example.want '42\n' >>> exc_info = failure.exc_info >>> raise exc_info[0], exc_info[1], exc_info[2] Traceback (most recent call last): ... KeyError If the output doesn't match, then a DocTestFailure is raised: >>> test = DocTestParser().get_doctest(''' ... >>> x = 1 ... >>> x ... 2 ... ''', {}, 'foo', 'foo.py', 0) >>> case = DocTestCase(test) >>> try: ... case.debug() ... except DocTestFailure, failure: ... pass DocTestFailure objects provide access to the test: >>> failure.test is test True As well as to the example: >>> failure.example.want '2\n' and the actual output: >>> failure.got '1\n' """ self.setUp() runner = DebugRunner(optionflags=self._dt_optionflags, checker=self._dt_checker, verbose=False) runner.run(self._dt_test, clear_globs=False) self.tearDown() def id(self): return self._dt_test.name def __repr__(self): name = self._dt_test.name.split('.') return "%s (%s)" % (name[-1], '.'.join(name[:-1])) __str__ = __repr__ def shortDescription(self): return "Doctest: " + self._dt_test.name def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None, **options): """ Convert doctest tests for a module to a unittest test suite. This converts each documentation string in a module that contains doctest tests to a unittest test case. If any of the tests in a doc string fail, then the test case fails. An exception is raised showing the name of the file containing the test and a (sometimes approximate) line number. The `module` argument provides the module to be tested. The argument can be either a module or a module name. If no argument is given, the calling module is used. A number of options may be provided as keyword arguments: setUp A set-up function. This is called before running the tests in each file. The setUp function will be passed a DocTest object. The setUp function can access the test globals as the globs attribute of the test passed. tearDown A tear-down function. This is called after running the tests in each file. The tearDown function will be passed a DocTest object. The tearDown function can access the test globals as the globs attribute of the test passed. globs A dictionary containing initial global variables for the tests. optionflags A set of doctest option flags expressed as an integer. """ if test_finder is None: test_finder = DocTestFinder() module = _normalize_module(module) tests = test_finder.find(module, globs=globs, extraglobs=extraglobs, optionflags=options.get('optionflags', 0)) if globs is None: globs = module.__dict__ if not tests: # Why do we want to do this? Because it reveals a bug that might # otherwise be hidden. raise ValueError(module, "has no tests") tests.sort() suite = unittest.TestSuite() for test in tests: if len(test.examples) == 0: continue if not test.filename: filename = module.__file__ if filename[-4:] in (".pyc", ".pyo"): filename = filename[:-1] test.filename = filename suite.addTest(DocTestCase(test, **options)) return suite class DocFileCase(DocTestCase): def id(self): return '_'.join(self._dt_test.name.split('.')) def __repr__(self): return self._dt_test.filename __str__ = __repr__ def format_failure(self, err): return ('Failed doctest test for %s\n File "%s", line 0\n\n%s' % (self._dt_test.name, self._dt_test.filename, err) ) def DocFileTest(path, module_relative=True, package=None, globs=None, parser=DocTestParser(), encoding=None, **options): if globs is None: globs = {} else: globs = globs.copy() if package and not module_relative: raise ValueError("Package may only be specified for module-" "relative paths.") # Relativize the path. if module_relative: package = _normalize_module(package) path = _module_relative_path(package, path) if "__file__" not in globs: globs["__file__"] = path # Find the file and read it. name = os.path.basename(path) doc = open(path).read() # If an encoding is specified, use it to convert the file to unicode if encoding is None: encoding = pep263_encoding(doc) if encoding is not None: doc = doc.decode(encoding) optionflags = options.get('optionflags', 0) # Convert it to a test, and wrap it in a DocFileCase. test = parser.get_doctest(doc, globs, name, path, 0, optionflags) return DocFileCase(test, **options) def DocFileSuite(*paths, **kw): """A unittest suite for one or more doctest files. The path to each doctest file is given as a string; the interpretation of that string depends on the keyword argument "module_relative". A number of options may be provided as keyword arguments: module_relative If "module_relative" is True, then the given file paths are interpreted as os-independent module-relative paths. By default, these paths are relative to the calling module's directory; but if the "package" argument is specified, then they are relative to that package. To ensure os-independence, "filename" should use "/" characters to separate path segments, and may not be an absolute path (i.e., it may not begin with "/"). If "module_relative" is False, then the given file paths are interpreted as os-specific paths. These paths may be absolute or relative (to the current working directory). package A Python package or the name of a Python package whose directory should be used as the base directory for module relative paths. If "package" is not specified, then the calling module's directory is used as the base directory for module relative filenames. It is an error to specify "package" if "module_relative" is False. setUp A set-up function. This is called before running the tests in each file. The setUp function will be passed a DocTest object. The setUp function can access the test globals as the globs attribute of the test passed. tearDown A tear-down function. This is called after running the tests in each file. The tearDown function will be passed a DocTest object. The tearDown function can access the test globals as the globs attribute of the test passed. globs A dictionary containing initial global variables for the tests. optionflags A set of doctest option flags expressed as an integer. parser A DocTestParser (or subclass) that should be used to extract tests from the files. encoding An encoding that will be used to convert the files to unicode. """ suite = unittest.TestSuite() # We do this here so that _normalize_module is called at the right # level. If it were called in DocFileTest, then this function # would be the caller and we might guess the package incorrectly. if kw.get('module_relative', True): kw['package'] = _normalize_module(kw.get('package')) for path in paths: suite.addTest(DocFileTest(path, **kw)) return suite ###################################################################### ## 9. Debugging Support ###################################################################### def script_from_examples(s): r"""Extract script from text with examples. Converts text with examples to a Python script. Example input is converted to regular code. Example output and all other words are converted to comments: >>> text = ''' ... Here are examples of simple math. ... ... Python has super accurate integer addition ... ... >>> 2 + 2 ... 5 ... ... And very friendly error messages: ... ... >>> 1/0 ... To Infinity ... And ... Beyond ... ... You can use logic if you want: ... ... >>> if 0: ... ... blah ... ... blah ... ... ... ... Ho hum ... ''' >>> print script_from_examples(text) # Here are examples of simple math. # # Python has super accurate integer addition # 2 + 2 # Expected: ## 5 # # And very friendly error messages: # 1/0 # Expected: ## To Infinity ## And ## Beyond # # You can use logic if you want: # if 0: blah blah # # Ho hum """ output = [] for piece in DocTestParser().parse(s): if isinstance(piece, Example): # Add the example's source code (strip trailing NL) output.append(piece.source[:-1]) # Add the expected output: want = piece.want if want: output.append('# Expected:') output += ['## '+l for l in want.split('\n')[:-1]] else: # Add non-example text. output += [_comment_line(l) for l in piece.split('\n')[:-1]] # Trim junk on both ends. while output and output[-1] == '#': output.pop() while output and output[0] == '#': output.pop(0) # Combine the output, and return it. return '\n'.join(output) def testsource(module, name): """Extract the test sources from a doctest docstring as a script. Provide the module (or dotted name of the module) containing the test to be debugged and the name (within the module) of the object with the doc string with tests to be debugged. """ module = _normalize_module(module) tests = DocTestFinder().find(module) test = [t for t in tests if t.name == name] if not test: raise ValueError(name, "not found in tests") test = test[0] testsrc = script_from_examples(test.docstring) return testsrc def debug_src(src, pm=False, globs=None): """Debug a single doctest docstring, in argument `src`'""" testsrc = script_from_examples(src) debug_script(testsrc, pm, globs) def debug_script(src, pm=False, globs=None): "Debug a test script. `src` is the script, as a string." import pdb # Note that tempfile.NameTemporaryFile() cannot be used. As the # docs say, a file so created cannot be opened by name a second time # on modern Windows boxes, and execfile() needs to open it. srcfilename = tempfile.mktemp(".py", "doctestdebug") f = open(srcfilename, 'w') f.write(src) f.close() try: if globs: globs = globs.copy() else: globs = {} if pm: try: execfile(srcfilename, globs, globs) except: print sys.exc_info()[1] pdb.post_mortem(sys.exc_info()[2]) else: # Note that %r is vital here. '%s' instead can, e.g., cause # backslashes to get treated as metacharacters on Windows. pdb.run("execfile(%r)" % srcfilename, globs, globs) finally: os.remove(srcfilename) def debug(module, name, pm=False): """Debug a single doctest docstring. Provide the module (or dotted name of the module) containing the test to be debugged and the name (within the module) of the object with the docstring with tests to be debugged. """ module = _normalize_module(module) testsrc = testsource(module, name) debug_script(testsrc, pm, module.__dict__) ###################################################################### ## 10. Example Usage ###################################################################### class _TestClass: """ A pointless class, for sanity-checking of docstring testing. Methods: square() get() >>> _TestClass(13).get() + _TestClass(-12).get() 1 >>> hex(_TestClass(13).square().get()) '0xa9' """ def __init__(self, val): """val -> _TestClass object with associated value val. >>> t = _TestClass(123) >>> print t.get() 123 """ self.val = val def square(self): """square() -> square TestClass's associated value >>> _TestClass(13).square().get() 169 """ self.val = self.val ** 2 return self def get(self): """get() -> return TestClass's associated value. >>> x = _TestClass(-42) >>> print x.get() -42 """ return self.val __test__ = {"_TestClass": _TestClass, "string": r""" Example of a string object, searched as-is. >>> x = 1; y = 2 >>> x + y, x * y (3, 2) """, "bool-int equivalence": r""" In 2.2, boolean expressions displayed 0 or 1. By default, we still accept them. This can be disabled by passing DONT_ACCEPT_TRUE_FOR_1 to the new optionflags argument. >>> 4 == 4 1 >>> 4 == 4 True >>> 4 > 4 0 >>> 4 > 4 False """, "blank lines": r""" Blank lines can be marked with : >>> print 'foo\n\nbar\n' foo bar """, "ellipsis": r""" If the ellipsis flag is used, then '...' can be used to elide substrings in the desired output: >>> print range(1000) #doctest: +ELLIPSIS [0, 1, 2, ..., 999] """, "whitespace normalization": r""" If the whitespace normalization flag is used, then differences in whitespace are ignored. >>> print range(30) #doctest: +NORMALIZE_WHITESPACE [0, 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] """, } def _test_footnotes(): ''' Footnotes ========= If the INTERPRET_FOOTNOTES flag is passed as part of optionflags, then footnotes will be looked up and their code injected at each point of reference. For example: >>> counter = 0 Here is some text that references a footnote [1]_ >>> counter 1 .. [1] and here we increment ``counter`` >>> counter += 1 Footnotes can also be referenced after they are defined: [1]_ >>> counter 2 Footnotes can also be "citations", which just means that the value in the brackets is alphanumeric: [citation]_ >>> print from_citation hi .. [citation] this is a citation. >>> from_citation = 'hi' Footnotes can contain more than one example: [multi example]_ >>> print one 1 >>> print two 2 >>> print three 3 .. [multi example] Here's a footnote with multiple examples: >>> one = 1 and now another (note indentation to make this part of the footnote): >>> two = 2 and a third: >>> three = 3 More than one footnote can be referenced at a time [1]_ [2]_ >>> counter 6 .. [2] let's multiply ``counter`` by two >>> counter *= 2 Parsing Details --------------- If the INTERPRET_FOOTNOTES optionflag isn't set, footnotes are ignored. >>> doctest = """ ... This is a doctest. [#1]_ ... ... >>> print var ... ... .. [#1] a footnote ... Here we set up the variable ... ... >>> var = 1 ... """ >>> print_structure(doctest) Prose| This is a doctest. [#1]_ Code | print var Prose| .. [#1] a footnote Code | var = 1 Prose| If INTERPRET_FOOTNOTES is set, footnotes are also copied to the point at which they are referenced. >>> print_structure(doctest, optionflags=INTERPRET_FOOTNOTES) Prose| This is a doctest. [#1]_ Code | var = 1 Prose| Code | print var Prose| .. [#1] a footnote Prose| >>> print_structure(""" ... Footnotes can have code that starts with no prose. [#quick code]_ ... ... .. [#quick code] ... >>> print 'this is some code' ... this is some code ... """, optionflags=INTERPRET_FOOTNOTES) Prose| Footnotes can have code that starts with no prose. [#quick code]_ Code | print 'this is some code' Prose| Prose| >>> print_structure(""" ... Footnotes can be back-to-back [#first]_ [#second]_ ... .. [#first] ... .. [#second] ... >>> 1+1 ... 2 ... """, optionflags=INTERPRET_FOOTNOTES) Prose| Footnotes can be back-to-back [#first]_ [#second]_ Prose| Footnotes can be back-to-back [#first]_ [#second]_ Code | 1+1 Prose| Prose| >>> print_structure(""" ... .. [#no code] Footnotes can also be defined with no code. ... """, optionflags=INTERPRET_FOOTNOTES) Prose| .. [#no code] Footnotes can also be defined with no code. If there are multiple footnotes with no code, then one with code, they are parsed correctly. >>> print_structure(""" ... I'd like some code to go here [#some code]_ ... .. [#no code 1] Footnotes can also be defined with no code. ... .. [#no code 2] Footnotes can also be defined with no code. ... .. [#no code 3] Footnotes can also be defined with no code. ... .. [#some code] ... >>> print 'hi' ... hi ... """, optionflags=INTERPRET_FOOTNOTES) Prose| I'd like some code to go here [#some code]_ Code | print 'hi' Prose| Prose| The non-autonumbered flavor of labels works too. >>> print_structure(""" ... Here is some text. [foo]_ ... .. [foo] ... >>> print 'hi' ... hi ... """, optionflags=INTERPRET_FOOTNOTES) Prose| Here is some text. [foo]_ Code | print 'hi' Prose| Prose| ''' def print_structure(doctest, optionflags=0): def preview(s): first_line = s.strip().split('\n')[0] MAX_LENGTH = 70 if len(first_line) <= MAX_LENGTH: return first_line return '%s...' % first_line[:MAX_LENGTH].strip() parser = DocTestParser() for x in parser.parse(doctest, optionflags=optionflags): if isinstance(x, Example): result = 'Code | ' + preview(x.source) else: result = 'Prose| ' + preview(x) print result.strip() def _test(): r = unittest.TextTestRunner() r.run(DocTestSuite(optionflags=INTERPRET_FOOTNOTES)) if __name__ == "__main__": _test() # TODO: # - make tracebacks show where the footnote was referenced # - teach script_from_examples and testsource about INTERPRET_FOOTNOTES # - update comments (including docstring for testfile) PK͆3a;T zope/testing/loghandler.py############################################################################## # # Copyright (c) 2003 Zope Corporation and Contributors. # All Rights Reserved. # # This software is subject to the provisions of the Zope Public License, # Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution. # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS # FOR A PARTICULAR PURPOSE. # ############################################################################## """logging handler for tests that check logging output. $Id: loghandler.py 27164 2004-08-17 11:16:39Z hdima $ """ import logging class Handler(logging.Handler): """Handler for use with unittest.TestCase objects. The handler takes a TestCase instance as a constructor argument. It can be registered with one or more loggers and collects log records they generate. The assertLogsMessage() and failIfLogsMessage() methods can be used to check the logger output and causes the test to fail as appropriate. """ def __init__(self, testcase, propagate=False): logging.Handler.__init__(self) self.records = [] # loggers stores (logger, propagate) tuples self.loggers = [] self.closed = False self.propagate = propagate self.testcase = testcase def close(self): """Remove handler from any loggers it was added to.""" if self.closed: return for logger, propagate in self.loggers: logger.removeHandler(self) logger.propagate = propagate self.closed = True def add(self, name): """Add handler to logger named name.""" logger = logging.getLogger(name) old_prop = logger.propagate logger.addHandler(self) if self.propagate: logger.propagate = 1 else: logger.propagate = 0 self.loggers.append((logger, old_prop)) def emit(self, record): self.records.append(record) def assertLogsMessage(self, msg, level=None): for r in self.records: if r.getMessage() == msg: if level is not None and r.levelno == level: return msg = "No log message contained %r" % msg if level is not None: msg += " at level %d" % level self.testcase.fail(msg) def failIfLogsMessage(self, msg): for r in self.records: if r.getMessage() == msg: self.testcase.fail("Found log message %r" % msg) PK45](Qsszope/testing/renormalizing.py############################################################################## # # Copyright (c) 2004 Zope Corporation and Contributors. # All Rights Reserved. # # This software is subject to the provisions of the Zope Public License, # Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution. # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS # FOR A PARTICULAR PURPOSE. # ############################################################################## r"""Regular expression pattern normalizing output checker The pattern-normalizing output checker extends the default output checker with an option to normalize expected an actual output. You specify a sequence of patterns and replacements. The replacements are applied to the expected and actual outputs before calling the default outputs checker. Let's look at an example. In this example, we have some times and addresses: >>> want = '''\ ... ... completed in 1.234 seconds. ... ... ... completed in 123.234 seconds. ... ... ... completed in .234 seconds. ... ... ... completed in 1.234 seconds. ... ... ''' >>> got = '''\ ... ... completed in 1.235 seconds. ... ... ... completed in 123.233 seconds. ... ... ... completed in .231 seconds. ... ... ... completed in 1.23 seconds. ... ... ''' We may wish to consider these two strings to match, even though they differ in actual addresses and times. The default output checker will consider them different: >>> doctest.OutputChecker().check_output(want, got, 0) False We'll use the RENormalizing to normalize both the wanted and gotten strings to ignore differences in times and addresses: >>> import re >>> checker = RENormalizing([ ... (re.compile('[0-9]*[.][0-9]* seconds'), ' seconds'), ... (re.compile('at 0x[0-9a-f]+'), 'at '), ... ]) >>> checker.check_output(want, got, 0) True Usual OutputChecker options work as expected: >>> want_ellided = '''\ ... ... completed in 1.234 seconds. ... ... ... ... completed in 1.234 seconds. ... ... ''' >>> checker.check_output(want_ellided, got, 0) False >>> checker.check_output(want_ellided, got, doctest.ELLIPSIS) True When we get differencs, we output them with normalized text: >>> source = '''\ ... >>> do_something() ... ... completed in 1.234 seconds. ... ... ... ... completed in 1.234 seconds. ... ... ''' >>> example = doctest.Example(source, want_ellided) >>> print checker.output_difference(example, got, 0) Expected: > completed in seconds. ... > completed in seconds. Got: > completed in seconds. > completed in seconds. > completed in seconds. > completed in seconds. >>> print checker.output_difference(example, got, ... doctest.REPORT_NDIFF) Differences (ndiff with -expected +actual): - > - completed in seconds. - ... > completed in seconds. + > + completed in seconds. + + > + completed in seconds. + + > + completed in seconds. + If the wanted text is empty, however, we don't transform the actual output. This is usful when writing tests. We leave the expected output empty, run the test, and use the actual output as expected, after reviewing it. >>> source = '''\ ... >>> do_something() ... ''' >>> example = doctest.Example(source, '\n') >>> print checker.output_difference(example, got, 0) Expected: Got: completed in 1.235 seconds. completed in 123.233 seconds. completed in .231 seconds. completed in 1.23 seconds. $Id: renormalizing.py 66267 2006-03-31 09:40:54Z BjornT $ """ import doctest class RENormalizing(doctest.OutputChecker): """Pattern-normalizing outout checker """ def __init__(self, patterns): self.patterns = patterns def check_output(self, want, got, optionflags): if got == want: return True for pattern, repl in self.patterns: want = pattern.sub(repl, want) got = pattern.sub(repl, got) return doctest.OutputChecker.check_output(self, want, got, optionflags) def output_difference(self, example, got, optionflags): want = example.want # If want is empty, use original outputter. This is useful # when setting up tests for the first time. In that case, we # generally use the differencer to display output, which we evaluate # by hand. if not want.strip(): return doctest.OutputChecker.output_difference( self, example, got, optionflags) # Dang, this isn't as easy to override as we might wish original = want for pattern, repl in self.patterns: want = pattern.sub(repl, want) got = pattern.sub(repl, got) # temporarily hack example with normalized want: example.want = want result = doctest.OutputChecker.output_difference( self, example, got, optionflags) example.want = original return result PK͆3=}zope/testing/formparser.py"""HTML parser that extracts form information. This is intended to support functional tests that need to extract information from HTML forms returned by the publisher. See *formparser.txt* for documentation. This isn't intended to simulate a browser session; that's provided by the `zope.testbrowser` package. """ __docformat__ = "reStructuredText" import HTMLParser import urlparse def parse(data, base=None): """Return a form collection parsed from `data`. `base` should be the URL from which `data` was retrieved. """ parser = FormParser(data, base) return parser.parse() class FormParser(object): def __init__(self, data, base=None): self.data = data self.base = base self._parser = HTMLParser.HTMLParser() self._parser.handle_data = self._handle_data self._parser.handle_endtag = self._handle_endtag self._parser.handle_starttag = self._handle_starttag self._parser.handle_startendtag = self._handle_starttag self._buffer = [] self.current = None # current form self.forms = FormCollection() def parse(self): """Parse the document, returning the collection of forms.""" self._parser.feed(self.data) self._parser.close() return self.forms # HTMLParser handlers def _handle_data(self, data): self._buffer.append(data) def _handle_endtag(self, tag): if tag == "textarea": self.textarea.value = "".join(self._buffer) self.textarea = None elif tag == "select": self.select = None elif tag == "option": option = self.select.options[-1] label = "".join(self._buffer) if not option.label: option.label = label if not option.value: option.value = label if option.selected: if self.select.multiple: self.select.value.append(option.value) else: self.select.value = option.value def _handle_starttag(self, tag, attrs): del self._buffer[:] d = {} for name, value in attrs: d[name] = value name = d.get("name") id = d.get("id") or d.get("xml:id") if tag == "form": method = kwattr(d, "method", "get") action = d.get("action", "").strip() or None if self.base and action: action = urlparse.urljoin(self.base, action) enctype = kwattr(d, "enctype", "application/x-www-form-urlencoded") self.current = Form(name, id, method, action, enctype) self.forms.append(self.current) elif tag == "input": type = kwattr(d, "type", "text") checked = "checked" in d disabled = "disabled" in d readonly = "readonly" in d src = d.get("src", "").strip() or None if self.base and src: src = urlparse.urljoin(self.base, src) value = d.get("value") size = intattr(d, "size") maxlength = intattr(d, "maxlength") self._add_field( Input(name, id, type, value, checked, disabled, readonly, src, size, maxlength)) elif tag == "button": pass elif tag == "textarea": disabled = "disabled" in d readonly = "readonly" in d self.textarea = Input(name, id, "textarea", None, None, disabled, readonly, None, None, None) self.textarea.rows = intattr(d, "rows") self.textarea.cols = intattr(d, "cols") self._add_field(self.textarea) # The value will be set when the is seen. elif tag == "base": href = d.get("href", "").strip() if href and self.base: href = urlparse.urljoin(self.base, href) self.base = href elif tag == "select": disabled = "disabled" in d multiple = "multiple" in d size = intattr(d, "size") self.select = Select(name, id, disabled, multiple, size) self._add_field(self.select) elif tag == "option": disabled = "disabled" in d selected = "selected" in d value = d.get("value") label = d.get("label") option = Option(id, value, selected, label, disabled) self.select.options.append(option) # Helpers: def _add_field(self, field): if field.name in self.current: ob = self.current[field.name] if isinstance(ob, list): ob.append(field) else: self.current[field.name] = [ob, field] else: self.current[field.name] = field def kwattr(d, name, default=None): """Return attribute, converted to lowercase.""" v = d.get(name, default) if v != default and v is not None: v = v.strip().lower() v = v or default return v def intattr(d, name): """Return attribute as an integer, or None.""" if name in d: v = d[name].strip() return int(v) else: return None class FormCollection(list): """Collection of all forms from a page.""" def __getattr__(self, name): for form in self: if form.name == name: return form raise AttributeError(name) class Form(dict): """A specific form within a page.""" # This object should provide some method to prepare a dictionary # that can be passed directly as the value of the `form` argument # to the `http()` function of the Zope functional test. # # This is probably a low priority given the availability of the # `zope.testbrowser` package. def __init__(self, name, id, method, action, enctype): super(Form, self).__init__() self.name = name self.id = id self.method = method self.action = action self.enctype = enctype class Input(object): """Input element.""" rows = None cols = None def __init__(self, name, id, type, value, checked, disabled, readonly, src, size, maxlength): super(Input, self).__init__() self.name = name self.id = id self.type = type self.value = value self.checked = checked self.disabled = disabled self.readonly = readonly self.src = src self.size = size self.maxlength = maxlength class Select(Input): """Select element.""" def __init__(self, name, id, disabled, multiple, size): super(Select, self).__init__(name, id, "select", None, None, disabled, None, None, size, None) self.options = [] self.multiple = multiple if multiple: self.value = [] class Option(object): """Individual value representation for a select element.""" def __init__(self, id, value, selected, label, disabled): super(Option, self).__init__() self.id = id self.value = value self.selected = selected self.label = label self.disabled = disabled PK4:[ zope/testing/loggingsupport.py############################################################################## # # Copyright (c) 2004 Zope Corporation and Contributors. # All Rights Reserved. # # This software is subject to the provisions of the Zope Public License, # Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution. # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS # FOR A PARTICULAR PURPOSE. # ############################################################################## """Support for testing logging code If you want to test that your code generates proper log output, you can create and install a handler that collects output: >>> handler = InstalledHandler('foo.bar') The handler is installed into loggers for all of the names passed. In addition, the logger level is set to 1, which means, log everything. If you want to log less than everything, you can provide a level keyword argument. The level setting effects only the named loggers. >>> handler_with_levels = InstalledHandler('baz', level=logging.WARNING) Then, any log output is collected in the handler: >>> logging.getLogger('foo.bar').exception('eek') >>> logging.getLogger('foo.bar').info('blah blah') >>> for record in handler.records: ... print record.name, record.levelname ... print ' ', record.getMessage() foo.bar ERROR eek foo.bar INFO blah blah A similar effect can be gotten by just printing the handler: >>> print handler foo.bar ERROR eek foo.bar INFO blah blah After checking the log output, you need to uninstall the handler: >>> handler.uninstall() >>> handler_with_levels.uninstall() At which point, the handler won't get any more log output. Let's clear the handler: >>> handler.clear() >>> handler.records [] And then log something: >>> logging.getLogger('foo.bar').info('blah') and, sure enough, we still have no output: >>> handler.records [] $Id: loggingsupport.py 66909 2006-04-12 20:57:44Z slinkp $ """ import logging class Handler(logging.Handler): def __init__(self, *names, **kw): logging.Handler.__init__(self) self.names = names self.records = [] self.setLoggerLevel(**kw) def setLoggerLevel(self, level=1): self.level = level self.oldlevels = {} def emit(self, record): self.records.append(record) def clear(self): del self.records[:] def install(self): for name in self.names: logger = logging.getLogger(name) self.oldlevels[name] = logger.level logger.setLevel(self.level) logger.addHandler(self) def uninstall(self): for name in self.names: logger = logging.getLogger(name) logger.setLevel(self.oldlevels[name]) logger.removeHandler(self) def __str__(self): return '\n'.join( [("%s %s\n %s" % (record.name, record.levelname, '\n'.join([line for line in record.getMessage().split('\n') if line.strip()]) ) ) for record in self.records] ) class InstalledHandler(Handler): def __init__(self, *names, **kw): Handler.__init__(self, *names, **kw) self.install() PKv45N19RRzope/testing/testrunner.py############################################################################## # # Copyright (c) 2004-2006 Zope Corporation and Contributors. # All Rights Reserved. # # This software is subject to the provisions of the Zope Public License, # Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution. # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS # FOR A PARTICULAR PURPOSE. # ############################################################################## """Test runner $Id: testrunner.py 69364 2006-08-07 15:56:38Z adamg $ """ # Too bad: For now, we depend on zope.testing. This is because # we want to use the latest, greatest doctest, which zope.testing # provides. Then again, zope.testing is generally useful. import gc import glob import logging import optparse import os import pdb import re import sys import tempfile import threading import time import trace import traceback import types import unittest # some Linux distributions don't include the profiler, which hotshot uses try: import hotshot import hotshot.stats except ImportError: hotshot = None real_pdb_set_trace = pdb.set_trace # For some reason, the doctest module resets the trace callable randomly, thus # disabling the coverage. Simply disallow the code from doing this. A real # trace can be set, so that debugging still works. osettrace = sys.settrace def settrace(trace): if trace is None: return osettrace(trace) class TestIgnore: def __init__(self, options): self._test_dirs = [self._filenameFormat(d[0]) + os.path.sep for d in test_dirs(options, {})] self._ignore = {} self._ignored = self._ignore.get def names(self, filename, modulename): # Special case: Modules generated from text files; i.e. doctests if modulename == '': return True filename = self._filenameFormat(filename) ignore = self._ignored(filename) if ignore is None: ignore = True if filename is not None: for d in self._test_dirs: if filename.startswith(d): ignore = False break self._ignore[filename] = ignore return ignore def _filenameFormat(self, filename): return os.path.abspath(filename) if sys.platform == 'win32': #on win32 drive name can be passed with different case to `names` #that lets e.g. the coverage profiler skip complete files #_filenameFormat will make sure that all drive and filenames get lowercased #albeit trace coverage has still problems with lowercase drive letters #when determining the dotted module name OldTestIgnore = TestIgnore class TestIgnore(OldTestIgnore): def _filenameFormat(self, filename): return os.path.normcase(os.path.abspath(filename)) class TestTrace(trace.Trace): """Simple tracer. >>> tracer = TestTrace(None, count=False, trace=False) Simple rules for use: you can't stop the tracer if it not started and you can't start the tracer if it already started: >>> tracer.stop() Traceback (most recent call last): File 'testrunner.py' AssertionError: can't stop if not started >>> tracer.start() >>> tracer.start() Traceback (most recent call last): File 'testrunner.py' AssertionError: can't start if already started >>> tracer.stop() >>> tracer.stop() Traceback (most recent call last): File 'testrunner.py' AssertionError: can't stop if not started """ def __init__(self, options, **kw): trace.Trace.__init__(self, **kw) if options is not None: self.ignore = TestIgnore(options) self.started = False def start(self): assert not self.started, "can't start if already started" if not self.donothing: sys.settrace = settrace sys.settrace(self.globaltrace) threading.settrace(self.globaltrace) self.started = True def stop(self): assert self.started, "can't stop if not started" if not self.donothing: sys.settrace = osettrace sys.settrace(None) threading.settrace(None) self.started = False class EndRun(Exception): """Indicate that the existing run call should stop Used to prevent additional test output after post-mortem debugging. """ def strip_py_ext(options, path): """Return path without its .py (or .pyc or .pyo) extension, or None. If options.usecompiled is false: If path ends with ".py", the path without the extension is returned. Else None is returned. If options.usecompiled is true: If Python is running with -O, a .pyo extension is also accepted. If Python is running without -O, a .pyc extension is also accepted. """ if path.endswith(".py"): return path[:-3] if options.usecompiled: if __debug__: # Python is running without -O. ext = ".pyc" else: # Python is running with -O. ext = ".pyo" if path.endswith(ext): return path[:-len(ext)] return None def contains_init_py(options, fnamelist): """Return true iff fnamelist contains a suitable spelling of __init__.py. If options.usecompiled is false, this is so iff "__init__.py" is in the list. If options.usecompiled is true, then "__init__.pyo" is also acceptable if Python is running with -O, and "__init__.pyc" is also acceptable if Python is running without -O. """ if "__init__.py" in fnamelist: return True if options.usecompiled: if __debug__: # Python is running without -O. return "__init__.pyc" in fnamelist else: # Python is running with -O. return "__init__.pyo" in fnamelist return False def run(defaults=None, args=None): if args is None: args = sys.argv # Set the default logging policy. # XXX There are no tests for this logging behavior. # It's not at all clear that the test runner should be doing this. configure_logging() # Control reporting flags during run old_reporting_flags = doctest.set_unittest_reportflags(0) # Check to see if we are being run as a subprocess. If we are, # then use the resume-layer and defaults passed in. if len(args) > 1 and args[1] == '--resume-layer': args.pop(1) resume_layer = args.pop(1) resume_number = int(args.pop(1)) defaults = [] while len(args) > 1 and args[1] == '--default': args.pop(1) defaults.append(args.pop(1)) sys.stdin = FakeInputContinueGenerator() else: resume_layer = resume_number = None options = get_options(args, defaults) if options.fail: return True options.testrunner_defaults = defaults options.resume_layer = resume_layer options.resume_number = resume_number # Make sure we start with real pdb.set_trace. This is needed # to make tests of the test runner work properly. :) pdb.set_trace = real_pdb_set_trace if hotshot is None and options.profile: print ('The Python you\'re using doesn\'t seem to have the profiler ' 'so you can\'t use the --profile switch.') sys.exit() if (options.profile and sys.version_info[:3] <= (2,4,1) and __debug__): print ('Because of a bug in Python < 2.4.1, profiling ' 'during tests requires the -O option be passed to ' 'Python (not the test runner).') sys.exit() if options.coverage: tracer = TestTrace(options, trace=False, count=True) tracer.start() else: tracer = None if options.profile: prof_prefix = 'tests_profile.' prof_suffix = '.prof' prof_glob = prof_prefix + '*' + prof_suffix # if we are going to be profiling, and this isn't a subprocess, # clean up any stale results files if not options.resume_layer: for file_name in glob.glob(prof_glob): os.unlink(file_name) # set up the output file oshandle, file_path = tempfile.mkstemp(prof_suffix, prof_prefix, '.') prof = hotshot.Profile(file_path) prof.start() try: try: failed = not run_with_options(options) except EndRun: failed = True finally: if tracer: tracer.stop() if options.profile: prof.stop() prof.close() # We must explicitly close the handle mkstemp returned, else on # Windows this dies the next time around just above due to an # attempt to unlink a still-open file. os.close(oshandle) if options.profile and not options.resume_layer: stats = None for file_name in glob.glob(prof_glob): loaded = hotshot.stats.load(file_name) if stats is None: stats = loaded else: stats.add(loaded) stats.sort_stats('cumulative', 'calls') stats.print_stats(50) if tracer: coverdir = os.path.join(os.getcwd(), options.coverage) r = tracer.results() r.write_results(summary=True, coverdir=coverdir) doctest.set_unittest_reportflags(old_reporting_flags) return failed def run_with_options(options, found_suites=None): """Find and run tests Passing a list of suites using the found_suites parameter will cause that list of suites to be used instead of attempting to load them from the filesystem. This is useful for unit testing the test runner. Returns True if all tests passed, or False if there were any failures of any kind. """ global _layer_name_cache _layer_name_cache = {} # Reset to enforce test isolation if options.resume_layer: original_stderr = sys.stderr sys.stderr = sys.stdout elif options.verbose: if options.all: print "Running tests at all levels" else: print "Running tests at level %d" % options.at_level old_threshold = gc.get_threshold() if options.gc: if len(options.gc) > 3: print "Too many --gc options" sys.exit(1) if options.gc[0]: print ("Cyclic garbage collection threshold set to: %s" % `tuple(options.gc)`) else: print "Cyclic garbage collection is disabled." gc.set_threshold(*options.gc) old_flags = gc.get_debug() if options.gc_option: new_flags = 0 for op in options.gc_option: new_flags |= getattr(gc, op) gc.set_debug(new_flags) old_reporting_flags = doctest.set_unittest_reportflags(0) reporting_flags = 0 if options.ndiff: reporting_flags = doctest.REPORT_NDIFF if options.udiff: if reporting_flags: print "Can only give one of --ndiff, --udiff, or --cdiff" sys.exit(1) reporting_flags = doctest.REPORT_UDIFF if options.cdiff: if reporting_flags: print "Can only give one of --ndiff, --udiff, or --cdiff" sys.exit(1) reporting_flags = doctest.REPORT_CDIFF if options.report_only_first_failure: reporting_flags |= doctest.REPORT_ONLY_FIRST_FAILURE if reporting_flags: doctest.set_unittest_reportflags(reporting_flags) else: doctest.set_unittest_reportflags(old_reporting_flags) # Add directories to the path for path in options.path: if path not in sys.path: sys.path.append(path) remove_stale_bytecode(options) tests_by_layer_name = find_tests(options, found_suites) ran = 0 failures = [] errors = [] nlayers = 0 import_errors = tests_by_layer_name.pop(None, None) if import_errors: print "Test-module import failures:" for error in import_errors: print_traceback("Module: %s\n" % error.module, error.exc_info), print if 'unit' in tests_by_layer_name: tests = tests_by_layer_name.pop('unit') if (not options.non_unit) and not options.resume_layer: if options.layer: should_run = False for pat in options.layer: if pat('unit'): should_run = True break else: should_run = True if should_run: print "Running unit tests:" nlayers += 1 ran += run_tests(options, tests, 'unit', failures, errors) setup_layers = {} layers_to_run = list(ordered_layers(tests_by_layer_name)) if options.resume_layer is not None: layers_to_run = [ (layer_name, layer, tests) for (layer_name, layer, tests) in layers_to_run if layer_name == options.resume_layer ] elif options.layer: layers_to_run = [ (layer_name, layer, tests) for (layer_name, layer, tests) in layers_to_run if filter(None, [pat(layer_name) for pat in options.layer]) ] for layer_name, layer, tests in layers_to_run: nlayers += 1 try: ran += run_layer(options, layer_name, layer, tests, setup_layers, failures, errors) except CanNotTearDown: setup_layers = None if not options.resume_layer: ran += resume_tests(options, layer_name, layers_to_run, failures, errors) break if setup_layers: if options.resume_layer == None: print "Tearing down left over layers:" tear_down_unneeded((), setup_layers, True) if options.resume_layer: sys.stdout.close() print >> original_stderr, ran, len(failures), len(errors) for test, exc_info in failures: print >> original_stderr, ' '.join(str(test).strip().split('\n')) for test, exc_info in errors: print >> original_stderr, ' '.join(str(test).strip().split('\n')) else: if options.verbose > 1: if errors: print print "Tests with errors:" for test, exc_info in errors: print " ", test if failures: print print "Tests with failures:" for test, exc_info in failures: print " ", test if nlayers != 1: print "Total: %s tests, %s failures, %s errors" % ( ran, len(failures), len(errors)) if import_errors: print print "Test-modules with import problems:" for test in import_errors: print " " + test.module doctest.set_unittest_reportflags(old_reporting_flags) if options.gc_option: gc.set_debug(old_flags) if options.gc: gc.set_threshold(*old_threshold) return not bool(import_errors or failures or errors) def run_tests(options, tests, name, failures, errors): repeat = options.repeat or 1 repeat_range = iter(range(repeat)) ran = 0 gc.collect() lgarbage = len(gc.garbage) sumrc = 0 if options.report_refcounts: if options.verbose: track = TrackRefs() rc = sys.gettotalrefcount() for i in repeat_range: if repeat > 1: print "Iteration", i+1 if options.verbose > 0 or options.progress: print ' Running:' result = TestResult(options, tests, layer_name=name) t = time.time() if options.post_mortem: # post-mortem debugging for test in tests: if result.shouldStop: break result.startTest(test) state = test.__dict__.copy() try: try: test.debug() except: result.addError( test, sys.exc_info()[:2] + (sys.exc_info()[2].tb_next, ), ) else: result.addSuccess(test) finally: result.stopTest(test) test.__dict__.clear() test.__dict__.update(state) else: # normal for test in tests: if result.shouldStop: break state = test.__dict__.copy() test(result) test.__dict__.clear() test.__dict__.update(state) t = time.time() - t if options.verbose == 1 or options.progress: result.stopTests() print failures.extend(result.failures) errors.extend(result.errors) print ( " Ran %s tests with %s failures and %s errors in %.3f seconds." % (result.testsRun, len(result.failures), len(result.errors), t) ) ran = result.testsRun gc.collect() if len(gc.garbage) > lgarbage: print ("Tests generated new (%d) garbage:" % (len(gc.garbage)-lgarbage)) print gc.garbage[lgarbage:] lgarbage = len(gc.garbage) if options.report_refcounts: # If we are being tested, we don't want stdout itself to # foul up the numbers. :) try: sys.stdout.getvalue() except AttributeError: pass prev = rc rc = sys.gettotalrefcount() if options.verbose: track.update() if i: print (" " " sum detail refcount=%-8d" " sys refcount=%-8d" " change=%-6d" % (track.n, rc, rc - prev)) if options.verbose: track.output() else: track.delta = None elif i: print " sys refcount=%-8d change=%-6d" % (rc, rc - prev) return ran def run_layer(options, layer_name, layer, tests, setup_layers, failures, errors): gathered = [] gather_layers(layer, gathered) needed = dict([(l, 1) for l in gathered]) if options.resume_number != 0: print "Running %s tests:" % layer_name tear_down_unneeded(needed, setup_layers) if options.resume_layer != None: print " Running in a subprocess." setup_layer(layer, setup_layers) return run_tests(options, tests, layer_name, failures, errors) def resume_tests(options, layer_name, layers, failures, errors): layers = [l for (l, _, _) in layers] layers = layers[layers.index(layer_name):] rantotal = 0 resume_number = 0 for layer_name in layers: args = [sys.executable, options.original_testrunner_args[0], '--resume-layer', layer_name, str(resume_number), ] resume_number += 1 for d in options.testrunner_defaults: args.extend(['--default', d]) args.extend(options.original_testrunner_args[1:]) # this is because of a bug in Python (http://www.python.org/sf/900092) if (hotshot is not None and options.profile and sys.version_info[:3] <= (2,4,1)): args.insert(1, '-O') if sys.platform.startswith('win'): args = args[0] + ' ' + ' '.join([ ('"' + a.replace('\\', '\\\\').replace('"', '\\"') + '"') for a in args[1:] ]) subin, subout, suberr = os.popen3(args) for l in subout: sys.stdout.write(l) line = suberr.readline() try: ran, nfail, nerr = map(int, line.strip().split()) except: raise SubprocessError(line+suberr.read()) while nfail > 0: nfail -= 1 failures.append((suberr.readline().strip(), None)) while nerr > 0: nerr -= 1 errors.append((suberr.readline().strip(), None)) rantotal += ran return rantotal class SubprocessError(Exception): """An error occurred when running a subprocess """ class CanNotTearDown(Exception): "Couldn't tear down a test" def tear_down_unneeded(needed, setup_layers, optional=False): # Tear down any layers not needed for these tests. The unneeded # layers might interfere. unneeded = [l for l in setup_layers if l not in needed] unneeded = order_by_bases(unneeded) unneeded.reverse() for l in unneeded: print " Tear down %s" % name_from_layer(l), t = time.time() try: if hasattr(l, 'tearDown'): l.tearDown() except NotImplementedError: print "... not supported" if not optional: raise CanNotTearDown(l) else: print "in %.3f seconds." % (time.time() - t) del setup_layers[l] def setup_layer(layer, setup_layers): assert layer is not object if layer not in setup_layers: for base in layer.__bases__: if base is not object: setup_layer(base, setup_layers) print " Set up %s" % name_from_layer(layer), t = time.time() if hasattr(layer, 'setUp'): layer.setUp() print "in %.3f seconds." % (time.time() - t) setup_layers[layer] = 1 def dependencies(bases, result): for base in bases: result[base] = 1 dependencies(base.__bases__, result) class TestResult(unittest.TestResult): max_width = 80 def __init__(self, options, tests, layer_name=None): unittest.TestResult.__init__(self) self.options = options # Calculate our list of relevant layers we need to call testSetUp # and testTearDown on. if layer_name != 'unit': layers = [] gather_layers(layer_from_name(layer_name), layers) self.layers = order_by_bases(layers) else: self.layers = [] if options.progress: count = 0 for test in tests: count += test.countTestCases() self.count = count self.last_width = 0 if options.progress: try: # Note that doing this every time is more test friendly. import curses except ImportError: # avoid repimporting a broken module in python 2.3 sys.modules['curses'] = None else: try: curses.setupterm() except TypeError: pass else: self.max_width = curses.tigetnum('cols') def getShortDescription(self, test, room): room -= 1 s = str(test) if len(s) > room: pos = s.find(" (") if pos >= 0: w = room - (pos + 5) if w < 1: # first portion (test method name) is too long s = s[:room-3] + "..." else: pre = s[:pos+2] post = s[-w:] s = "%s...%s" % (pre, post) else: w = room - 4 s = '... ' + s[-w:] return ' ' + s[:room] def testSetUp(self): """A layer may define a setup method to be called before each individual test. """ for layer in self.layers: if hasattr(layer, 'testSetUp'): layer.testSetUp() def testTearDown(self): """A layer may define a teardown method to be called after each individual test. This is useful for clearing the state of global resources or resetting external systems such as relational databases or daemons. """ for layer in self.layers[-1::-1]: if hasattr(layer, 'testTearDown'): layer.testTearDown() def startTest(self, test): self.testSetUp() unittest.TestResult.startTest(self, test) testsRun = self.testsRun - 1 count = test.countTestCases() self.testsRun = testsRun + count options = self.options self.test_width = 0 if options.progress: if self.last_width: sys.stdout.write('\r' + (' ' * self.last_width) + '\r') s = " %d/%d (%.1f%%)" % ( self.testsRun, self.count, (self.testsRun) * 100.0 / self.count ) sys.stdout.write(s) self.test_width += len(s) if options.verbose == 1: room = self.max_width - self.test_width - 1 s = self.getShortDescription(test, room) sys.stdout.write(s) self.test_width += len(s) elif options.verbose == 1: for i in range(count): sys.stdout.write('.') testsRun += 1 if options.verbose > 1: s = str(test) sys.stdout.write(' ') sys.stdout.write(s) self.test_width += len(s) + 1 sys.stdout.flush() self._threads = threading.enumerate() self._start_time = time.time() def addSuccess(self, test): if self.options.verbose > 2: t = max(time.time() - self._start_time, 0.0) s = " (%.3f ms)" % t sys.stdout.write(s) self.test_width += len(s) + 1 def addError(self, test, exc_info): if self.options.verbose > 2: print " (%.3f ms)" % (time.time() - self._start_time) unittest.TestResult.addError(self, test, exc_info) print self._print_traceback("Error in test %s" % test, exc_info) if self.options.post_mortem: if self.options.resume_layer: print print '*'*70 print ("Can't post-mortem debug when running a layer" " as a subprocess!") print '*'*70 print else: post_mortem(exc_info) self.test_width = self.last_width = 0 def addFailure(self, test, exc_info): if self.options.verbose > 2: print " (%.3f ms)" % (time.time() - self._start_time) unittest.TestResult.addFailure(self, test, exc_info) print self._print_traceback("Failure in test %s" % test, exc_info) if self.options.post_mortem: post_mortem(exc_info) self.test_width = self.last_width = 0 def stopTests(self): if self.options.progress and self.last_width: sys.stdout.write('\r' + (' ' * self.last_width) + '\r') def stopTest(self, test): self.testTearDown() if self.options.progress: self.last_width = self.test_width elif self.options.verbose > 1: print if gc.garbage: print "The following test left garbage:" print test print gc.garbage # TODO: Perhaps eat the garbage here, so that the garbage isn't # printed for every subsequent test. # Did the test leave any new threads behind? new_threads = [t for t in threading.enumerate() if (t.isAlive() and t not in self._threads)] if new_threads: print "The following test left new threads behind:" print test print "New thread(s):", new_threads sys.stdout.flush() def _print_traceback(self, msg, exc_info): print_traceback(msg, exc_info) doctest_template = """ File "%s", line %s, in %s %s Want: %s Got: %s """ class FakeInputContinueGenerator: def readline(self): print 'c\n' print '*'*70 print ("Can't use pdb.set_trace when running a layer" " as a subprocess!") print '*'*70 print return 'c\n' def print_traceback(msg, exc_info): print print msg v = exc_info[1] if isinstance(v, doctest.DocTestFailureException): tb = v.args[0] elif isinstance(v, doctest.DocTestFailure): tb = doctest_template % ( v.test.filename, v.test.lineno + v.example.lineno + 1, v.test.name, v.example.source, v.example.want, v.got, ) else: tb = "".join(traceback.format_exception(*exc_info)) print tb def post_mortem(exc_info): err = exc_info[1] if isinstance(err, (doctest.UnexpectedException, doctest.DocTestFailure)): if isinstance(err, doctest.UnexpectedException): exc_info = err.exc_info # Print out location info if the error was in a doctest if exc_info[2].tb_frame.f_code.co_filename == '': print_doctest_location(err) else: print_doctest_location(err) # Hm, we have a DocTestFailure exception. We need to # generate our own traceback try: exec ('raise ValueError' '("Expected and actual output are different")' ) in err.test.globs except: exc_info = sys.exc_info() print "%s:" % (exc_info[0], ) print exc_info[1] pdb.post_mortem(exc_info[2]) raise EndRun def print_doctest_location(err): # This mimicks pdb's output, which gives way cool results in emacs :) filename = err.test.filename if filename.endswith('.pyc'): filename = filename[:-1] print "> %s(%s)_()" % (filename, err.test.lineno+err.example.lineno+1) def ordered_layers(tests_by_layer_name): layer_names = dict([(layer_from_name(layer_name), layer_name) for layer_name in tests_by_layer_name]) for layer in order_by_bases(layer_names): layer_name = layer_names[layer] yield layer_name, layer, tests_by_layer_name[layer_name] def gather_layers(layer, result): if layer is not object: result.append(layer) for b in layer.__bases__: gather_layers(b, result) def layer_from_name(layer_name): """Return the layer for the corresponding layer_name by discovering and importing the necessary module if necessary. Note that a name -> layer cache is maintained by name_from_layer to allow locating layers in cases where it would otherwise be impossible. """ global _layer_name_cache if _layer_name_cache.has_key(layer_name): return _layer_name_cache[layer_name] layer_names = layer_name.split('.') layer_module, module_layer_name = layer_names[:-1], layer_names[-1] return getattr(import_name('.'.join(layer_module)), module_layer_name) def order_by_bases(layers): """Order the layers from least to most specific (bottom to top) """ named_layers = [(name_from_layer(layer), layer) for layer in layers] named_layers.sort() named_layers.reverse() gathered = [] for name, layer in named_layers: gather_layers(layer, gathered) gathered.reverse() seen = {} result = [] for layer in gathered: if layer not in seen: seen[layer] = 1 if layer in layers: result.append(layer) return result _layer_name_cache = {} def name_from_layer(layer): """Determine a name for the Layer using the namespace to avoid conflicts. We also cache a name -> layer mapping to enable layer_from_name to work in cases where the layer cannot be imported (such as layers defined in doctests) """ if layer.__module__ == '__builtin__': name = layer.__name__ else: name = layer.__module__ + '.' + layer.__name__ _layer_name_cache[name] = layer return name def find_tests(options, found_suites=None): """Creates a dictionary mapping layer name to a suite of tests to be run in that layer. Passing a list of suites using the found_suites parameter will cause that list of suites to be used instead of attempting to load them from the filesystem. This is useful for unit testing the test runner. """ suites = {} if found_suites is None: found_suites = find_suites(options) for suite in found_suites: for test, layer_name in tests_from_suite(suite, options): suite = suites.get(layer_name) if not suite: suite = suites[layer_name] = unittest.TestSuite() suite.addTest(test) return suites def tests_from_suite(suite, options, dlevel=1, dlayer='unit'): """Returns a sequence of (test, layer_name) The tree of suites is recursively visited, with the most specific layer taking precidence. So if a TestCase with a layer of 'foo' is contained in a TestSuite with a layer of 'bar', the test case would be returned with 'foo' as the layer. Tests are also filtered out based on the test level and test selection filters stored in the options. """ level = getattr(suite, 'level', dlevel) layer = getattr(suite, 'layer', dlayer) if not isinstance(layer, basestring): layer = name_from_layer(layer) if isinstance(suite, unittest.TestSuite): for possible_suite in suite: for r in tests_from_suite(possible_suite, options, level, layer): yield r elif isinstance(suite, StartUpFailure): yield (suite, None) else: if level <= options.at_level: for pat in options.test: if pat(str(suite)): yield (suite, layer) break def find_suites(options): for fpath, package in find_test_files(options): for (prefix, prefix_package) in options.prefix: if fpath.startswith(prefix) and package == prefix_package: # strip prefix, strip .py suffix and convert separator to dots noprefix = fpath[len(prefix):] noext = strip_py_ext(options, noprefix) assert noext is not None module_name = noext.replace(os.path.sep, '.') if package: module_name = package + '.' + module_name for filter in options.module: if filter(module_name): break else: continue try: module = import_name(module_name) except: suite = StartUpFailure( options, module_name, sys.exc_info()[:2] + (sys.exc_info()[2].tb_next.tb_next,), ) else: try: suite = getattr(module, options.suite_name)() if isinstance(suite, unittest.TestSuite): check_suite(suite, module_name) else: raise TypeError( "Invalid test_suite, %r, in %s" % (suite, module_name) ) except: suite = StartUpFailure( options, module_name, sys.exc_info()[:2]+(None,)) yield suite break def check_suite(suite, module_name): for x in suite: if isinstance(x, unittest.TestSuite): check_suite(x, module_name) elif not isinstance(x, unittest.TestCase): raise TypeError( "Invalid test, %r,\nin test_suite from %s" % (x, module_name) ) class StartUpFailure: def __init__(self, options, module, exc_info): if options.post_mortem: post_mortem(exc_info) self.module = module self.exc_info = exc_info def find_test_files(options): found = {} for f, package in find_test_files_(options): if f not in found: found[f] = 1 yield f, package identifier = re.compile(r'[_a-zA-Z]\w*$').match def find_test_files_(options): tests_pattern = options.tests_pattern test_file_pattern = options.test_file_pattern # If options.usecompiled, we can accept .pyc or .pyo files instead # of .py files. We'd rather use a .py file if one exists. `root2ext` # maps a test file path, sans extension, to the path with the best # extension found (.py if it exists, else .pyc or .pyo). # Note that "py" < "pyc" < "pyo", so if more than one extension is # found, the lexicographically smaller one is best. # Found a new test file, in directory `dirname`. `noext` is the # file name without an extension, and `withext` is the file name # with its extension. def update_root2ext(dirname, noext, withext): key = os.path.join(dirname, noext) new = os.path.join(dirname, withext) if key in root2ext: root2ext[key] = min(root2ext[key], new) else: root2ext[key] = new for (p, package) in test_dirs(options, {}): for dirname, dirs, files in walk_with_symlinks(options, p): if dirname != p and not contains_init_py(options, files): continue # not a plausible test directory root2ext = {} dirs[:] = filter(identifier, dirs) d = os.path.split(dirname)[1] if tests_pattern(d) and contains_init_py(options, files): # tests directory for file in files: noext = strip_py_ext(options, file) if noext and test_file_pattern(noext): update_root2ext(dirname, noext, file) for file in files: noext = strip_py_ext(options, file) if noext and tests_pattern(noext): update_root2ext(dirname, noext, file) winners = root2ext.values() winners.sort() for file in winners: yield file, package def walk_with_symlinks(options, dir): # TODO -- really should have test of this that uses symlinks # this is hard on a number of levels ... for dirpath, dirs, files in os.walk(dir): dirs.sort() files.sort() dirs[:] = [d for d in dirs if d not in options.ignore_dir] yield (dirpath, dirs, files) for d in dirs: p = os.path.join(dirpath, d) if os.path.islink(p): for sdirpath, sdirs, sfiles in walk_with_symlinks(options, p): yield (sdirpath, sdirs, sfiles) compiled_sufixes = '.pyc', '.pyo' def remove_stale_bytecode(options): if options.keepbytecode: return for (p, _) in options.test_path: for dirname, dirs, files in walk_with_symlinks(options, p): for file in files: if file[-4:] in compiled_sufixes and file[:-1] not in files: fullname = os.path.join(dirname, file) print "Removing stale bytecode file", fullname os.unlink(fullname) def test_dirs(options, seen): if options.package: for p in options.package: p = import_name(p) for p in p.__path__: p = os.path.abspath(p) if p in seen: continue for (prefix, package) in options.prefix: if p.startswith(prefix) or p == prefix[:-1]: seen[p] = 1 yield p, package break else: for dpath in options.test_path: yield dpath def import_name(name): __import__(name) return sys.modules[name] def configure_logging(): """Initialize the logging module.""" import logging.config # Get the log.ini file from the current directory instead of # possibly buried in the build directory. TODO: This isn't # perfect because if log.ini specifies a log file, it'll be # relative to the build directory. Hmm... logini = # os.path.abspath("log.ini") logini = os.path.abspath("log.ini") if os.path.exists(logini): logging.config.fileConfig(logini) else: # If there's no log.ini, cause the logging package to be # silent during testing. root = logging.getLogger() root.addHandler(NullHandler()) logging.basicConfig() if os.environ.has_key("LOGGING"): level = int(os.environ["LOGGING"]) logging.getLogger().setLevel(level) class NullHandler(logging.Handler): """Logging handler that drops everything on the floor. We require silence in the test environment. Hush. """ def emit(self, record): pass class TrackRefs(object): """Object to track reference counts across test runs.""" def __init__(self): self.type2count = {} self.type2all = {} self.delta = None self.n = 0 self.update() self.delta = None def update(self): gc.collect() obs = sys.getobjects(0) type2count = {} type2all = {} n = 0 for o in obs: if type(o) is str and o == '': # avoid dictionary madness continue all = sys.getrefcount(o) - 3 n += all t = type(o) if t is types.InstanceType: t = o.__class__ if t in type2count: type2count[t] += 1 type2all[t] += all else: type2count[t] = 1 type2all[t] = all ct = [( type_or_class_title(t), type2count[t] - self.type2count.get(t, 0), type2all[t] - self.type2all.get(t, 0), ) for t in type2count.iterkeys()] ct += [( type_or_class_title(t), - self.type2count[t], - self.type2all[t], ) for t in self.type2count.iterkeys() if t not in type2count] ct.sort() self.delta = ct self.type2count = type2count self.type2all = type2all self.n = n def output(self): printed = False s1 = s2 = 0 for t, delta1, delta2 in self.delta: if delta1 or delta2: if not printed: print ( ' Leak details, changes in instances and refcounts' ' by type/class:') print " %-55s %6s %6s" % ('type/class', 'insts', 'refs') print " %-55s %6s %6s" % ('-' * 55, '-----', '----') printed = True print " %-55s %6d %6d" % (t, delta1, delta2) s1 += delta1 s2 += delta2 if printed: print " %-55s %6s %6s" % ('-' * 55, '-----', '----') print " %-55s %6s %6s" % ('total', s1, s2) self.delta = None def type_or_class_title(t): module = getattr(t, '__module__', '__builtin__') if module == '__builtin__': return t.__name__ return "%s.%s" % (module, t.__name__) ############################################################################### # Command-line UI parser = optparse.OptionParser("Usage: %prog [options] [MODULE] [TEST]") ###################################################################### # Searching and filtering searching = optparse.OptionGroup(parser, "Searching and filtering", """\ Options in this group are used to define which tests to run. """) searching.add_option( '--package', '--dir', '-s', action="append", dest='package', help="""\ Search the given package's directories for tests. This can be specified more than once to run tests in multiple parts of the source tree. For example, if refactoring interfaces, you don't want to see the way you have broken setups for tests in other packages. You *just* want to run the interface tests. Packages are supplied as dotted names. For compatibility with the old test runner, forward and backward slashed in package names are converted to dots. (In the special case of packages spread over multiple directories, only directories within the test search path are searched. See the --path option.) """) searching.add_option( '--module', '-m', action="append", dest='module', help="""\ Specify a test-module filter as a regular expression. This is a case-sensitive regular expression, used in search (not match) mode, to limit which test modules are searched for tests. The regular expressions are checked against dotted module names. In an extension of Python regexp notation, a leading "!" is stripped and causes the sense of the remaining regexp to be negated (so "!bc" matches any string that does not match "bc", and vice versa). The option can be specified multiple test-module filters. Test modules matching any of the test filters are searched. If no test-module filter is specified, then all test moduless are used. """) searching.add_option( '--test', '-t', action="append", dest='test', help="""\ Specify a test filter as a regular expression. This is a case-sensitive regular expression, used in search (not match) mode, to limit which tests are run. In an extension of Python regexp notation, a leading "!" is stripped and causes the sense of the remaining regexp to be negated (so "!bc" matches any string that does not match "bc", and vice versa). The option can be specified multiple test filters. Tests matching any of the test filters are included. If no test filter is specified, then all tests are run. """) searching.add_option( '--unit', '-u', action="store_true", dest='unit', help="""\ Run only unit tests, ignoring any layer options. """) searching.add_option( '--non-unit', '-f', action="store_true", dest='non_unit', help="""\ Run tests other than unit tests. """) searching.add_option( '--layer', action="append", dest='layer', help="""\ Specify a test layer to run. The option can be given multiple times to specify more than one layer. If not specified, all layers are run. It is common for the running script to provide default values for this option. Layers are specified regular expressions, used in search mode, for dotted names of objects that define a layer. In an extension of Python regexp notation, a leading "!" is stripped and causes the sense of the remaining regexp to be negated (so "!bc" matches any string that does not match "bc", and vice versa). The layer named 'unit' is reserved for unit tests, however, take note of the --unit and non-unit options. """) searching.add_option( '-a', '--at-level', type='int', dest='at_level', help="""\ Run the tests at the given level. Any test at a level at or below this is run, any test at a level above this is not run. Level 0 runs all tests. """) searching.add_option( '--all', action="store_true", dest='all', help="Run tests at all levels.") parser.add_option_group(searching) ###################################################################### # Reporting reporting = optparse.OptionGroup(parser, "Reporting", """\ Reporting options control basic aspects of test-runner output """) reporting.add_option( '--verbose', '-v', action="count", dest='verbose', help="""\ Make output more verbose. Increment the verbosity level. """) reporting.add_option( '--quiet', '-q', action="store_true", dest='quiet', help="""\ Make the output minimal, overriding any verbosity options. """) reporting.add_option( '--progress', '-p', action="store_true", dest='progress', help="""\ Output progress status """) reporting.add_option( '-1', action="store_true", dest='report_only_first_failure', help="""\ Report only the first failure in a doctest. (Examples after the failure are still executed, in case they do any cleanup.) """) reporting.add_option( '--ndiff', action="store_true", dest="ndiff", help="""\ When there is a doctest failure, show it as a diff using the ndiff.py utility. """) reporting.add_option( '--udiff', action="store_true", dest="udiff", help="""\ When there is a doctest failure, show it as a unified diff. """) reporting.add_option( '--cdiff', action="store_true", dest="cdiff", help="""\ When there is a doctest failure, show it as a context diff. """) parser.add_option_group(reporting) ###################################################################### # Analysis analysis = optparse.OptionGroup(parser, "Analysis", """\ Analysis options provide tools for analysing test output. """) analysis.add_option( '--post-mortem', '-D', action="store_true", dest='post_mortem', help="Enable post-mortem debugging of test failures" ) analysis.add_option( '--gc', '-g', action="append", dest='gc', type="int", help="""\ Set the garbage collector generation threshold. This can be used to stress memory and gc correctness. Some crashes are only reproducible when the threshold is set to 1 (agressive garbage collection). Do "--gc 0" to disable garbage collection altogether. The --gc option can be used up to 3 times to specify up to 3 of the 3 Python gc_threshold settings. """) analysis.add_option( '--gc-option', '-G', action="append", dest='gc_option', type="choice", choices=['DEBUG_STATS', 'DEBUG_COLLECTABLE', 'DEBUG_UNCOLLECTABLE', 'DEBUG_INSTANCES', 'DEBUG_OBJECTS', 'DEBUG_SAVEALL', 'DEBUG_LEAK'], help="""\ Set a Python gc-module debug flag. This option can be used more than once to set multiple flags. """) analysis.add_option( '--repeat', '-N', action="store", type="int", dest='repeat', help="""\ Repeat the testst the given number of times. This option is used to make sure that tests leave thier environment in the state they found it and, with the --report-refcounts option to look for memory leaks. """) analysis.add_option( '--report-refcounts', '-r', action="store_true", dest='report_refcounts', help="""\ After each run of the tests, output a report summarizing changes in refcounts by object type. This option that requires that Python was built with the --with-pydebug option to configure. """) analysis.add_option( '--coverage', action="store", type='string', dest='coverage', help="""\ Perform code-coverage analysis, saving trace data to the directory with the given name. A code coverage summary is printed to standard out. """) analysis.add_option( '--profile', action="store_true", dest='profile', help="""\ Run the tests under hotshot and display the top 50 stats, sorted by cumulative time and number of calls. """) def do_pychecker(*args): if not os.environ.get("PYCHECKER"): os.environ["PYCHECKER"] = "-q" import pychecker.checker analysis.add_option( '--pychecker', action="callback", callback=do_pychecker, help="""\ Run the tests under pychecker """) parser.add_option_group(analysis) ###################################################################### # Setup setup = optparse.OptionGroup(parser, "Setup", """\ Setup options are normally supplied by the testrunner script, although they can be overridden by users. """) setup.add_option( '--path', action="append", dest='path', help="""\ Specify a path to be added to Python's search path. This option can be used multiple times to specify multiple search paths. The path is usually specified by the test-runner script itself, rather than by users of the script, although it can be overridden by users. Only tests found in the path will be run. This option also specifies directories to be searched for tests. See the search_directory. """) setup.add_option( '--test-path', action="append", dest='test_path', help="""\ Specify a path to be searched for tests, but not added to the Python search path. This option can be used multiple times to specify multiple search paths. The path is usually specified by the test-runner script itself, rather than by users of the script, although it can be overridden by users. Only tests found in the path will be run. """) setup.add_option( '--package-path', action="append", dest='package_path', nargs=2, help="""\ Specify a path to be searched for tests, but not added to the Python search path. Also specify a package for files found in this path. This is used to deal with directories that are stiched into packages that are not otherwise searched for tests. This option takes 2 arguments. The first is a path name. The second is the package name. This option can be used multiple times to specify multiple search paths. The path is usually specified by the test-runner script itself, rather than by users of the script, although it can be overridden by users. Only tests found in the path will be run. """) setup.add_option( '--tests-pattern', action="store", dest='tests_pattern', help="""\ The test runner looks for modules containing tests. It uses this pattern to identify these modules. The modules may be either packages or python files. If a test module is a package, it uses the value given by the test-file-pattern to identify python files within the package containing tests. """) setup.add_option( '--suite-name', action="store", dest='suite_name', help="""\ Specify the name of the object in each test_module that contains the module's test suite. """) setup.add_option( '--test-file-pattern', action="store", dest='test_file_pattern', help="""\ Specify a pattern for identifying python files within a tests package. See the documentation for the --tests-pattern option. """) setup.add_option( '--ignore_dir', action="append", dest='ignore_dir', help="""\ Specifies the name of a directory to ignore when looking for tests. """) parser.add_option_group(setup) ###################################################################### # Other other = optparse.OptionGroup(parser, "Other", "Other options") other.add_option( '--keepbytecode', '-k', action="store_true", dest='keepbytecode', help="""\ Normally, the test runner scans the test paths and the test directories looking for and deleting pyc or pyo files without corresponding py files. This is to prevent spurious test failures due to finding compiled modules where source modules have been deleted. This scan can be time consuming. Using this option disables this scan. If you know you haven't removed any modules since last running the tests, can make the test run go much faster. """) other.add_option( '--usecompiled', action="store_true", dest='usecompiled', help="""\ Normally, a package must contain an __init__.py file, and only .py files can contain test code. When this option is specified, compiled Python files (.pyc and .pyo) can be used instead: a directory containing __init__.pyc or __init__.pyo is also considered to be a package, and if file XYZ.py contains tests but is absent while XYZ.pyc or XYZ.pyo exists then the compiled files will be used. This is necessary when running tests against a tree where the .py files have been removed after compilation to .pyc/.pyo. Use of this option implies --keepbytecode. """) parser.add_option_group(other) ###################################################################### # Command-line processing def compile_filter(pattern): if pattern.startswith('!'): pattern = re.compile(pattern[1:]).search return (lambda s: not pattern(s)) return re.compile(pattern).search def merge_options(options, defaults): odict = options.__dict__ for name, value in defaults.__dict__.items(): if (value is not None) and (odict[name] is None): odict[name] = value default_setup_args = [ '--tests-pattern', '^tests$', '--at-level', '1', '--ignore', '.svn', '--ignore', 'CVS', '--ignore', '{arch}', '--ignore', '.arch-ids', '--ignore', '_darcs', '--test-file-pattern', '^test', '--suite-name', 'test_suite', ] def get_options(args=None, defaults=None): default_setup, _ = parser.parse_args(default_setup_args) assert not _ if defaults: defaults, _ = parser.parse_args(defaults) assert not _ merge_options(defaults, default_setup) else: defaults = default_setup if args is None: args = sys.argv original_testrunner_args = args args = args[1:] options, positional = parser.parse_args(args) merge_options(options, defaults) options.original_testrunner_args = original_testrunner_args options.fail = False if positional: module_filter = positional.pop(0) if module_filter != '.': if options.module: options.module.append(module_filter) else: options.module = [module_filter] if positional: test_filter = positional.pop(0) if options.test: options.test.append(test_filter) else: options.test = [test_filter] if positional: parser.error("Too mant positional arguments") options.ignore_dir = dict([(d,1) for d in options.ignore_dir]) options.test_file_pattern = re.compile(options.test_file_pattern).search options.tests_pattern = re.compile(options.tests_pattern).search options.test = map(compile_filter, options.test or ('.')) options.module = map(compile_filter, options.module or ('.')) if options.package: options.package = [p.replace('/', '.').replace('\\', '.') for p in options.package] # Remove useless dot ('.') at the end of the package. bash # adds a `/` by default using completion. Otherweise, it # raises an exception trying to import an empty package # because of this. options.package = [re.sub(r'\.$', '', p) for p in options.package] options.path = map(os.path.abspath, options.path or ()) options.test_path = map(os.path.abspath, options.test_path or ()) options.test_path += options.path options.test_path = ([(path, '') for path in options.test_path] + [(os.path.abspath(path), package) for (path, package) in options.package_path or () ]) options.prefix = [(path + os.path.sep, package) for (path, package) in options.test_path] if options.all: options.at_level = sys.maxint if options.unit: options.layer = ['unit'] if options.layer: options.layer = map(compile_filter, options.layer) options.layer = options.layer and dict([(l, 1) for l in options.layer]) if options.usecompiled: options.keepbytecode = options.usecompiled if options.quiet: options.verbose = 0 if options.report_refcounts and options.repeat < 2: print """\ You must use the --repeat (-N) option to specify a repeat count greater than 1 when using the --report_refcounts (-r) option. """ options.fail = True return options if options.report_refcounts and not hasattr(sys, "gettotalrefcount"): print """\ The Python you are running was not configured with --with-pydebug. This is required to use the --report-refcounts option. """ options.fail = True return options return options # Command-line UI ############################################################################### ############################################################################### # Install 2.4 TestSuite __iter__ into earlier versions if sys.version_info < (2, 4): def __iter__(suite): return iter(suite._tests) unittest.TestSuite.__iter__ = __iter__ del __iter__ # Install 2.4 TestSuite __iter__ into earlier versions ############################################################################### ############################################################################### # Test the testrunner def test_suite(): import renormalizing checker = renormalizing.RENormalizing([ # 2.5 changed the way pdb reports exceptions (re.compile(r":"), r'exceptions.\1Error:'), (re.compile('^> [^\n]+->None$', re.M), '> ...->None'), (re.compile("'[A-Za-z]:\\\\"), "'"), # hopefully, we'll make Windows happy (re.compile(r'\\\\'), '/'), # more Windows happiness (re.compile(r'\\'), '/'), # even more Windows happiness (re.compile('/r'), '\\\\r'), # undo damage from previous (re.compile(r'\r'), '\\\\r\n'), (re.compile(r'\d+[.]\d\d\d seconds'), 'N.NNN seconds'), (re.compile(r'\d+[.]\d\d\d ms'), 'N.NNN ms'), (re.compile('( |")[^\n]+testrunner-ex'), r'\1testrunner-ex'), (re.compile('( |")[^\n]+testrunner.py'), r'\1testrunner.py'), (re.compile(r'> [^\n]*(doc|unit)test[.]py\(\d+\)'), r'\1doctest.py(NNN)'), (re.compile(r'[.]py\(\d+\)'), r'.py(NNN)'), (re.compile(r'[.]py:\d+'), r'.py:NNN'), (re.compile(r' line \d+,', re.IGNORECASE), r' Line NNN,'), # omit traceback entries for unittest.py or doctest.py from # output: (re.compile(r'^ +File "[^\n]+(doc|unit)test.py", [^\n]+\n[^\n]+\n', re.MULTILINE), r''), (re.compile('^> [^\n]+->None$', re.M), '> ...->None'), (re.compile('import pdb; pdb'), 'Pdb()'), # Py 2.3 ]) def setUp(test): test.globs['saved-sys-info'] = ( sys.path[:], sys.argv[:], sys.modules.copy(), gc.get_threshold(), ) test.globs['this_directory'] = os.path.split(__file__)[0] test.globs['testrunner_script'] = __file__ def tearDown(test): sys.path[:], sys.argv[:] = test.globs['saved-sys-info'][:2] gc.set_threshold(*test.globs['saved-sys-info'][3]) sys.modules.clear() sys.modules.update(test.globs['saved-sys-info'][2]) suites = [ doctest.DocFileSuite( 'testrunner-arguments.txt', 'testrunner-coverage.txt', 'testrunner-debugging.txt', 'testrunner-edge-cases.txt', 'testrunner-errors.txt', 'testrunner-layers-ntd.txt', 'testrunner-layers.txt', 'testrunner-layers-api.txt', 'testrunner-progress.txt', 'testrunner-simple.txt', 'testrunner-test-selection.txt', 'testrunner-verbose.txt', 'testrunner-wo-source.txt', 'testrunner-repeat.txt', 'testrunner-gc.txt', 'testrunner-knit.txt', setUp=setUp, tearDown=tearDown, optionflags=doctest.ELLIPSIS+doctest.NORMALIZE_WHITESPACE, checker=checker), doctest.DocTestSuite() ] if sys.platform == 'win32': suites.append( doctest.DocFileSuite( 'testrunner-coverage-win32.txt', setUp=setUp, tearDown=tearDown, optionflags=doctest.ELLIPSIS+doctest.NORMALIZE_WHITESPACE, checker=checker)) # Python <= 2.4.1 had a bug that prevented hotshot from running in # non-optimize mode if sys.version_info[:3] > (2,4,1) or not __debug__: # some Linux distributions don't include the profiling module (which # hotshot.stats depends on) try: import hotshot.stats except ImportError: pass else: suites.append( doctest.DocFileSuite( 'testrunner-profiling.txt', setUp=setUp, tearDown=tearDown, optionflags=doctest.ELLIPSIS+doctest.NORMALIZE_WHITESPACE, checker = renormalizing.RENormalizing([ (re.compile(r'tests_profile[.]\S*[.]prof'), 'tests_profile.*.prof'), ]), ) ) if hasattr(sys, 'gettotalrefcount'): suites.append( doctest.DocFileSuite( 'testrunner-leaks.txt', setUp=setUp, tearDown=tearDown, optionflags=doctest.ELLIPSIS+doctest.NORMALIZE_WHITESPACE, checker = renormalizing.RENormalizing([ (re.compile(r'\d+[.]\d\d\d seconds'), 'N.NNN seconds'), (re.compile(r'sys refcount=\d+ +change=\d+'), 'sys refcount=NNNNNN change=NN'), (re.compile(r'sum detail refcount=\d+ +'), 'sum detail refcount=NNNNNN '), (re.compile(r'total +\d+ +\d+'), 'total NNNN NNNN'), (re.compile(r"^ +(int|type) +-?\d+ +-?\d+ *\n", re.M), ''), ]), ) ) else: suites.append( doctest.DocFileSuite( 'testrunner-leaks-err.txt', setUp=setUp, tearDown=tearDown, optionflags=doctest.ELLIPSIS+doctest.NORMALIZE_WHITESPACE, checker=checker, ) ) return unittest.TestSuite(suites) def main(): default = [ '--path', os.path.split(sys.argv[0])[0], '--tests-pattern', '^testrunner$', ] run(default) if __name__ == '__main__': # if --resume_layer is in the arguments, we are being run from the # test runner's own tests. We need to adjust the path in hopes of # not getting a different version installed in the system python. if len(sys.argv) > 1 and sys.argv[1] == '--resume-layer': sys.path.insert(0, os.path.split( os.path.split( os.path.split( os.path.abspath(sys.argv[0]) )[0] )[0] )[0] ) # Hm, when run as a script, we need to import the testrunner under # its own name, so that there's the imported flavor has the right # real_pdb_set_trace. import zope.testing.testrunner from zope.testing import doctest main() # Test the testrunner ############################################################################### # Delay import to give main an opportunity to fix up the path if # necessary from zope.testing import doctest PK͆3^zope/testing/module.py############################################################################## # # Copyright (c) 2004 Zope Corporation and Contributors. # All Rights Reserved. # # This software is subject to the provisions of the Zope Public License, # Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution. # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS # FOR A PARTICULAR PURPOSE. # ############################################################################## """Fake module support $Id: module.py 38684 2005-09-29 09:21:32Z jim $ """ import sys class FakeModule: def __init__(self, dict): self.__dict = dict def __getattr__(self, name): try: return self.__dict[name] except KeyError: raise AttributeError(name) def setUp(test, name='README.txt'): dict = test.globs dict['__name__'] = name module = FakeModule(dict) sys.modules[name] = module if '.' in name: name = name.split('.') parent = sys.modules['.'.join(name[:-1])] setattr(parent, name[-1], module) def tearDown(test, name=None): if name is None: name = test.globs['__name__'] del sys.modules[name] if '.' in name: name = name.split('.') parent = sys.modules['.'.join(name[:-1])] delattr(parent, name[-1]) PK͆3o88zope/testing/cleanup.py############################################################################## # # Copyright (c) 2001, 2002 Zope Corporation and Contributors. # All Rights Reserved. # # This software is subject to the provisions of the Zope Public License, # Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution. # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS # FOR A PARTICULAR PURPOSE. # ############################################################################## """Provide a standard cleanup registry Unit tests that change global data should include the CleanUp base class, which provides simpler setUp and tearDown methods that call global-data cleanup routines:: class Test(CleanUp, unittest.TestCase): .... If custom setUp or tearDown are needed, then the base routines should be called, as in:: def tearDown(self): super(Test, self).tearDown() .... Cleanup routines for global data should be registered by passing them to addCleanup:: addCleanUp(pigRegistry._clear) $Id: cleanup.py 29143 2005-02-14 22:43:16Z srichter $ """ _cleanups = [] def addCleanUp(func, args=(), kw={}): """Register a cleanup routines Pass a function to be called to cleanup global data. Optional argument tuple and keyword arguments may be passed. """ _cleanups.append((func, args, kw)) class CleanUp(object): """Mix-in class providing clean-up setUp and tearDown routines.""" def cleanUp(self): """Clean up global data.""" cleanUp() setUp = tearDown = cleanUp def cleanUp(): """Clean up global data.""" for func, args, kw in _cleanups: func(*args, **kw) setUp = tearDown = cleanUp PK͆3̲zope/testing/DEPENDENCIES.cfgzope.exceptions PKoz45+Jeezope/testing/formparser.txtParsing HTML Forms ================== Sometimes in functional tests, information from a generated form must be extracted in order to re-submit it as part of a subsequent request. The `zope.testing.formparser` module can be used for this purpose. The scanner is implemented using the `FormParser` class. The constructor arguments are the page data containing the form and (optionally) the URL from which the page was retrieved: >>> import zope.testing.formparser >>> page_text = '''\ ... ...
... ... ... ... ...
... ... Just for fun, a second form, after specifying a base: ... ...
... ... ... ... ...
... ... ''' >>> parser = zope.testing.formparser.FormParser(page_text) >>> forms = parser.parse() >>> len(forms) 2 >>> forms.form1 is forms[0] True >>> forms.form1 is forms[1] False More often, the `parse()` convenience function is all that's needed: >>> forms = zope.testing.formparser.parse( ... page_text, "http://cgi.example.com/somewhere/form.html") >>> len(forms) 2 >>> forms.form1 is forms[0] True >>> forms.form1 is forms[1] False Once we have the form we're interested in, we can check form attributes and individual field values: >>> form = forms.form1 >>> form.enctype 'application/x-www-form-urlencoded' >>> form.method 'post' >>> keys = form.keys() >>> keys.sort() >>> keys ['do-it-now', 'f1', 'not-really', 'pick-two'] >>> not_really = form["not-really"] >>> not_really.type 'image' >>> not_really.value "Don't." >>> not_really.readonly False >>> not_really.disabled False Note that relative URLs are converted to absolute URLs based on the ```` element (if present) or using the base passed in to the constructor. >>> form.action 'http://cgi.example.com/cgi-bin/foobar.py' >>> not_really.src 'http://cgi.example.com/somewhere/dont.png' >>> forms[1].action 'http://www.example.com/base/sproing/sprung.html' >>> forms[1]["action"].src 'http://www.example.com/base/else.png' Fields which are repeated are reported as lists of objects that represent each instance of the field:: >>> field = forms[1]["multi"] >>> type(field) >>> [o.value for o in field] ['', ''] >>> [o.size for o in field] [2, 3] The `` ... ... ... ... ... ... ''' >>> parser = zope.testing.formparser.FormParser(page_text) >>> forms = parser.parse() >>> len(forms) 2 >>> forms.form1 is forms[0] True >>> forms.form1 is forms[1] False More often, the `parse()` convenience function is all that's needed: >>> forms = zope.testing.formparser.parse( ... page_text, "http://cgi.example.com/somewhere/form.html") >>> len(forms) 2 >>> forms.form1 is forms[0] True >>> forms.form1 is forms[1] False Once we have the form we're interested in, we can check form attributes and individual field values: >>> form = forms.form1 >>> form.enctype 'application/x-www-form-urlencoded' >>> form.method 'post' >>> keys = form.keys() >>> keys.sort() >>> keys ['do-it-now', 'f1', 'not-really', 'pick-two'] >>> not_really = form["not-really"] >>> not_really.type 'image' >>> not_really.value "Don't." >>> not_really.readonly False >>> not_really.disabled False Note that relative URLs are converted to absolute URLs based on the ```` element (if present) or using the base passed in to the constructor. >>> form.action 'http://cgi.example.com/cgi-bin/foobar.py' >>> not_really.src 'http://cgi.example.com/somewhere/dont.png' >>> forms[1].action 'http://www.example.com/base/sproing/sprung.html' >>> forms[1]["action"].src 'http://www.example.com/base/else.png' Fields which are repeated are reported as lists of objects that represent each instance of the field:: >>> field = forms[1]["multi"] >>> type(field) >>> [o.value for o in field] ['', ''] >>> [o.size for o in field] [2, 3] The ``