testtools: Import latest upstream.
[nivanova/samba-autobuild/.git] / lib / testtools / NEWS
1 testtools NEWS
2 ++++++++++++++
3
4 NEXT
5 ~~~~
6
7 0.9.6
8 ~~~~~
9
10 Nothing major in this release, just enough small bits and pieces to make it
11 useful enough to upgrade to.
12
13 In particular, a serious bug in assertThat() has been fixed, it's easier to
14 write Matchers, there's a TestCase.patch() method for those inevitable monkey
15 patches and TestCase.assertEqual gives slightly nicer errors.
16
17 Improvements
18 ------------
19
20  * 'TestCase.assertEqual' now formats errors a little more nicely, in the
21    style of bzrlib.
22
23  * Added `PlaceHolder` and `ErrorHolder`, TestCase-like objects that can be
24    used to add results to a `TestResult`.
25
26  * 'Mismatch' now takes optional description and details parameters, so
27    custom Matchers aren't compelled to make their own subclass.
28
29  * jml added a built-in UTF8_TEXT ContentType to make it slightly easier to
30    add details to test results. See bug #520044.
31
32  * Fix a bug in our built-in matchers where assertThat would blow up if any
33    of them failed. All built-in mismatch objects now provide get_details().
34
35  * New 'Is' matcher, which lets you assert that a thing is identical to
36    another thing.
37
38  * New 'LessThan' matcher which lets you assert that a thing is less than
39    another thing.
40
41  * TestCase now has a 'patch()' method to make it easier to monkey-patching
42    objects in tests. See the manual for more information. Fixes bug #310770.
43
44  * MultiTestResult methods now pass back return values from the results it
45    forwards to.
46
47 0.9.5
48 ~~~~~
49
50 This release fixes some obscure traceback formatting issues that probably
51 weren't affecting you but were certainly breaking our own test suite.
52
53 Changes
54 -------
55
56 * Jamu Kakar has updated classes in testtools.matchers and testtools.runtest
57   to be new-style classes, fixing bug #611273.
58
59 Improvements
60 ------------
61
62 * Martin[gz] fixed traceback handling to handle cases where extract_tb returns
63   a source line of None. Fixes bug #611307.
64
65 * Martin[gz] fixed an unicode issue that was causing the tests to fail,
66   closing bug #604187.
67
68 * testtools now handles string exceptions (although why would you want to use
69   them?) and formats their tracebacks correctly. Thanks to Martin[gz] for
70   fixing bug #592262.
71
72 0.9.4
73 ~~~~~
74
75 This release overhauls the traceback formatting layer to deal with Python 2
76 line numbers and traceback objects often being local user encoded strings
77 rather than unicode objects. Test discovery has also been added and Python 3.1
78 is also supported. Finally, the Mismatch protocol has been extended to let
79 Matchers collaborate with tests in supplying detailed data about failures.
80
81 Changes
82 -------
83
84 * testtools.utils has been renamed to testtools.compat. Importing
85   testtools.utils will now generate a deprecation warning.
86
87 Improvements
88 ------------
89
90 * Add machinery for Python 2 to create unicode tracebacks like those used by
91   Python 3. This means testtools no longer throws on encountering non-ascii
92   filenames, source lines, or exception strings when displaying test results.
93   Largely contributed by Martin[gz] with some tweaks from Robert Collins.
94
95 * James Westby has supplied test discovery support using the Python 2.7
96   TestRunner in testtools.run. This requires the 'discover' module. This
97   closes bug #250764.
98
99 * Python 3.1 is now supported, thanks to Martin[gz] for a partial patch.
100   This fixes bug #592375.
101
102 * TestCase.addCleanup has had its docstring corrected about when cleanups run.
103
104 * TestCase.skip is now deprecated in favour of TestCase.skipTest, which is the
105   Python2.7 spelling for skip. This closes bug #560436.
106
107 * Tests work on IronPython patch from Martin[gz] applied.
108
109 * Thanks to a patch from James Westby testtools.matchers.Mismatch can now
110   supply a get_details method, which assertThat will query to provide
111   additional attachments. This can be used to provide additional detail
112   about the mismatch that doesn't suite being included in describe(). For
113   instance, if the match process was complex, a log of the process could be
114   included, permitting debugging.
115
116 * testtools.testresults.real._StringException will now answer __str__ if its
117   value is unicode by encoding with UTF8, and vice versa to answer __unicode__.
118   This permits subunit decoded exceptions to contain unicode and still format
119   correctly.
120
121 0.9.3
122 ~~~~~
123
124 More matchers, Python 2.4 support, faster test cloning by switching to copy
125 rather than deepcopy and better output when exceptions occur in cleanups are
126 the defining characteristics of this release.
127
128 Improvements
129 ------------
130
131 * New matcher "Annotate" that adds a simple string message to another matcher,
132   much like the option 'message' parameter to standard library assertFoo
133   methods.
134
135 * New matchers "Not" and "MatchesAll". "Not" will invert another matcher, and
136   "MatchesAll" that needs a successful match for all of its arguments.
137
138 * On Python 2.4, where types.FunctionType cannot be deepcopied, testtools will
139   now monkeypatch copy._deepcopy_dispatch using the same trivial patch that
140   added such support to Python 2.5. The monkey patch is triggered by the
141   absence of FunctionType from the dispatch dict rather than a version check.
142   Bug #498030.
143
144 * On windows the test 'test_now_datetime_now' should now work reliably.
145
146 * TestCase.getUniqueInteger and TestCase.getUniqueString now have docstrings.
147
148 * TestCase.getUniqueString now takes an optional prefix parameter, so you can
149   now use it in circumstances that forbid strings with '.'s, and such like.
150
151 * testtools.testcase.clone_test_with_new_id now uses copy.copy, rather than
152   copy.deepcopy. Tests that need a deeper copy should use the copy protocol to
153   control how they are copied. Bug #498869.
154
155 * The backtrace test result output tests should now pass on windows and other
156   systems where os.sep is not '/'.
157
158 * When a cleanUp or tearDown exception occurs, it is now accumulated as a new
159   traceback in the test details, rather than as a separate call to addError / 
160   addException. This makes testtools work better with most TestResult objects
161   and fixes bug #335816.
162
163
164 0.9.2
165 ~~~~~
166
167 Python 3 support, more matchers and better consistency with Python 2.7 --
168 you'd think that would be enough for a point release. Well, we here on the
169 testtools project think that you deserve more.
170
171 We've added a hook so that user code can be called just-in-time whenever there
172 is an exception, and we've also factored out the "run" logic of test cases so
173 that new outcomes can be added without fiddling with the actual flow of logic.
174
175 It might sound like small potatoes, but it's changes like these that will
176 bring about the end of test frameworks.
177
178
179 Improvements
180 ------------
181
182 * A failure in setUp and tearDown now report as failures not as errors.
183
184 * Cleanups now run after tearDown to be consistent with Python 2.7's cleanup
185   feature.
186
187 * ExtendedToOriginalDecorator now passes unrecognised attributes through
188   to the decorated result object, permitting other extensions to the
189   TestCase -> TestResult protocol to work.
190
191 * It is now possible to trigger code just-in-time after an exception causes
192   a test outcome such as failure or skip. See the testtools MANUAL or
193   ``pydoc testtools.TestCase.addOnException``. (bug #469092)
194
195 * New matcher Equals which performs a simple equality test.
196
197 * New matcher MatchesAny which looks for a match of any of its arguments.
198
199 * TestCase no longer breaks if a TestSkipped exception is raised with no
200   parameters.
201
202 * TestCase.run now clones test cases before they are run and runs the clone.
203   This reduces memory footprint in large test runs - state accumulated on
204   test objects during their setup and execution gets freed when test case
205   has finished running unless the TestResult object keeps a reference.
206   NOTE: As test cloning uses deepcopy, this can potentially interfere if
207   a test suite has shared state (such as the testscenarios or testresources
208   projects use).  Use the __deepcopy__ hook to control the copying of such
209   objects so that the shared references stay shared.
210
211 * Testtools now accepts contributions without copyright assignment under some
212   circumstances. See HACKING for details.
213
214 * Testtools now provides a convenient way to run a test suite using the
215   testtools result object: python -m testtools.run testspec [testspec...].
216
217 * Testtools now works on Python 3, thanks to Benjamin Peterson.
218
219 * Test execution now uses a separate class, testtools.RunTest to run single
220   tests. This can be customised and extended in a more consistent fashion than
221   the previous run method idiom. See pydoc for more information.
222
223 * The test doubles that testtools itself uses are now available as part of
224   the testtools API in testtols.testresult.doubles.
225
226 * TracebackContent now sets utf8 as the charset encoding, rather than not
227   setting one and encoding with the default encoder.
228
229 * With python2.7 testtools.TestSkipped will be the unittest.case.SkipTest
230   exception class making skips compatible with code that manually raises the
231   standard library exception. (bug #490109)
232
233 Changes
234 -------
235
236 * TestCase.getUniqueInteger is now implemented using itertools.count. Thanks
237   to Benjamin Peterson for the patch. (bug #490111)
238
239
240 0.9.1
241 ~~~~~
242
243 The new matcher API introduced in 0.9.0 had a small flaw where the matchee
244 would be evaluated twice to get a description of the mismatch. This could lead
245 to bugs if the act of matching caused side effects to occur in the matchee.
246 Since having such side effects isn't desirable, we have changed the API now
247 before it has become widespread.
248
249 Changes
250 -------
251
252 * Matcher API changed to avoid evaluating matchee twice. Please consult
253   the API documentation.
254
255 * TestCase.getUniqueString now uses the test id, not the test method name,
256   which works nicer with parameterised tests.
257
258 Improvements
259 ------------
260
261 * Python2.4 is now supported again.
262
263
264 0.9.0
265 ~~~~~
266
267 This release of testtools is perhaps the most interesting and exciting one
268 it's ever had. We've continued in bringing together the best practices of unit
269 testing from across a raft of different Python projects, but we've also
270 extended our mission to incorporating unit testing concepts from other
271 languages and from our own research, led by Robert Collins.
272
273 We now support skipping and expected failures. We'll make sure that you
274 up-call setUp and tearDown, avoiding unexpected testing weirdnesses. We're
275 now compatible with Python 2.5, 2.6 and 2.7 unittest library.
276
277 All in all, if you are serious about unit testing and want to get the best
278 thinking from the whole Python community, you should get this release.
279
280 Improvements
281 ------------
282
283 * A new TestResult API has been added for attaching details to test outcomes.
284   This API is currently experimental, but is being prepared with the intent
285   of becoming an upstream Python API. For more details see pydoc
286   testtools.TestResult and the TestCase addDetail / getDetails methods.
287
288 * assertThat has been added to TestCase. This new assertion supports
289   a hamcrest-inspired matching protocol. See pydoc testtools.Matcher for
290   details about writing matchers, and testtools.matchers for the included
291   matchers. See http://code.google.com/p/hamcrest/.
292
293 * Compatible with Python 2.6 and Python 2.7
294
295 * Failing to upcall in setUp or tearDown will now cause a test failure.
296   While the base methods do nothing, failing to upcall is usually a problem
297   in deeper hierarchies, and checking that the root method is called is a
298   simple way to catch this common bug.
299
300 * New TestResult decorator ExtendedToOriginalDecorator which handles
301   downgrading extended API calls like addSkip to older result objects that
302   do not support them. This is used internally to make testtools simpler but
303   can also be used to simplify other code built on or for use with testtools.
304
305 * New TextTestResult supporting the extended APIs that testtools provides.
306
307 * Nose will no longer find 'runTest' tests in classes derived from
308    testtools.testcase.TestCase (bug #312257).
309
310 * Supports the Python 2.7/3.1 addUnexpectedSuccess and addExpectedFailure
311   TestResult methods, with a support function 'knownFailure' to let tests
312   trigger these outcomes.
313
314 * When using the skip feature with TestResult objects that do not support it
315   a test success will now be reported. Previously an error was reported but
316   production experience has shown that this is too disruptive for projects that
317   are using skips: they cannot get a clean run on down-level result objects.