lib/testtools/doc/overview.rst

   1 ======================================
   2 testtools: tasteful testing for Python
   3 ======================================
   4
   5 testtools is a set of extensions to the Python standard library's unit testing
   6 framework. These extensions have been derived from many years of experience
   7 with unit testing in Python and come from many different sources. testtools
   8 supports Python versions all the way back to Python 2.4. The next release of
   9 testtools will change that to support versions that are maintained by the
  10 Python community instead, to allow the use of modern language features within
  11 testtools.
  12
  13 What better way to start than with a contrived code snippet?::
  14
  15   from testtools import TestCase
  16   from testtools.content import Content
  17   from testtools.content_type import UTF8_TEXT
  18   from testtools.matchers import Equals
  19
  20   from myproject import SillySquareServer
  21
  22   class TestSillySquareServer(TestCase):
  23
  24       def setUp(self):
  25           super(TestSillySquare, self).setUp()
  26           self.server = self.useFixture(SillySquareServer())
  27           self.addCleanup(self.attach_log_file)
  28
  29       def attach_log_file(self):
  30           self.addDetail(
  31               'log-file',
  32               Content(UTF8_TEXT
  33                       lambda: open(self.server.logfile, 'r').readlines()))
  34
  35       def test_server_is_cool(self):
  36           self.assertThat(self.server.temperature, Equals("cool"))
  37
  38       def test_square(self):
  39           self.assertThat(self.server.silly_square_of(7), Equals(49))
  40
  41
  42 Why use testtools?
  43 ==================
  44
  45 Better assertion methods
  46 ------------------------
  47
  48 The standard assertion methods that come with unittest aren't as helpful as
  49 they could be, and there aren't quite enough of them.  testtools adds
  50 ``assertIn``, ``assertIs``, ``assertIsInstance`` and their negatives.
  51
  52
  53 Matchers: better than assertion methods
  54 ---------------------------------------
  55
  56 Of course, in any serious project you want to be able to have assertions that
  57 are specific to that project and the particular problem that it is addressing.
  58 Rather than forcing you to define your own assertion methods and maintain your
  59 own inheritance hierarchy of ``TestCase`` classes, testtools lets you write
  60 your own "matchers", custom predicates that can be plugged into a unit test::
  61
  62   def test_response_has_bold(self):
  63      # The response has bold text.
  64      response = self.server.getResponse()
  65      self.assertThat(response, HTMLContains(Tag('bold', 'b')))
  66
  67
  68 More debugging info, when you need it
  69 --------------------------------------
  70
  71 testtools makes it easy to add arbitrary data to your test result.  If you
  72 want to know what's in a log file when a test fails, or what the load was on
  73 the computer when a test started, or what files were open, you can add that
  74 information with ``TestCase.addDetail``, and it will appear in the test
  75 results if that test fails.
  76
  77
  78 Extend unittest, but stay compatible and re-usable
  79 --------------------------------------------------
  80
  81 testtools goes to great lengths to allow serious test authors and test
  82 *framework* authors to do whatever they like with their tests and their
  83 extensions while staying compatible with the standard library's unittest.
  84
  85 testtools has completely parametrized how exceptions raised in tests are
  86 mapped to ``TestResult`` methods and how tests are actually executed (ever
  87 wanted ``tearDown`` to be called regardless of whether ``setUp`` succeeds?)
  88
  89 It also provides many simple but handy utilities, like the ability to clone a
  90 test, a ``MultiTestResult`` object that lets many result objects get the
  91 results from one test suite, adapters to bring legacy ``TestResult`` objects
  92 into our new golden age.
  93
  94
  95 Cross-Python compatibility
  96 --------------------------
  97
  98 testtools gives you the very latest in unit testing technology in a way that
  99 will work with Python 2.6, 2.7 and 3.1.
 100
 101 If you wish to use testtools with Python 2.4 or 2.5, then please use testtools
 102 0.9.15.