Trac Unit Tests

Unit tests assist in developing code that meets requirements and prevent regressions when modifying code. Most of the Python modules in the Trac codebase are accompanied by unit tests. The test modules are found in the tests directory of each package directory.

You should run the tests whenever making changes, to be confident you haven't broken anything. Note however that the coverage of application code by the unit tests is incomplete, so not having broken the unit tests does not mean you haven't broken the application! Unit tests do not replace manual testing.

Please include unit tests that provide coverage for a change or enhancement, even if you are 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 all of the unit tests from the command line using make:

$ make unit-test

or by invoking python directly:

$ python -m trac.test --skip-functional-tests

or the Unix way:

$ PYTHONPATH=. python trac/test.py --skip-functional-tests

See FunctionalTests and ​apidoc:dev/testing for more details about functional tests.

This assumes the current working directory is where you checked out the Trac code from the SubversionRepository.

You can also run only the tests for a specific package, module, class or method. For example, to run the unit tests for the trac.versioncontrol package, execute:

$ make test=trac.versioncontrol.tests

or:

$ python -m unittest trac.versioncontrol.tests.__init__.test_suite

To run the unit tests for the trac.versioncontrol.cache module, execute:

$ make test=trac.versioncontrol.tests.cache

or:

$ python -m unittest trac.versioncontrol.tests.cache.test_suite

To run the unit tests for the test class trac.versioncontrol.tests.cache.CacheTestCase, execute:

$ python -m unittest trac.versioncontrol.tests.cache.CacheTestCase

To run the test case trac.versioncontrol.tests.cache.CacheTestCase.test_initial_sync, execute:

$ python -m unittest trac.versioncontrol.tests.cache.CacheTestCase.test_initial_sync

In Trac 1.4 and later, unittest ​command line options can be passed in the Makefile argument testopts. Example:

$ make unit-test testopts="-f -c"

If you've made larger changes, before running the tests please make sure you've cleaned all .pyc files that may be left after removed or renamed source *.py files:

$ make clean

or:

$ find . -name *.pyc | xargs rm

Test Database

If you are developing on a database different from SQLite, you may want to specify its URI using the TRAC_TEST_DB_URI environment variable.

If you use the Makefile the database can be specified using the db argument:

$ make db=postgres test
$ make db=mysql test
$ make db=sqlite test

Note that make db=sqlite test runs the tests with an on-disk SQLite database. make test uses an in-memory SQLite database.

Automatic builds

The Trac unit tests are also run by the AutomaticBuilds.

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.

WritingUnitTests is a tutorial for writing your own unit tests.

Utility code for unit tests

The module trac.test​ contains a couple of functions and classes that can help writing unit tests. In particular, it provides an EnvironmentStub class which will allow the tests to run faster than using a real Environment. There's also a very simple factory for ​mock objects, which you can use to create quick substitutes of the "real" objects for testing.

Optional Dependencies

Some unit-tests depend on:

• ​pytz
• ​Pygments

These can be installed with pip:

pip install pytz
pip install Pygments

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 the following message:

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, Tickets containing keyword testing