<type>documentation</type>
<domain>testing</domain>
<id>run-from-cmd-line</id>
<title>Running unittest Tests from the Command Line</title>
<date>$Date: 2006-05-24 22:53:07 -0400 (Wed, 24 May 2006) $</date>
<version>$Revision: 13098 $</version>
<product>pro+</product>

Wing's test runner for the ``unittest`` testing framework can be run from the command line,
in order to store results in an XML file that can be loaded into Wing later using 
``Load Test Results`` in the ``Testing`` menu. The test runner is
``src/testing/runners/run_unittest_xml.py`` within the ``Install Directory`` listed in Wing's
`About <script:about-application>`__ box. It should be started as in the following
example::

  /path/to/python /path/to/wing/src/testing/runners/run_unittests_xml.py [options] -q testModule.className.testName

Replace ``/path/to/python`` with the Python that should be used to run the tests,
``/path/to/wing`` with the installation directory for Wing, ``[options]`` with any of the
command line options listed below, and ``testModule.className.testName`` with the real
test specification.

In the test specification, ``testModule`` is the module name (without ``.py``),
``className`` is the test class name, and ``testName`` is the name of the test method to
run. To run all tests in a class, omit ``testName``. To run all tests in a module,
also omit ``className``.

**Command Line Options**

``--directory=<dirname>`` runs the tests in the given directory.  When omitted, the 
tests are run in the current directory, inherited from the command line.

``--output-file=<filename>`` writes results to the selected file.  When omitted, 
results are written to ``stdout``.

``--append-to-file`` appends results to the file selected with the ``--output-file`` 
option, rather than truncating the file.

``--one-module-per-process`` runs each module in a separate process space 
to avoid unintended interactions between the tests.  Tests are still run
sequentially and not concurrently.

``--pattern=<glob filename pattern>`` runs tests in each filename matching
the given pattern.  This option may be repeated multiple times with 
different wildcards.  This option also turns on the ``--one-module-per-process`` 
option.
  
**Notes:** Only the ``unittest`` test runner supports running from the command line.
The other test runners cannot be used in this way.  Also, running tests from the
command line will not collect and update code coverage data.

