lib/testtools/NEWS

   1 testtools NEWS
   2 ++++++++++++++
   3
   4 NEXT
   5 ~~~~
   6
   7 Changes
   8 -------
   9
  10 * addUnexpectedSuccess is translated to addFailure for test results that don't
  11   know about addUnexpectedSuccess.  Further, it fails the entire result for
  12   all testtools TestResults (i.e. wasSuccessful() returns False after
  13   addUnexpectedSuccess has been called). Note that when using a delegating
  14   result such as ThreadsafeForwardingResult, MultiTestResult or
  15   ExtendedToOriginalDecorator then the behaviour of addUnexpectedSuccess is
  16   determined by the delegated to result(s).
  17   (Jonathan Lange, Robert Collins, #654474, #683332)
  18
  19 * startTestRun will reset any errors on the result.  That is, wasSuccessful()
  20   will always return True immediately after startTestRun() is called. This
  21   only applies to delegated test results (ThreadsafeForwardingResult,
  22   MultiTestResult and ExtendedToOriginalDecorator) if the delegated to result
  23   is a testtools test result - we cannot reliably reset the state of unknown
  24   test result class instances. (Jonathan Lange, Robert Collins, #683332)
  25
  26 * Responsibility for running test cleanups has been moved to ``RunTest``.
  27   This change does not affect public APIs and can be safely ignored by test
  28   authors.  (Jonathan Lange, #662647)
  29
  30 Improvements
  31 ------------
  32
  33 * Experimental support for running tests that return Deferreds.
  34   (Jonathan Lange, Martin [gz])
  35
  36 * Provide a per-test decorator, run_test_with, to specify which RunTest
  37   object to use for a given test.  (Jonathan Lange, #657780)
  38
  39 * Fix the runTest parameter of TestCase to actually work, rather than raising
  40   a TypeError.  (Jonathan Lange, #657760)
  41
  42 * New matcher ``EndsWith`` added to complement the existing ``StartsWith``
  43   matcher.  (Jonathan Lange, #669165)
  44
  45 * Non-release snapshots of testtools will now work with buildout.
  46   (Jonathan Lange, #613734)
  47
  48 * Malformed SyntaxErrors no longer blow up the test suite.  (Martin [gz])
  49
  50 * ``MatchesException`` added to the ``testtools.matchers`` module - matches
  51   an exception class and parameters. (Robert Collins)
  52
  53 * New ``KeysEqual`` matcher.  (Jonathan Lange)
  54
  55 * New helpers for conditionally importing modules, ``try_import`` and
  56   ``try_imports``.  (Jonathan Lange)
  57
  58 * ``Raises`` added to the ``testtools.matchers`` module - matches if the
  59   supplied callable raises, and delegates to an optional matcher for validation
  60   of the exception. (Robert Collins)
  61
  62 * ``raises`` added to the ``testtools.matchers`` module - matches if the
  63   supplied callable raises and delegates to ``MatchesException`` to validate
  64   the exception. (Jonathan Lange)
  65
  66 * ``testools.TestCase.useFixture`` has been added to glue with fixtures nicely.
  67   (Robert Collins)
  68
  69 * ``testtools.run`` now supports ``-l`` to list tests rather than executing
  70   them. This is useful for integration with external test analysis/processing
  71   tools like subunit and testrepository. (Robert Collins)
  72
  73 * ``testtools.run`` now supports ``--load-list``, which takes a file containing
  74   test ids, one per line, and intersects those ids with the tests found. This
  75   allows fine grained control of what tests are run even when the tests cannot
  76   be named as objects to import (e.g. due to test parameterisation via
  77   testscenarios). (Robert Collins)
  78
  79 * Update documentation to say how to use testtools.run() on Python 2.4.
  80   (Jonathan Lange, #501174)
  81
  82 * ``text_content`` conveniently converts a Python string to a Content object.
  83   (Jonathan Lange, James Westby)
  84
  85
  86
  87 0.9.7
  88 ~~~~~
  89
  90 Lots of little cleanups in this release; many small improvements to make your
  91 testing life more pleasant.
  92
  93 Improvements
  94 ------------
  95
  96 * Cleanups can raise ``testtools.MultipleExceptions`` if they have multiple
  97   exceptions to report. For instance, a cleanup which is itself responsible for
  98   running several different internal cleanup routines might use this.
  99
 100 * Code duplication between assertEqual and the matcher Equals has been removed.
 101
 102 * In normal circumstances, a TestCase will no longer share details with clones
 103   of itself. (Andrew Bennetts, bug #637725)
 104
 105 * Less exception object cycles are generated (reduces peak memory use between
 106   garbage collection). (Martin [gz])
 107
 108 * New matchers 'DoesNotStartWith' and 'StartsWith' contributed by Canonical
 109   from the Launchpad project. Written by James Westby.
 110
 111 * Timestamps as produced by subunit protocol clients are now forwarded in the
 112   ThreadsafeForwardingResult so correct test durations can be reported.
 113   (Martin [gz], Robert Collins, #625594)
 114
 115 * With unittest from Python 2.7 skipped tests will now show only the reason
 116   rather than a serialisation of all details. (Martin [gz], #625583)
 117
 118 * The testtools release process is now a little better documented and a little
 119   smoother.  (Jonathan Lange, #623483, #623487)
 120
 121
 122 0.9.6
 123 ~~~~~
 124
 125 Nothing major in this release, just enough small bits and pieces to make it
 126 useful enough to upgrade to.
 127
 128 In particular, a serious bug in assertThat() has been fixed, it's easier to
 129 write Matchers, there's a TestCase.patch() method for those inevitable monkey
 130 patches and TestCase.assertEqual gives slightly nicer errors.
 131
 132 Improvements
 133 ------------
 134
 135 * 'TestCase.assertEqual' now formats errors a little more nicely, in the
 136   style of bzrlib.
 137
 138 * Added `PlaceHolder` and `ErrorHolder`, TestCase-like objects that can be
 139   used to add results to a `TestResult`.
 140
 141 * 'Mismatch' now takes optional description and details parameters, so
 142   custom Matchers aren't compelled to make their own subclass.
 143
 144 * jml added a built-in UTF8_TEXT ContentType to make it slightly easier to
 145   add details to test results. See bug #520044.
 146
 147 * Fix a bug in our built-in matchers where assertThat would blow up if any
 148   of them failed. All built-in mismatch objects now provide get_details().
 149
 150 * New 'Is' matcher, which lets you assert that a thing is identical to
 151   another thing.
 152
 153 * New 'LessThan' matcher which lets you assert that a thing is less than
 154   another thing.
 155
 156 * TestCase now has a 'patch()' method to make it easier to monkey-patching
 157   objects in tests. See the manual for more information. Fixes bug #310770.
 158
 159 * MultiTestResult methods now pass back return values from the results it
 160   forwards to.
 161
 162 0.9.5
 163 ~~~~~
 164
 165 This release fixes some obscure traceback formatting issues that probably
 166 weren't affecting you but were certainly breaking our own test suite.
 167
 168 Changes
 169 -------
 170
 171 * Jamu Kakar has updated classes in testtools.matchers and testtools.runtest
 172   to be new-style classes, fixing bug #611273.
 173
 174 Improvements
 175 ------------
 176
 177 * Martin[gz] fixed traceback handling to handle cases where extract_tb returns
 178   a source line of None. Fixes bug #611307.
 179
 180 * Martin[gz] fixed an unicode issue that was causing the tests to fail,
 181   closing bug #604187.
 182
 183 * testtools now handles string exceptions (although why would you want to use
 184   them?) and formats their tracebacks correctly. Thanks to Martin[gz] for
 185   fixing bug #592262.
 186
 187 0.9.4
 188 ~~~~~
 189
 190 This release overhauls the traceback formatting layer to deal with Python 2
 191 line numbers and traceback objects often being local user encoded strings
 192 rather than unicode objects. Test discovery has also been added and Python 3.1
 193 is also supported. Finally, the Mismatch protocol has been extended to let
 194 Matchers collaborate with tests in supplying detailed data about failures.
 195
 196 Changes
 197 -------
 198
 199 * testtools.utils has been renamed to testtools.compat. Importing
 200   testtools.utils will now generate a deprecation warning.
 201
 202 Improvements
 203 ------------
 204
 205 * Add machinery for Python 2 to create unicode tracebacks like those used by
 206   Python 3. This means testtools no longer throws on encountering non-ascii
 207   filenames, source lines, or exception strings when displaying test results.
 208   Largely contributed by Martin[gz] with some tweaks from Robert Collins.
 209
 210 * James Westby has supplied test discovery support using the Python 2.7
 211   TestRunner in testtools.run. This requires the 'discover' module. This
 212   closes bug #250764.
 213
 214 * Python 3.1 is now supported, thanks to Martin[gz] for a partial patch.
 215   This fixes bug #592375.
 216
 217 * TestCase.addCleanup has had its docstring corrected about when cleanups run.
 218
 219 * TestCase.skip is now deprecated in favour of TestCase.skipTest, which is the
 220   Python2.7 spelling for skip. This closes bug #560436.
 221
 222 * Tests work on IronPython patch from Martin[gz] applied.
 223
 224 * Thanks to a patch from James Westby testtools.matchers.Mismatch can now
 225   supply a get_details method, which assertThat will query to provide
 226   additional attachments. This can be used to provide additional detail
 227   about the mismatch that doesn't suite being included in describe(). For
 228   instance, if the match process was complex, a log of the process could be
 229   included, permitting debugging.
 230
 231 * testtools.testresults.real._StringException will now answer __str__ if its
 232   value is unicode by encoding with UTF8, and vice versa to answer __unicode__.
 233   This permits subunit decoded exceptions to contain unicode and still format
 234   correctly.
 235
 236 0.9.3
 237 ~~~~~
 238
 239 More matchers, Python 2.4 support, faster test cloning by switching to copy
 240 rather than deepcopy and better output when exceptions occur in cleanups are
 241 the defining characteristics of this release.
 242
 243 Improvements
 244 ------------
 245
 246 * New matcher "Annotate" that adds a simple string message to another matcher,
 247   much like the option 'message' parameter to standard library assertFoo
 248   methods.
 249
 250 * New matchers "Not" and "MatchesAll". "Not" will invert another matcher, and
 251   "MatchesAll" that needs a successful match for all of its arguments.
 252
 253 * On Python 2.4, where types.FunctionType cannot be deepcopied, testtools will
 254   now monkeypatch copy._deepcopy_dispatch using the same trivial patch that
 255   added such support to Python 2.5. The monkey patch is triggered by the
 256   absence of FunctionType from the dispatch dict rather than a version check.
 257   Bug #498030.
 258
 259 * On windows the test 'test_now_datetime_now' should now work reliably.
 260
 261 * TestCase.getUniqueInteger and TestCase.getUniqueString now have docstrings.
 262
 263 * TestCase.getUniqueString now takes an optional prefix parameter, so you can
 264   now use it in circumstances that forbid strings with '.'s, and such like.
 265
 266 * testtools.testcase.clone_test_with_new_id now uses copy.copy, rather than
 267   copy.deepcopy. Tests that need a deeper copy should use the copy protocol to
 268   control how they are copied. Bug #498869.
 269
 270 * The backtrace test result output tests should now pass on windows and other
 271   systems where os.sep is not '/'.
 272
 273 * When a cleanUp or tearDown exception occurs, it is now accumulated as a new
 274   traceback in the test details, rather than as a separate call to addError /
 275   addException. This makes testtools work better with most TestResult objects
 276   and fixes bug #335816.
 277
 278
 279 0.9.2
 280 ~~~~~
 281
 282 Python 3 support, more matchers and better consistency with Python 2.7 --
 283 you'd think that would be enough for a point release. Well, we here on the
 284 testtools project think that you deserve more.
 285
 286 We've added a hook so that user code can be called just-in-time whenever there
 287 is an exception, and we've also factored out the "run" logic of test cases so
 288 that new outcomes can be added without fiddling with the actual flow of logic.
 289
 290 It might sound like small potatoes, but it's changes like these that will
 291 bring about the end of test frameworks.
 292
 293
 294 Improvements
 295 ------------
 296
 297 * A failure in setUp and tearDown now report as failures not as errors.
 298
 299 * Cleanups now run after tearDown to be consistent with Python 2.7's cleanup
 300   feature.
 301
 302 * ExtendedToOriginalDecorator now passes unrecognised attributes through
 303   to the decorated result object, permitting other extensions to the
 304   TestCase -> TestResult protocol to work.
 305
 306 * It is now possible to trigger code just-in-time after an exception causes
 307   a test outcome such as failure or skip. See the testtools MANUAL or
 308   ``pydoc testtools.TestCase.addOnException``. (bug #469092)
 309
 310 * New matcher Equals which performs a simple equality test.
 311
 312 * New matcher MatchesAny which looks for a match of any of its arguments.
 313
 314 * TestCase no longer breaks if a TestSkipped exception is raised with no
 315   parameters.
 316
 317 * TestCase.run now clones test cases before they are run and runs the clone.
 318   This reduces memory footprint in large test runs - state accumulated on
 319   test objects during their setup and execution gets freed when test case
 320   has finished running unless the TestResult object keeps a reference.
 321   NOTE: As test cloning uses deepcopy, this can potentially interfere if
 322   a test suite has shared state (such as the testscenarios or testresources
 323   projects use).  Use the __deepcopy__ hook to control the copying of such
 324   objects so that the shared references stay shared.
 325
 326 * Testtools now accepts contributions without copyright assignment under some
 327   circumstances. See HACKING for details.
 328
 329 * Testtools now provides a convenient way to run a test suite using the
 330   testtools result object: python -m testtools.run testspec [testspec...].
 331
 332 * Testtools now works on Python 3, thanks to Benjamin Peterson.
 333
 334 * Test execution now uses a separate class, testtools.RunTest to run single
 335   tests. This can be customised and extended in a more consistent fashion than
 336   the previous run method idiom. See pydoc for more information.
 337
 338 * The test doubles that testtools itself uses are now available as part of
 339   the testtools API in testtols.testresult.doubles.
 340
 341 * TracebackContent now sets utf8 as the charset encoding, rather than not
 342   setting one and encoding with the default encoder.
 343
 344 * With python2.7 testtools.TestSkipped will be the unittest.case.SkipTest
 345   exception class making skips compatible with code that manually raises the
 346   standard library exception. (bug #490109)
 347
 348 Changes
 349 -------
 350
 351 * TestCase.getUniqueInteger is now implemented using itertools.count. Thanks
 352   to Benjamin Peterson for the patch. (bug #490111)
 353
 354
 355 0.9.1
 356 ~~~~~
 357
 358 The new matcher API introduced in 0.9.0 had a small flaw where the matchee
 359 would be evaluated twice to get a description of the mismatch. This could lead
 360 to bugs if the act of matching caused side effects to occur in the matchee.
 361 Since having such side effects isn't desirable, we have changed the API now
 362 before it has become widespread.
 363
 364 Changes
 365 -------
 366
 367 * Matcher API changed to avoid evaluating matchee twice. Please consult
 368   the API documentation.
 369
 370 * TestCase.getUniqueString now uses the test id, not the test method name,
 371   which works nicer with parameterised tests.
 372
 373 Improvements
 374 ------------
 375
 376 * Python2.4 is now supported again.
 377
 378
 379 0.9.0
 380 ~~~~~
 381
 382 This release of testtools is perhaps the most interesting and exciting one
 383 it's ever had. We've continued in bringing together the best practices of unit
 384 testing from across a raft of different Python projects, but we've also
 385 extended our mission to incorporating unit testing concepts from other
 386 languages and from our own research, led by Robert Collins.
 387
 388 We now support skipping and expected failures. We'll make sure that you
 389 up-call setUp and tearDown, avoiding unexpected testing weirdnesses. We're
 390 now compatible with Python 2.5, 2.6 and 2.7 unittest library.
 391
 392 All in all, if you are serious about unit testing and want to get the best
 393 thinking from the whole Python community, you should get this release.
 394
 395 Improvements
 396 ------------
 397
 398 * A new TestResult API has been added for attaching details to test outcomes.
 399   This API is currently experimental, but is being prepared with the intent
 400   of becoming an upstream Python API. For more details see pydoc
 401   testtools.TestResult and the TestCase addDetail / getDetails methods.
 402
 403 * assertThat has been added to TestCase. This new assertion supports
 404   a hamcrest-inspired matching protocol. See pydoc testtools.Matcher for
 405   details about writing matchers, and testtools.matchers for the included
 406   matchers. See http://code.google.com/p/hamcrest/.
 407
 408 * Compatible with Python 2.6 and Python 2.7
 409
 410 * Failing to upcall in setUp or tearDown will now cause a test failure.
 411   While the base methods do nothing, failing to upcall is usually a problem
 412   in deeper hierarchies, and checking that the root method is called is a
 413   simple way to catch this common bug.
 414
 415 * New TestResult decorator ExtendedToOriginalDecorator which handles
 416   downgrading extended API calls like addSkip to older result objects that
 417   do not support them. This is used internally to make testtools simpler but
 418   can also be used to simplify other code built on or for use with testtools.
 419
 420 * New TextTestResult supporting the extended APIs that testtools provides.
 421
 422 * Nose will no longer find 'runTest' tests in classes derived from
 423    testtools.testcase.TestCase (bug #312257).
 424
 425 * Supports the Python 2.7/3.1 addUnexpectedSuccess and addExpectedFailure
 426   TestResult methods, with a support function 'knownFailure' to let tests
 427   trigger these outcomes.
 428
 429 * When using the skip feature with TestResult objects that do not support it
 430   a test success will now be reported. Previously an error was reported but
 431   production experience has shown that this is too disruptive for projects that
 432   are using skips: they cannot get a clean run on down-level result objects.