Each unit test tests one bit of functionality in the software. Unit tests are entirely automated and complete quickly. Unit tests for the entire system are gathered into one test suite, and may all be run in a single batch. The result of a unit test is simple: either it passes, or it doesn't. All this means you can test the entire system at any time without inconvenience, and quickly see what passes and what fails.
The Twisted development team adheres to the practice of Extreme Programming (XP), and the usage of unit tests is a cornerstone XP practice. Unit tests are a tool to give you increased confidence. You changed an algorithm -- did you break something? Run the unit tests. If a test fails, you know where to look, because each test covers only a small amount of code, and you know it has something to do with the changes you just made. If all the tests pass, you're good to go, and you don't need to second-guess yourself or worry that you just accidently broke someone else's program.
You don't have to write a test for every single method you write, only production methods that could possibly break.
-- Kent Beck, Extreme Programming Explained, p. 58.
$ Twisted/admin/runtests
You'll find that having something like this in your emacs init files is quite handy:
(defun runtests () (interactive) (compile "python /somepath/Twisted/admin/runtests")) (global-set-key [(alt t)] 'runtests)
Always always always be sure all the tests pass before committing any code. If someone else checks out code at the start of a development session and finds failing tests, they will not be happy and may decide to hunt you down.
Since this is a geographically dispersed team, the person who can help you get your code working probably isn't in the room with you. You may want to share your work in progress over the network, but you want to leave the main CVS tree in good working order. So use a branch, and merge your changes back in only after your problem is solved and all the unit tests pass again.
Please don't add new modules to Twisted without adding tests for them too. Otherwise we could change something which breaks your module and not find out until later, making it hard to know exactly what the change that broke it was, or until after a release, and nobody wants broken code in a release.
Tests go in Twisted/twisted/test/, and are named test_foo.py
,
where foo
is the name of the module or package being tested.
Extensive documentation on using the PyUnit framework for writing
unit tests can be found in the links
section below.
One deviation from the standard PyUnit documentation: To ensure
that any variations in test results are due to variations in the
code or environment and not the test process itself, Twisted ships
with its own, compatible, testing framework. That just
means that when you import the unittest module, you will from twisted.trial import unittest
instead of the
standard import unittest
.
As long as you have followed the module naming and placement
conventions, runtests
will be smart
enough to pick up any new tests you write.
Please add a test-case-name
tag to the source file that is
covered by your new test. This is a comment at the beginning of the file
which looks like one of the following:
# -*- test-case-name: twisted.test.test_defer -*-
or
#!/usr/bin/python # -*- test-case-name: twisted.test.test_defer -*-
This format is understood by emacs to mark File Variables
. The
intention is to accept test-case-name
anywhere emacs would on
the first or second line of the file (but not in the File
Variables:
block that emacs accepts at the end of the file). If you
need to define other emacs file variables, you can either put them in the
File Variables:
block or use a semicolon-separated list of
variable definitions:
# -*- test-case-name: twisted.test.test_defer; fill-column: 75; -*-
If the code is exercised by multiple test cases, those may be marked by using a comma-separated list of tests, as follows: (NOTE: not all tools can handle this yet.. trial --testmodule does, though)
# -*- test-case-name: twisted.test.test_defer,twisted.test.test_tcp -*-
The test-case-name
tag will allow trial
--testmodule twisted/dir/myfile.py
to determine which test cases need
to be run to exercise the code in myfile.py
. Several tools (as
well as twisted-dev.el
's F9 command) use this to automatically
run the right tests.
unittest
module documentation, in the Python Library
Reference.