#! /usr/bin/env python2.3
##############################################################################
#
# 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.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.
#
##############################################################################
"""
test.py [-abBcdDfFgGhklLmMPprstTuUv] [modfilter [testfilter]]

Find and run tests written using the unittest module.

The test runner searches for Python modules that contain test suites.
It collects those suites, and runs the tests.  There are many options
for controlling how the tests are run.  There are options for using
the debugger, reporting code coverage, and checking for refcount problems.

The test runner uses the following rules for finding tests to run.  It
searches for packages and modules that contain "tests" as a component
of the name, e.g. "frob.tests.nitz" matches this rule because tests is
a sub-package of frob.  Within each "tests" package, it looks for
modules that begin with the name "test."  For each test module, it
imports the module and calls the module's test_suite() function, which must
return a unittest TestSuite object.

Options can be specified as command line arguments (see below). However,
options may also be specified in a file named 'test.config', a Python
script which, if found, will be executed before the command line
arguments are processed.

The test.config script should specify options by setting zero or more of the
global variables: LEVEL, BUILD, and other capitalized variable names found in
the test runner script (see the list of global variables in process_args().).


-a level
--at-level level
--all
    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.  The default is to run tests at level 1.  --all is
    a shortcut for -a 0.

-b
--build
    Run "python setup.py build" before running tests, where "python"
    is the version of python used to run test.py.  Highly recommended.
    Tests will be run from the build directory.

-B
--build-inplace
    Run "python setup.py build_ext -i" before running tests.  Tests will be
    run from the source directory.

-c
--pychecker
    use pychecker

-d
--debug
    Instead of the normal test harness, run a debug version which
    doesn't catch any exceptions.  This is occasionally handy when the
    unittest code catching the exception doesn't work right.
    Unfortunately, the debug harness doesn't print the name of the
    test, so Use With Care.

-D
--debug-inplace
    Works like -d, except that it loads pdb when an exception occurs.

--dir directory
-s directory
    Option to limit where tests are searched for. This is important
    when you *really* want to limit the code that gets run.  This can
    be specified more than once to run tests in two different 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.

-f
--skip-unit
    Run functional tests but not unit tests.
    Note that functional tests will be skipped if the module
    zope.app.tests.functional cannot be imported.
    Functional tests also expect to find the file ftesting.zcml,
    which is used to configure the functional-test run.

-F
    DEPRECATED. Run both unit and functional tests.
    This option is deprecated, because this is the new default mode.
    Note that functional tests will be skipped if the module
    zope.app.tests.functional cannot be imported.

-g threshold
--gc-threshold threshold
    Set the garbage collector generation0 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 "-g 0" to disable garbage collection altogether.

-G gc_option
--gc-option gc_option
    Set the garbage collection debugging flags.  The argument must be one
    of the DEBUG_ flags defined bythe Python gc module.  Multiple options
    can be specified by using "-G OPTION1 -G OPTION2."

-k
--keepbytecode
    Do not delete all stale bytecode before running tests

-l test_root
--libdir test_root
    Search for tests starting in the specified start directory
    (useful for testing components being developed outside the main
    "src" or "build" trees).

-L
--loop
    Keep running the selected tests in a loop.  You may experience
    memory leakage.

-m
-M  minimal GUI. See -U.

-P
--profile
    Run the tests under hotshot and display the top 50 stats, sorted by
    cumulative time and number of calls.

-p
--progress
    Show running progress.  It can be combined with -v or -vv.

-r
--refcount
    Look for refcount problems.
    This requires that Python was built --with-pydebug.

-t
--top-fifty
    Time the individual tests and print a list of the top 50, sorted from
    longest to shortest.

--times n
--times outfile
    With an integer argument, time the tests and print a list of the top <n>
    tests, sorted from longest to shortest.
    With a non-integer argument, specifies a file to which timing information
    is to be printed.

-T
--trace
    Use the trace module from Python for code coverage.  The current
    utility writes coverage files to a directory named `coverage' that
    is parallel to `build'.  It also prints a summary to stdout.

-u
--skip-functional
    CHANGED. Run unit tests but not functional tests.
    Note that the meaning of -u is changed from its former meaning,
    which is now specified by -U or --gui.

-U
--gui
    Use the PyUnit GUI instead of output to the command line.  The GUI
    imports tests on its own, taking care to reload all dependencies
    on each run.  The debug (-d), verbose (-v), progress (-p), and
    Loop (-L) options will be ignored.  The testfilter filter is also
    not applied.

-m
-M
--minimal-gui
    Note: -m is DEPRECATED in favour of -M or --minimal-gui.
    -m starts the gui minimized.  Double-clicking the progress bar
    will start the import and run all tests.


-v
--verbose
    Verbose output.  With one -v, unittest prints a dot (".") for each
    test run.  With -vv, unittest prints the name of each test (for
    some definition of "name" ...).  With no -v, unittest is silent
    until the end of the run, except when errors occur.

    When -p is also specified, the meaning of -v is slightly
    different.  With -p and no -v only the percent indicator is
    displayed.  With -p and -v the test name of the current test is
    shown to the right of the percent indicator.  With -p and -vv the
Operation mode
