<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.
  
**Note:** Only the ``unittest`` test runner supports running from the command line.
The other test runners cannot be used in this way.

