= Trac Unit Tests = Many of the Trac Python modules are accompanied by unit tests. You should run the tests whenever making changes, to be confident you haven't broken anything. ''Note though that the coverage of application code by the unit tests is still rather poor, and even if it were better, not having broken the unit tests does not mean you haven't broken the application! Unit tests do not replace manual testing.'' Ideally, you'd also include new unit tests for a change or enhancement, even if you're just submitting a patch. Patches that break the unit tests are a lot less likely to get integrated than patches that add unit tests for the new or changed functionality. == Running the tests == You can run the unit tests from the command line by executing: {{{ python -m trac.test --skip-functional-tests }}} or unix way: {{{ $ PYTHONPATH=. python trac/test.py --skip-functional-tests }}} or: {{{ $ make unit-test }}} See [source:trunk/TESTING-README TESTING-README] for more details about functional tests. Assuming the current working directory is where you checked out the Trac code from the SubversionRepository. This will run all the unit tests, but you can also run only those tests for a specific package or module. For example, to run the unit tests for the {{{trac.versioncontrol}}} package, execute: {{{ python -m trac.versioncontrol.tests.__init__ }}} or if you prefer bash: {{{ $ PYTHONPATH=. trac/versioncontrol/tests/__init__.py }}} To run the unit tests for the {{{trac.versioncontrol.cache}}} module, execute: {{{ python -m trac.versioncontrol.tests.cache }}} or {{{ $ PYTHONPATH=. trac/versioncontrol/tests/cache.py }}} If you've made larger changes, then before running the tests, please make sure you've cleaned all {{{.pyc}}} files that may be left after removed or renamed source {{{*.py}}} files: {{{ $ find . -name *.pyc | xargs rm }}} === Test Database === If you're developing on database different from SQLite, you may want to specify its URI using {{{TRAC_TEST_DB_URI}}} environment variable. == Buildbots == The Trac unit tests are also being run by the [http://pybots.org/ Python Community Buildbots] project. Trac tests are executed regularly on both the latest Python version and development snapshots, so that the scope of backwards incompatible changes to Python can be easily detected. Look for the {{{x86 Gentoo trunk}}} buildslave on both [http://www.python.org/dev/buildbot/community/trunk/ Python trunk] and [http://www.python.org/dev/buildbot/community/2.5/ Python 2.5] (which Trac revision is being tested can be seen from the {{{pre-requisites installation}}} phase, which shows an {{{svn up}}} log). == Adding tests == If you're adding a new module, or you want to add tests for a module that doesn't have any unit tests yet, you'll need to create a new Python module for the unit tests. For example, say you want to add tests for the module {{{trac.foo}}} (which maps to {{{trac/foo.py}}}). You'll need to create a new module at {{{trac/tests/foo.py}}} and put the tests there. Also, you'll have to edit the {{{__init__.py}}} in the {{{tests}}} package so that your new unit tests get executed with the others. == Utility code for unit tests == The module [source:/trunk/trac/test.py#latest trac.test] contains a couple of functions and classes that can help writing unit tests. In particular, it provides an {{{InMemoryDatabase}}} class that can be used to test functionality that requires database access, without having to create an actual database on disk. Also there's a very simple factory for [http://c2.com/cgi/wiki?MockObject mock objects], which you can use to create quick substitutes of the "real" objects for testing. == Optional Dependencies == Some unit-tests depend on: * [http://pytz.sourceforge.net/ pytz] * [http://pygments.org/ Pygments] In addition, the figleaf package can be used to provide code coverage information: * [http://darcs.idyll.org/~t/projects/figleaf/README.html figleaf] These can be installed with easy_install: {{{ easy_install pytz easy_install Pygments easy_install figleaf }}} If these dependencies are not present, certain tests will be skipped. == Troubleshooting == For general advice about Trac debugging, see TracTroubleshooting. === !ImportError: no module named tests === If you try to run the tests and you receive {{{ ImportError: No module named tests }}} It may mean that you have a version of Trac installed in `/usr/lib/pythonX.X/site-packages` or `/usr/local/lib/pythonX.X/site-packages` but you are testing a different version installed elsewhere on your machine. If so, uninstalling the system version of Trac in /usr/lib/pythonX.X should allow you to run the unit tests, testing your private version. Installing your virtual environment with {{{--no-site-packages}}} should eliminate this problem. ---- See also: TracDev/FunctionalTests