[Checkins] SVN: manuel/branches/regebro-python3/s Giving up for now, bugs in 2to3 with doctests stop further progress.
Lennart Regebro
regebro at gmail.com
Tue Jan 26 14:49:27 EST 2010
Log message for revision 108538:
Giving up for now, bugs in 2to3 with doctests stop further progress.
Changed:
U manuel/branches/regebro-python3/setup.py
U manuel/branches/regebro-python3/sphinx/conf.py
U manuel/branches/regebro-python3/src/manuel/README.txt
U manuel/branches/regebro-python3/src/manuel/doctest.py
A manuel/branches/regebro-python3/src/manuel/index.txt
U manuel/branches/regebro-python3/src/manuel/testing.py
U manuel/branches/regebro-python3/src/manuel/tests.py
-=-
Modified: manuel/branches/regebro-python3/setup.py
===================================================================
--- manuel/branches/regebro-python3/setup.py 2010-01-26 18:08:24 UTC (rev 108537)
+++ manuel/branches/regebro-python3/setup.py 2010-01-26 19:49:27 UTC (rev 108538)
@@ -1,5 +1,6 @@
from setuptools import setup, find_packages
import os
+import sys
long_description = (
open('README.txt').read()
@@ -7,6 +8,19 @@
+ open('CHANGES.txt').read()
)
+if sys.version > '3':
+ extras = dict(
+ dependency_links = ['.'],
+ use_2to3 = True,
+ convert_2to3_doctests = ['src/manuel/README.txt',
+ 'src/manuel/table-example.txt',
+ 'src/manuel/bugs.txt',
+ 'src/manuel/capture.txt',
+ ],)
+else:
+ extras = {}
+
+
setup(
name='manuel',
version='0',
@@ -24,4 +38,6 @@
],
include_package_data=True,
long_description = long_description,
+ test_suite = 'manuel.tests.test_suite',
+ **extras
)
Modified: manuel/branches/regebro-python3/sphinx/conf.py
===================================================================
--- manuel/branches/regebro-python3/sphinx/conf.py 2010-01-26 18:08:24 UTC (rev 108537)
+++ manuel/branches/regebro-python3/sphinx/conf.py 2010-01-26 19:49:27 UTC (rev 108538)
@@ -1,5 +1,5 @@
source_suffix = '.txt'
-master_doc = 'index'
+master_doc = 'manuel/index'
project = 'Manuel'
copyright = 'Benji York'
version = '1'
Modified: manuel/branches/regebro-python3/src/manuel/README.txt
===================================================================
--- manuel/branches/regebro-python3/src/manuel/README.txt 2010-01-26 18:08:24 UTC (rev 108537)
+++ manuel/branches/regebro-python3/src/manuel/README.txt 2010-01-26 19:49:27 UTC (rev 108538)
@@ -223,7 +223,7 @@
>>> for region in document:
... print (region.lineno, region.parsed or region.source)
(1, 'This is my\ndoctest.\n\n')
- (4, <zope.testing.doctest.Example instance at 0x...>)
+ (4, <zope.testing.doctest.Example ... at 0x...>)
Now we can evaluate the examples.
@@ -231,7 +231,7 @@
>>> for region in document:
... print (region.lineno, region.evaluated or region.source)
(1, 'This is my\ndoctest.\n\n')
- (4, <manuel.doctest.DocTestResult instance at 0x...>)
+ (4, <manuel.doctest.DocTestResult ... at 0x...>)
And format the results.
@@ -336,7 +336,7 @@
(1, '\nWe can have a list of numbers...\n\n')
(4, <NumbersTest object at 0x...>)
(5, '\n... and we can test Python.\n\n')
- (8, <doctest.Example instance at 0x...>)
+ (8, <doctest.Example ... at 0x...>)
(10, '\n')
We can look at the formatted output to see that each of the two tests failed.
@@ -377,7 +377,8 @@
... if region.parsed:
... continue
... if region.source.strip().endswith('my clone:'):
- ... to_be_cloned = document_iter.next().copy()
+ ... thenext = document_iter.next()
+ ... to_be_cloned = thenext.copy()
... break
... # if we found the region to cloned, do so
... if to_be_cloned:
@@ -518,7 +519,6 @@
>>> import StringIO
>>> import token
>>> import tokenize
-
>>> def informative_evaluater_2(region, document, globs):
... if not isinstance(region.parsed, doctest.Example):
... return
Modified: manuel/branches/regebro-python3/src/manuel/doctest.py
===================================================================
--- manuel/branches/regebro-python3/src/manuel/doctest.py 2010-01-26 18:08:24 UTC (rev 108537)
+++ manuel/branches/regebro-python3/src/manuel/doctest.py 2010-01-26 19:49:27 UTC (rev 108538)
@@ -1,10 +1,14 @@
import StringIO
import manuel
import os.path
-import zope.testing.doctest
doctest = manuel.absolute_import('doctest')
+try:
+ import zope.testing.doctest
+ example_types = (doctest.Example, zope.testing.doctest.Example,)
+except ImportError:
+ example_types = (doctest.Example, )
class DocTestResult(StringIO.StringIO):
pass
@@ -47,8 +51,7 @@
def evaluate(m, region, document, globs):
# If the parsed object is not a doctest Example (from either the stdlib
# doctest or zope.testing.doctest), then we don't need to handle it.
- if not isinstance(region.parsed, doctest.Example) \
- and not isinstance(region.parsed, zope.testing.doctest.Example):
+ if not isinstance(region.parsed, example_types):
return
result = DocTestResult()
Added: manuel/branches/regebro-python3/src/manuel/index.txt
===================================================================
--- manuel/branches/regebro-python3/src/manuel/index.txt (rev 0)
+++ manuel/branches/regebro-python3/src/manuel/index.txt 2010-01-26 19:49:27 UTC (rev 108538)
@@ -0,0 +1,974 @@
+======
+Manuel
+======
+
+Manuel lets you mix and match traditional doctests with custom test syntax.
+
+Several plug-ins are included that provide new test syntax (see
+:ref:`functionality`). You can also create your own plug-ins.
+
+For example, if you've ever wanted to include a large chunk of Python in a
+doctest but were irritated by all the ">>>" and "..." prompts required, you'd
+like the :mod:`manuel.codeblock` module. It lets you execute code using
+Sphinx-style ".. code-block:: python" directives. The markup looks like
+this::
+
+ .. code-block:: python
+
+ import foo
+
+ def my_func(bar):
+ return foo.baz(bar)
+
+Incidentally, the implementation of :mod:`manuel.codeblock` is only 23 lines of
+code.
+
+The plug-ins included in Manuel make good examples while being quite useful in
+their own right. The Manuel documentation makes extensive use of them as well.
+Follow the "Show Source" link to the left to see the `reST
+<http://docutils.sourceforge.net/rst.html>`_ source of this document.
+
+For a large example of creating test syntax, take a look at the
+:ref:`fit-table-example` or for all the details, :ref:`theory-of-operation`.
+
+To see how to get Manuel wired up see :ref:`getting-started`.
+
+.. contents::
+
+
+.. reset-globs
+.. _functionality:
+
+Included Functionality
+======================
+
+Manuel includes several plug-ins out of the box:
+
+:ref:`manuel.capture <capture>`
+ stores regions of a document in variables for later processing
+
+:ref:`manuel.codeblock <code-blocks>`
+ executes code in ".. code-block:: python" blocks
+
+:ref:`manuel.doctest <doctest>`
+ provides traditional doctest processing as a Manuel plug-in
+
+:ref:`manuel.footnote <footnotes>`
+ executes code in reST-style footnodes each time they're referenced (good
+ for getting incidental code out of the main flow of a document)
+
+:ref:`manuel.ignore <ignore>`
+ ignores parts of a document while running tests
+
+:ref:`manuel.isolation <isolation>`
+ makes it easier to have test isolation in doctests
+
+:ref:`manuel.testcase <testcase>`
+ identify parts of tests as individual test cases so they can be run
+ independently
+
+
+.. reset-globs
+.. _getting-started:
+
+Getting Started
+===============
+
+The plug-ins used for a test are composed together using the "+" operator.
+Let's say you wanted a test that used doctest syntax as well as footnotes. You
+would create a Manuel instance to use like this:
+
+.. code-block:: python
+
+ import manuel.doctest
+ import manuel.footnote
+
+ m = manuel.doctest.Manuel()
+ m += manuel.footnote.Manuel()
+
+You would then pass the Manuel instance to a :class:`manuel.testing.TestSuite`,
+including the names of documents you want to process:
+
+.. ignore-next-block
+.. code-block:: python
+
+ manuel.testing.TestSuite(m, 'test-one.txt', 'test-two.txt')
+
+
+Using unittest
+--------------
+
+The simplest way to get started with Manuel is to use :mod:`unittest` to run
+your tests:
+
+.. code-block:: python
+
+ import manuel.codeblock
+ import manuel.doctest
+ import manuel.testing
+ import unittest
+
+ def test_suite():
+ m = manuel.doctest.Manuel()
+ m += manuel.codeblock.Manuel()
+ return manuel.testing.TestSuite(m, 'test-one.txt', 'test-two.txt')
+
+ if __name__ == '__main__':
+ unittest.TextTestRunner().run(test_suite())
+
+
+Using zope.testing
+------------------
+
+If you want to use a more featureful test runner you can use zope.testing's
+test runner (usable stand-alone -- it isn't dependent on the Zope application
+server). Create a file named :file:`tests.py` with a :func:`test_setup`
+function that returns a test suite.
+
+The suite can be either a :class:`manuel.testing.TestSuite` object or a
+:class:`unittest.TestSuite` as demonstrated below.
+
+.. code-block:: python
+
+ import manuel.codeblock
+ import manuel.doctest
+ import manuel.testing
+
+ def test_suite():
+ suite = unittest.TestSuite()
+
+ # here you add your other tests to the suite...
+
+ # now you can add the Manuel tests
+ m = manuel.doctest.Manuel()
+ m += manuel.codeblock.Manuel()
+ suite.addTest(manuel.testing.TestSuite(m,
+ 'test-one.txt', 'test-two.txt'))
+
+ return suite
+
+
+Others
+------
+
+If you know out how to make Manuel work with other test runners (nose, py.test,
+etc.), please `send me an email`_ and I'll expand this section.
+
+.. _send me an email: benji+manuel at benjiyork.com
+
+
+.. reset-globs
+.. _doctest:
+
+Doctests
+========
+
+Manuel is all about making testable documents and well-documented tests. Of
+course, Python's doctest module is a long-standing fixture in that space, so it
+only makes sense for Manuel to support doctest syntax.
+
+Handling doctests is easy:
+
+.. ignore-next-block
+.. code-block:: python
+
+ import manuel.doctest
+
+ m = manuel.doctest.Manuel()
+ suite = manuel.testing.TestSuite(m, 'my-doctest.txt')
+
+Of course you can mix in other Manuel syntax plug-ins as well (including ones
+you write yourself).
+
+.. ignore-next-block
+.. code-block:: python
+
+ import manuel.doctest
+ import manuel.codeblock
+
+ m = manuel.doctest.Manuel()
+ m += manuel.codeblock.Manuel()
+ suite = manuel.testing.TestSuite(m, 'my-doctest-with-code-blocks.txt')
+
+The :class:`manuel.doctest.Manuel` constructor also takes :data:`optionflags`
+and :data:`checker` arguments.
+
+.. ignore-next-block
+.. code-block:: python
+
+ m = manuel.doctest.Manuel(optionflags=optionflags, checker=checker)
+
+See the `doctest documentation <http://docs.python.org/library/doctest.html>`_
+for more information about the `available options
+<http://docs.python.org/library/doctest.html#doctest-options>`_ and `output
+checkers <http://docs.python.org/library/doctest.html#outputchecker-objects>`_
+
+
+.. note:: :mod:`zope.testing.renormalizing` provides an :class:`OutputChecker`
+ for smoothing out differences between actual and expected output for things
+ that are hard to control (like memory addresses and time). See the
+ `module's doctests <http://svn.zope.org/zope.testing/trunk/src/zope/testing/renormalizing.py?view=markup>`_
+ for more information on how it works.
+
+
+.. reset-globs
+.. _capture:
+
+Capturing Blocks
+================
+
+When writing documentation the need often arises to describe the contents of
+files or other non-Python information. You may also want to put that
+information under test. :mod:`manuel.capture` helps with that.
+
+For example, if you were writing the problems for a programming contest, you
+might want to describe the input and output files for each challenge, but you
+want to be sure that your examples are correct.
+
+To do that you might write your document like this:
+
+::
+
+ Challenge 1
+ ===========
+
+ Write a program that sorts the numbers in a file.
+
+
+ Example
+ -------
+
+ Given this example input file::
+
+ 6
+ 1
+ 8
+ 20
+ 11
+ 65
+ 2
+
+ .. -> input
+
+ Your program should generate this output file::
+
+ 1
+ 2
+ 6
+ 8
+ 11
+ 20
+ 65
+
+ .. -> output
+
+ >>> input_lines = input.splitlines()
+ >>> correct = '\n'.join(map(str, sorted(map(int, input_lines)))) + '\n'
+ >>> output == correct
+ True
+
+.. -> source
+
+ >>> import manuel
+ >>> document = manuel.Document(source)
+ >>> import manuel.capture
+ >>> m = manuel.capture.Manuel()
+ >>> import manuel.doctest
+ >>> m += manuel.doctest.Manuel()
+ >>> document.process_with(m, globs={})
+ >>> print document.formatted(),
+
+This uses the syntax implemented in :mod:`manuel.capture` to capture a block of
+text into a variable (the one named after "->").
+
+Whenever a line of the structure ".. -> VAR" is detected, the text of the
+*previous* block will be stored in the given variable.
+
+.. the paragraph below could be phrased better
+
+Of course, lines that start with ".. " are reST comments, so when the document
+is rendered with docutils or Sphinx, the tests will dissapear and only the
+intended document contents will remain. Like so::
+
+ Challenge 1
+ ===========
+
+ Write a program that sorts the numbers in a file.
+
+
+ Example
+ -------
+
+ Given this example input file::
+
+ 6
+ 1
+ 8
+ 20
+ 11
+ 65
+ 2
+
+ Your program should generate this output file::
+
+ 1
+ 2
+ 6
+ 8
+ 11
+ 20
+ 65
+
+
+.. reset-globs
+.. _code-blocks:
+
+Code Blocks
+===========
+
+`Sphinx <http://sphinx.pocoo.org/>`_ and other docutils `extensions
+<http://docutils.sourceforge.net/sandbox/code-block-directive/docs/syntax-highlight.html>`_
+provide a `"code-block" directive <http://sphinx.pocoo.org/markup/code.html>`_,
+which allows inlined snippets of code in reST documents.
+
+The :mod:`manuel.codeblock` module provides the ability to execute the contents
+of Python code-blocks. For example::
+
+ .. code-block:: python
+
+ print 'hello'
+
+.. Let's create a reST document with a code block.
+
+ >>> import manuel.codeblock
+ >>> document = manuel.Document("""
+ ... Here is a code-block:
+ ...
+ ... .. code-block:: python
+ ...
+ ... x = 'hello'
+ ...
+ ... A little prose to separate the examples.
+ ...
+ ... >>> print x
+ ... hello
+ ...
+ ... """)
+
+.. Since the above document mixes code-blocks and doctests, we'll mix in the
+ doctest handler.
+
+ >>> import manuel.doctest
+ >>> m = manuel.codeblock.Manuel()
+ >>> m += manuel.doctest.Manuel()
+ >>> document.process_with(m, globs={})
+
+ Both code blocks were found (for a total of five regions -- text, block,
+ text, block, and text):
+
+ >>> len(list(document))
+ 5
+
+ We can see that none of the tests in the document failed:
+
+ >>> print document.formatted(),
+
+If the code-block generates some sort of error...
+
+.. code-block:: python
+
+ .. code-block:: python
+
+ print does_not_exist
+
+.. -> source
+
+ >>> document = manuel.Document(source, location='fake.txt')
+
+.. the document above was specially formulated to have nothing before or after
+ the code-block
+
+ >>> document.source.startswith('.. code-block')
+ True
+ >>> document.source.endswith('print does_not_exist\n')
+ True
+
+...that error will be reported:
+
+ >>> document.process_with(m, globs={})
+ Traceback (most recent call last):
+ ...
+ NameError: name 'does_not_exist' is not defined
+
+If you find that you want to include a code-block in a document but don't want
+Manuel to execute it, use :ref:`manuel.ignore <ignore>` to ignore that
+particular block.
+
+
+Invisible Code Blocks
+---------------------
+
+At times you'll want to have a block of code that is executed but not displayed
+in the rendered document (like some setup for later examples).
+
+When using doctest's native format (">>>") that's easy to do, you just put the
+code in a reST comment, like so:
+
+::
+
+ .. this is some setup, it is hidden in a reST comment
+
+ >>> a = 5
+ >>> b = a + 3
+
+However, if you want to include a relatively large chunk of Python, you'd
+rather use a code-block, but that means that it will be included in the
+rendered document. Instead, :mod:`manuel.codeblock` also understands a variant
+of the code-block directive that is actually a reST comment: "..
+invisible-code-block:: python"::
+
+ .. invisible-code-block:: python
+
+ a = 5
+ b = a + 3
+
+.. -> source
+
+ >>> import manuel
+ >>> document = manuel.Document(source)
+ >>> document.process_with(m, globs={})
+ >>> print document.formatted()
+
+.. note: The "invisible-code-block" directive will work with either one or two
+ colons. The reason is that reST processers (like docutils and Sphinx) will
+ generate an error for unrecognized directives (like invisible-code-block).
+ Therefore you can use a single colon and the line will be interpreted as a
+ comment instead.
+
+.. the single-colon variant works too
+
+ >>> document = manuel.Document("""
+ ...
+ ... .. invisible-code-block: python
+ ...
+ ... raise RuntimeError('it worked!')
+ ...
+ ... """)
+ >>> document.process_with(m, globs={})
+ Traceback (most recent call last):
+ ...
+ RuntimeError: it worked!
+
+
+.. reset-globs
+.. _footnotes:
+
+Footnotes
+=========
+
+The :mod:`manuel.footnote` module provides an implementation of reST footnote
+handling, but instead of just plain text, the footnotes can contain any syntax
+Manuel can interpret including doctests.
+
+ >>> import manuel.footnote
+ >>> m = manuel.footnote.Manuel()
+
+Here's an example of combining footnotes with doctests:
+
+.. so we also need the doctest Manuel plug-in
+
+ >>> import manuel.doctest
+ >>> m += manuel.doctest.Manuel()
+
+::
+
+ Here we reference a footnote. [1]_
+
+ >>> x
+ 42
+
+ Here we reference another. [2]_
+
+ >>> x
+ 100
+
+ .. [1] This is a test footnote definition.
+
+ >>> x = 42
+
+ .. [2] This is another test footnote definition.
+
+ >>> x = 100
+
+ .. [3] This is a footnote that will never be executed.
+
+ >>> raise RuntimeError('nooooo!')
+
+.. -> source
+
+ >>> import manuel
+ >>> document = manuel.Document(source)
+ >>> document.process_with(m, globs={})
+ >>> print document.formatted(),
+
+.. The order of examples in footnotes is preserved. If not, the document below
+ would generate an error because "a" won't be defined when "b = a + 1" is
+ evaluated.
+
+ >>> document = manuel.Document("""
+ ... Here we want some imports to be done. [foo]_
+ ...
+ ... >>> a + b
+ ... 3
+ ...
+ ... A little prose to separate the examples.
+ ...
+ ... .. [foo] Do something
+ ...
+ ... >>> a = 1
+ ...
+ ... >>> b = a + 1
+ ...
+ ... """)
+ >>> document.process_with(m, globs={})
+ >>> print document.formatted()
+
+It is also possible to reference more than one footnote on a single line.
+
+::
+
+ This line has several footnotes on it. [1]_ [2]_ [3]_
+
+ >>> z
+ 105
+
+ A little prose to separate the examples.
+
+ .. [1] Do something
+
+ >>> w = 3
+
+ .. [2] Do something
+
+ >>> x = 5
+
+ .. [3] Do something
+
+ >>> y = 7
+
+ >>> z = w * x * y
+
+.. -> source2
+
+ >>> document = manuel.Document(source)
+ >>> document.process_with(m, globs={})
+ >>> print document.formatted()
+
+
+.. reset-globs
+.. _ignore:
+
+Ignoring Blocks
+===============
+
+.. reset-globs
+
+Occasionally the need arises to ignore a block of markup that would otherwise
+be parsed by a Manuel plug-in.
+
+For example, this document has a code-block that will generate a syntax error::
+
+ The following is invalid Python.
+
+ .. code-block:: python
+
+ def foo:
+ pass
+
+.. -> source
+
+ >>> import manuel
+ >>> document = manuel.Document(source)
+ >>> import manuel.codeblock
+ >>> m = manuel.codeblock.Manuel()
+
+We can see that when executed, the SyntaxError escapes.
+
+ >>> import manuel.codeblock
+ >>> m = manuel.codeblock.Manuel()
+ >>> document.process_with(m, globs={})
+ Traceback (most recent call last):
+ ...
+ File "<memory>:4", line 2
+ def foo:
+ ^
+ SyntaxError: invalid syntax
+
+The :mod:`manuel.ignore` module provides a way to ignore parts of a document
+using a directive ".. ignore-next-block".
+
+Because Manuel plug-ins are executed in the order they are accumulated, we want
+:mod:`manuel.ignore` to be the base Manuel object, with any additional plug-ins
+added to it.
+
+.. code-block:: python
+
+ import manuel.ignore
+ import manuel.doctest
+ m = manuel.ignore.Manuel()
+ m += manuel.codeblock.Manuel()
+ m += manuel.doctest.Manuel()
+
+If we add an ignore marker to the block we don't want processed...
+
+.. code-block:: python
+
+ The following is invalid Python.
+
+ .. ignore-next-block
+ .. code-block:: python
+
+ def foo:
+ pass
+
+.. -> source
+
+ >>> document = manuel.Document(source)
+
+...the error goes away.
+
+ >>> document.process_with(m, globs={})
+ >>> print document.formatted(),
+
+
+Ignoring Literal Blocks
+-----------------------
+
+Ignoring literal blocks is a little more involved::
+
+ Here is some invalid Python:
+
+ .. ignore-next-block
+
+ ::
+
+ >>> lambda: print 'hi'
+
+.. -> source
+
+ >>> document = manuel.Document(source)
+
+ >>> document.process_with(m, globs={})
+ >>> print document.formatted(),
+
+.. we want to be very sure that the above example without the ignore actually
+ generates an error:
+
+ >>> document = manuel.Document(document.source.replace(
+ ... '.. ignore-next-block', ''))
+ >>> document.process_with(m, globs={})
+ >>> print document.formatted(),
+ File "<memory>"...
+ Failed example:
+ lambda: print 'hi'
+ Exception raised:
+ ...
+ File "<doctest <memory>[0]>", line 1
+ lambda: print 'hi'
+ ^
+ SyntaxError: invalid syntax
+
+
+.. reset-globs
+.. _isolation:
+
+Test Isolation
+==============
+
+One of the advantages of unittest over doctest is that the individual tests are
+isolated from one-another.
+
+In large doctests (like this one) you may want to keep later tests from
+depending on incidental details of earlier tests, preventing the tests from
+becoming brittle and harder to change.
+
+Test isolation is one approach to reducing this intra-doctest coupling. The
+:mod:`manuel.isolation` module provides a plug-in to help.
+
+The ".. reset-globs" directive resets the globals in the test::
+
+ We define a variable.
+
+ >>> x = 'hello'
+
+ It is still defined.
+
+ >>> print x
+ hello
+
+ Now we can reset the globals...
+
+ .. reset-globs
+
+ ...and the name binding will be gone:
+
+ >>> print x
+ Traceback (most recent call last):
+ ...
+ NameError: name 'x' is not defined
+
+.. -> source
+
+ >>> import manuel
+ >>> document = manuel.Document(source)
+ >>> import manuel.isolation
+ >>> import manuel.doctest
+ >>> m = manuel.isolation.Manuel()
+ >>> m += manuel.doctest.Manuel()
+
+We can see that after the globals have been reset, the second "print x" line
+raises an error.
+
+Of course, resetting to an empty set of global variables isn't always what's
+wanted. In that case there is a ".. capture-globs" directive that saves a
+baseline set of globals that will be restored at each reset.
+
+::
+
+ We define a variable.
+
+ >>> x = 'hello'
+
+ It is still defined.
+
+ >>> print x
+ hello
+
+ We can capture the currently defined globals:
+
+ .. capture-globs
+
+ Of course capturing the globals doesn't disturb them.
+
+ >>> print x
+ hello
+
+ Now if we define a new global...
+
+ >>> y = 'goodbye'
+ >>> print y
+ goodbye
+
+ .. reset-globs
+
+ ...it will disappear after a reset.
+
+ >>> print y
+ Traceback (most recent call last):
+ ...
+ NameError: name 'y' is not defined
+
+ But the captured globals will still be defined.
+
+ >>> print x
+ hello
+
+.. -> source
+
+ >>> import manuel
+ >>> document = manuel.Document(source)
+ >>> document.process_with(m, globs={})
+ >>> print document.formatted(),
+
+
+.. reset-globs
+.. _testcase:
+
+Identifying Test Cases
+======================
+
+If you want parts of a document to be individually accessible as test cases (to
+be able to run just a particular subset of them, for example), a parser can
+create a region that marks the beginning of a new test case.
+
+Two ways of identifying test cases are included in :mod:`manuel.testcase`:
+
+1. by section headings
+
+2. by explicit ".. test-case: NAME" markers.
+
+Grouping Tests by Heading
+-------------------------
+
+::
+
+ First Section
+ =============
+
+ Some prose.
+
+ >>> print 'first test case'
+
+ Some more prose.
+
+ >>> print 'still in the first test case'
+
+ Second Section
+ ==============
+
+ Even more prose.
+
+ >>> print 'second test case'
+
+.. -> source
+
+ >>> import manuel
+ >>> import manuel.testcase
+ >>> document = manuel.Document(source)
+ >>> m = manuel.testcase.SectionManuel()
+ >>> m += manuel.doctest.Manuel()
+ >>> document.process_with(m, globs={})
+ >>> print document.formatted(),
+ File "<memory>"...
+ Failed example:
+ print 'first test case'
+ Expected nothing
+ Got:
+ first test case
+ File "<memory>"...
+ Failed example:
+ print 'still in the first test case'
+ Expected nothing
+ Got:
+ still in the first test case
+ File "<memory>"...
+ Failed example:
+ print 'second test case'
+ Expected nothing
+ Got:
+ second test case
+
+.. now lets see if the regions are grouped as we expect
+
+ >>> import manuel.testing
+ >>> for regions in manuel.testing.group_regions_by_test_case(document):
+ ... print (regions.location, regions.id)
+ ('<memory>', None)
+ ('<memory>', 'First Section')
+ ('<memory>', 'Second Section')
+
+Given the above document, if you're using zope.testing's testrunner (located in bin/test), you could run just the tests in the second section with this command::
+
+ bin/test -t "file-name.txt:Second Section"
+
+Or, exploiting the fact that -t does a regex search (as opposed to a match)::
+
+ bin/test -t file-name.txt:Second
+
+
+Grouping Tests Explicitly
+-------------------------
+
+If you would like to identify test cases separately from sections, you can
+identify them with a marker::
+
+ First Section
+ =============
+
+ The following test will be in a test case that is not individually
+ identifiable.
+
+ >>> print 'first test case (unidentified)'
+
+ Some more prose.
+
+ .. test-case: first-named-test-case
+
+ >>> print 'first identified test case'
+
+
+ Second Section
+ ==============
+
+ The test case markers don't have to immediately proceed a test.
+
+ .. test-case: second-named-test-case
+
+ Even more prose.
+
+ >>> print 'second identified test case'
+
+.. -> source
+
+ >>> document = manuel.Document(source)
+ >>> m = manuel.testcase.MarkerManuel()
+ >>> m += manuel.doctest.Manuel()
+ >>> document.parse_with(m)
+ >>> for regions in manuel.testing.group_regions_by_test_case(document):
+ ... print regions.location, regions.id
+ <memory> None
+ <memory> first-named-test-case
+ <memory> second-named-test-case
+
+Again, given the above document and zope.testing, you could run just the second
+set of tests with this command::
+
+ bin/test -t file-name.txt:second-named-test-case
+
+Or, exploiting the fact that -t does a regex search again::
+
+ bin/test -t file-name.txt:second
+
+Even though the tests are individually accessable doesn't mean that they can't
+all be run at the same time::
+
+ bin/test -t file-name.txt
+
+Also, if you create a hierarchy of names, you can run groups of tests at a
+time. For example, lets say that you append "-important" to all your really
+important tests, you could then run the important tests for a single document
+like so::
+
+ bin/test -t 'file-name.txt:.*-important$'
+
+or all the "important" tests no matter what file they are in::
+
+ bin/test -t '-important$'
+
+Both Methods
+------------
+
+You can also combine more than one test case identification method if you want.
+Here's an example of building a Manuel stack that has doctests and both flavors
+of test case identification:
+
+.. code-block:: python
+
+ import manuel.doctest
+ import manuel.testcase
+
+ m = manuel.doctest.Manuel()
+ m += manuel.testcase.SectionManuel()
+ m += manuel.testcase.MarkerManuel()
+
+.. make sure above finds all the test cases appropriately
+
+ >>> document.parse_with(m)
+ >>> for regions in manuel.testing.group_regions_by_test_case(document):
+ ... print regions.location, regions.id
+ <memory> None
+ <memory> First Section
+ <memory> first-named-test-case
+ <memory> Second Section
+ <memory> second-named-test-case
+
+
+Further Reading
+===============
+
+.. toctree::
+ :maxdepth: 1
+
+ manuel/README.txt
+ manuel/table-example.txt
+ manuel/bugs.txt
Modified: manuel/branches/regebro-python3/src/manuel/testing.py
===================================================================
--- manuel/branches/regebro-python3/src/manuel/testing.py 2010-01-26 18:08:24 UTC (rev 108537)
+++ manuel/branches/regebro-python3/src/manuel/testing.py 2010-01-26 19:49:27 UTC (rev 108538)
@@ -2,8 +2,14 @@
import manuel
import os.path
import unittest
-import zope.testing.doctest
+doctest = manuel.absolute_import('doctest')
+try:
+ from zope.testing.doctest import _normalize_module, _module_relative_path
+except ImportError:
+ from zope.testing import _normalize_module, _module_relative_path
+
+
__all__ = ['TestSuite']
class TestCaseMarker(object):
@@ -36,7 +42,7 @@
results = [r.formatted for r in self.regions if r.formatted]
if results:
DIVIDER = '-'*70 + '\n'
- raise zope.testing.doctest.DocTestFailureException(
+ raise AssertionError(
'\n' + DIVIDER + DIVIDER.join(results))
def debug(self):
@@ -130,8 +136,7 @@
# walk up the stack frame to find the module that called this function
for depth in range(2, 5):
try:
- calling_module = zope.testing.doctest._normalize_module(
- None, depth=depth)
+ calling_module = _normalize_module(None, depth=depth)
except KeyError:
continue
else:
@@ -142,8 +147,8 @@
abs_path = os.path.normpath(path)
else:
abs_path = os.path.abspath(
- zope.testing.doctest._module_relative_path(
- calling_module, path))
+ _module_relative_path(calling_module,path)
+ )
document = manuel.Document(
open(abs_path, 'U').read(), location=abs_path)
Modified: manuel/branches/regebro-python3/src/manuel/tests.py
===================================================================
--- manuel/branches/regebro-python3/src/manuel/tests.py 2010-01-26 18:08:24 UTC (rev 108537)
+++ manuel/branches/regebro-python3/src/manuel/tests.py 2010-01-26 19:49:27 UTC (rev 108538)
@@ -8,6 +8,7 @@
import manuel.testing
import os.path
import re
+import sys
import unittest
doctest = manuel.absolute_import('doctest')
@@ -20,15 +21,18 @@
(re.compile(r'<zope\.testing\.doctest\.'), '<doctest.'),
])
- tests = ['../index.txt', 'table-example.txt', 'README.txt', 'bugs.txt',
- 'capture.txt']
+ tests = ['table-example.txt', 'README.txt', 'bugs.txt','capture.txt']
+ if sys.version < '3':
+ # This test can not be automatically 2to3:d, because it intentionally
+ # contains invalid python, and 2to3 can't handle that.
+ tests.append('../index.txt')
m = manuel.ignore.Manuel()
m += manuel.doctest.Manuel(optionflags=optionflags, checker=checker)
m += manuel.codeblock.Manuel()
m += manuel.capture.Manuel()
- return manuel.testing.TestSuite(m, *tests,
- globs={'path_to_test': os.path.join(here, 'bugs.txt')})
+ kw = {'globs': {'path_to_test': os.path.join(here, 'bugs.txt')}}
+ return manuel.testing.TestSuite(m, *tests, **kw)
if __name__ == '__main__':
More information about the checkins
mailing list