[Checkins]
SVN: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/README.txt
Tests for 'filter_func'.
Uli Fouquet
uli at gnufix.de
Tue Feb 5 08:08:45 EST 2008
Log message for revision 83527:
Tests for 'filter_func'.
Changed:
U Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/README.txt
-=-
Modified: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/README.txt
===================================================================
--- Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/README.txt 2008-02-05 13:06:36 UTC (rev 83526)
+++ Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/README.txt 2008-02-05 13:08:45 UTC (rev 83527)
@@ -46,7 +46,7 @@
1) Make sure your testfiles are named properly (.txt/.rst for
doctests, valid python modules for usual unit tests) and provide a
- suitable marker string as explained below.
+ suitable marker string as explained below_.
2) Write a test setup module which is named so that your testrunner
finds it and in this module call::
@@ -57,6 +57,235 @@
object you can also pass the package's dotted name as string like
`'z3c.testsetup.tests.cave'`.
+Given that, this setup should find all doctests (unit and functional)
+as well as python tests in the package and register them.
+
+
+Customized Setups
+-----------------
+
+The `register_all_tests` function mentioned above accepts a bunch of
+keyword parameters::
+
+ register_all_tests(pkg_or_dotted_name, filter_func, extensions,
+ encoding, checker,
+ globs, setup, teardown, optionflags
+ zcml_config, layer_name, layer)
+
+where all but the first parameter are keyword paramters and all but
+the package parameter are optional.
+
+While `filter_func` and `extensions` determine the set of testfiles to
+be found, the other paramters tell how to setup single tests.
+
+
+- `filter_func` (`ufilter_func`, `ffilter_func`):
+
+ a function that takes an absolute filepath and returns `True` or
+ `False`, depending on whether the file should be included in the
+ test suite as doctest or not. `filter_func` applies only to
+ doctests.
+
+ We setup a few things to check that::
+
+ >>> import os
+ >>> import unittest
+ >>> suite = test_suite()
+ >>> suite.countTestCases()
+ 4
+
+ Okay, the callable in `test_suite` we created above with
+ `register_all_tests` apparently delivered four testcases. This is
+ normally also the number of files involved, but let's check that
+ correctly.
+
+ We did setup a function `get_filenames_from_suite` in this testing
+ environment (as a `globs` entry) which determines the paths of all
+ testcases contained in a `TestSuite`::
+
+ >>> testfiles = [os.path.basename(x)
+ ... for x in get_filenames_from_suite(suite)]
+ >>> testfiles.sort()
+ >>> testfiles
+ ['file1.py', 'file1.rst', 'file1.txt', 'subdirfile.txt']
+
+ Ah, okay. There are in fact four files, in which testcases were
+ found. Now, we define a plain filter function::
+
+ >>> def custom_file_filter(path):
+ ... """Accept all txt files."""
+ ... return os.path.basename(path).endswith('.txt')
+
+ This one accepts all '.txt' files. We run `register_all_tests`
+ again, but this time with a `filter_func` parameter::
+
+ >>> test_suite = z3c.testsetup.register_all_tests(
+ ... 'z3c.testsetup.tests.cave',
+ ... filter_func=custom_file_filter)
+
+ To get the resulting test suite, we again call the returned
+ callable::
+
+ >>> suite = test_suite()
+ >>> testfiles = [os.path.basename(x) for x in
+ ... get_filenames_from_suite(suite)]
+ >>> testfiles.sort()
+ >>> testfiles
+ ['file1.py', 'file1.txt', 'file1.txt', 'subdirfile.txt',
+ 'subdirfile.txt']
+
+ Compared with the first call to `register_all_tests` we got some
+ strange results here: there is a '.py' file, which should have been
+ refused by our filter function and the other two files appear
+ twice. What happened?
+
+ The python module is included, because python tests are not
+ filtered by `filter_func`. Instead this value applies only to
+ doctests.
+
+ The second strange result, that every .txt file appears twice in
+ the list, comes from the fact, that the filter is valid for unit
+ and functional doctests at the same time. In other words: the tests
+ in those .txt files are registered twice, as unittests and a second
+ time as functional tests as well.
+
+ If you want a filter function for functional doctests or unit
+ doctests only, then you can use `ffilter_func` and `ufilter_func`
+ respectively::
+
+ >>> test_suite = z3c.testsetup.register_all_tests(
+ ... 'z3c.testsetup.tests.cave',
+ ... ffilter_func=custom_file_filter,
+ ... ufilter_func=lambda x: False)
+
+ >>> suite = test_suite()
+ >>> testfiles = [os.path.basename(x) for x in
+ ... get_filenames_from_suite(suite)]
+ >>> testfiles.sort()
+ >>> testfiles
+ ['file1.py', 'file1.txt', 'subdirfile.txt']
+
+ As expected, every .txt file was only registered once. The same
+ happens, when we switch and accept only unit doctests::
+
+ >>> test_suite = z3c.testsetup.register_all_tests(
+ ... 'z3c.testsetup.tests.cave',
+ ... ffilter_func=lambda x: False,
+ ... ufilter_func=custom_file_filter)
+
+ >>> suite = test_suite()
+ >>> testfiles = [os.path.basename(x) for x in
+ ... get_filenames_from_suite(suite)]
+ >>> testfiles.sort()
+ >>> testfiles
+ ['file1.py', 'file1.txt', 'subdirfile.txt']
+
+ If you specify both, a `filter_func` and a more specialized
+ `ufilter_func` or `ffilter_func`, then this has the same effect as
+ passing both, `ufilter_func` and `ffilter_func`::
+
+ >>> test_suite = z3c.testsetup.register_all_tests(
+ ... 'z3c.testsetup.tests.cave',
+ ... ffilter_func=lambda x: False,
+ ... filter_func=custom_file_filter)
+
+ >>> suite = test_suite()
+ >>> testfiles = [os.path.basename(x) for x in
+ ... get_filenames_from_suite(suite)]
+ >>> testfiles.sort()
+ >>> testfiles
+ ['file1.py', 'file1.txt', 'subdirfile.txt']
+
+
+- `pfilter_func`:
+
+ Does the same for python unit tests.
+
+
+- `extensions`; a list of filename extensions to be considered during
+ test search. Default value is `['.txt',
+ '.rst']`. Python tests are not touched by this (they
+ have to be regular Python modules with '.py'
+ extension).
+
+- `encoding`: the testfiles encoding. 'utf-8' by default. Setting
+ this to `None` means system default encoding (normally
+ 7Bit ASCII encoding).
+
+- `checker`: An output checker for functional doctests. `None` by
+ default. A typical output checker can be created like
+ this::
+
+ >>> import re
+ >>> from zope.testing import renormalizing
+ >>> mychecker = renormalizing.RENormalizing([
+ ... (re.compile('[0-9]*[.][0-9]* seconds'),
+ ... '<SOME NUMBER OF> seconds'),
+ ... (re.compile('at 0x[0-9a-f]+'), 'at <SOME ADDRESS>'),
+ ... ])
+
+ This would match for example output like `0.123
+ seconds` if you write in your doctest::
+
+ <SOME NUBMER OF> seconds
+
+ Checkers are applied to functional doctests only!
+
+- `globs`: A dictionary of things that should be available
+ immediately (without imports) during tests. Defaults
+ are::
+
+ dict(http=HTTPCaller(),
+ getRootFolder=getRootFolder,
+ sync=sync)
+
+ for functional doctests and an empty dict for unit
+ doctests. Python test globals can't be set this way.
+
+ If you want to register special globals for functional
+ doctest or unit doctests only, then you can use the
+ `fglobs` and/or `uglobs` keyword respectively. These
+ keywords replace any `globs` value.
+
+- `setup`: A function that takes a `test` argument and is
+ executed before every single doctest. By default it
+ runs::
+
+ zope.app.testing.functional.FunctionalTestSetup().setUp()
+
+ for functional doctests and an empty function for unit
+ doctests. Python tests provide their own setups.
+
+ If you want to register special setup-functions for
+ either functional or unit doctests, then you can pass
+ keyword parameters `fsetup` or `usetup` respectively.
+
+- `teardown`: The equivalent to `setup`. Runs by default::
+
+ FunctionalTestSetup().tearDown()
+
+ for functional doctests and::
+
+ zope.testing.cleanup.cleanUp()
+
+ for unit doctests.
+
+- `optionflags`:
+
+- `zcml_config`:
+
+- `layer_name`:
+
+- `layer`:
+
+
+
+
+.. below:
+
+How to mark testfiles/modules
+-----------------------------
+
To avoid non-wanted files and modules to be registered, you have to
mark your wanted test files/modules with a special string explicitly:
More information about the Checkins
mailing list