Testtools

~~~~~~

Our sister project, `subunit <https://launchpad.net/subunit>`_, was using a
private API that was deleted in the 0.9.13 release. This release restores
that API in order to smooth out the upgrade path.

If you don't use subunit, then this release won't matter very much to you.

~~~~~~

Plenty of new matchers and quite a few critical bug fixes (especially to do
with stack traces from failed assertions). A net win for all.

Changes
-------

* ``MatchesAll`` now takes an ``first_only`` keyword argument that changes how
mismatches are displayed. If you were previously passing matchers to
``MatchesAll`` with keyword arguments, then this change might affect your
test results. (Jonathan Lange)

Improvements
------------

* Actually hide all of the testtools stack for assertion failures. The
previous release promised clean stack, but now we actually provide it.
(Jonathan Lange, 854769)

* ``assertRaises`` now includes the ``repr`` of the callable that failed to raise
properly. (Jonathan Lange, 881052)

* Asynchronous tests no longer hang when run with trial.
(Jonathan Lange, 926189)

* ``Content`` objects now have an ``as_text`` method to convert their contents
to Unicode text. (Jonathan Lange)

* Failed equality assertions now line up. (Jonathan Lange, 879339)

* ``FullStackRunTest`` no longer aborts the test run if a test raises an
error. (Jonathan Lange)

* ``MatchesAll`` and ``MatchesListwise`` both take a ``first_only`` keyword
argument. If True, they will report only on the first mismatch they find,
and not continue looking for other possible mismatches.
(Jonathan Lange)

* New helper, ``Nullary`` that turns callables with arguments into ones that
don't take arguments. (Jonathan Lange)

* New matchers:

* ``DirContains`` matches the contents of a directory.
(Jonathan Lange, James Westby)

* ``DirExists`` matches if a directory exists.
(Jonathan Lange, James Westby)

* ``FileContains`` matches the contents of a file.
(Jonathan Lange, James Westby)

* ``FileExists`` matches if a file exists.
(Jonathan Lange, James Westby)

* ``HasPermissions`` matches the permissions of a file. (Jonathan Lange)

* ``MatchesPredicate`` matches if a predicate is true. (Jonathan Lange)

* ``PathExists`` matches if a path exists. (Jonathan Lange, James Westby)

* ``SamePath`` matches if two paths are the same. (Jonathan Lange)

* ``TarballContains`` matches the contents of a tarball. (Jonathan Lange)

* ``MultiTestResult`` supports the ``tags`` method.
(Graham Binns, Francesco Banconi, 914279)

* ``ThreadsafeForwardingResult`` supports the ``tags`` method.
(Graham Binns, Francesco Banconi, 914279)

* ``ThreadsafeForwardingResult`` no longer includes semaphore acquisition time
in the test duration (for implicitly timed test runs).
(Robert Collins, 914362)

~~~~~~

This is a very big release. We've made huge improvements on three fronts:
1. Test failures are way nicer and easier to read
2. Matchers and ``assertThat`` are much more convenient to use
3. Correct handling of extended unicode characters

We've trimmed off the fat from the stack trace you get when tests fail, we've
cut out the bits of error messages that just didn't help, we've made it easier
to annotate mismatch failures, to compare complex objects and to match raised
exceptions.

Testing code was never this fun.

Changes
-------

* ``AfterPreproccessing`` renamed to ``AfterPreprocessing``, which is a more
correct spelling. Old name preserved for backwards compatibility, but is
now deprecated. Please stop using it.
(Jonathan Lange, 813460)

* ``assertThat`` raises ``MismatchError`` instead of
``TestCase.failureException``. ``MismatchError`` is a subclass of
``AssertionError``, so in most cases this change will not matter. However,
if ``self.failureException`` has been set to a non-default value, then
mismatches will become test errors rather than test failures.

* ``gather_details`` takes two dicts, rather than two detailed objects.
(Jonathan Lange, 801027)

* ``MatchesRegex`` mismatch now says "<value> does not match /<regex>/" rather
than "<regex> did not match <value>". The regular expression contains fewer
backslashes too. (Jonathan Lange, 818079)

* Tests that run with ``AsynchronousDeferredRunTest`` now have the ``reactor``
attribute set to the running reactor. (Jonathan Lange, 720749)

Improvements
------------

* All public matchers are now in ``testtools.matchers.__all__``.
(Jonathan Lange, 784859)

* ``assertThat`` can actually display mismatches and matchers that contain
extended unicode characters. (Jonathan Lange, Martin [gz], 804127)

* ``assertThat`` output is much less verbose, displaying only what the mismatch
tells us to display. Old-style verbose output can be had by passing
``verbose=True`` to assertThat. (Jonathan Lange, 675323, 593190)

* ``assertThat`` accepts a message which will be used to annotate the matcher.
This can be given as a third parameter or as a keyword parameter.
(Robert Collins)

* Automated the Launchpad part of the release process.
(Jonathan Lange, 623486)

* Correctly display non-ASCII unicode output on terminals that claim to have a
unicode encoding. (Martin [gz], 804122)

* ``DocTestMatches`` correctly handles unicode output from examples, rather
than raising an error. (Martin [gz], 764170)

* ``ErrorHolder`` and ``PlaceHolder`` added to docs. (Jonathan Lange, 816597)

* ``ExpectedException`` now matches any exception of the given type by
default, and also allows specifying a ``Matcher`` rather than a mere regular
expression. (Jonathan Lange, 791889)

* ``FixtureSuite`` added, allows test suites to run with a given fixture.
(Jonathan Lange)

* Hide testtools's own stack frames when displaying tracebacks, making it
easier for test authors to focus on their errors.
(Jonathan Lange, Martin [gz], 788974)

* Less boilerplate displayed in test failures and errors.
(Jonathan Lange, 660852)

* ``MatchesException`` now allows you to match exceptions against any matcher,
rather than just regular expressions. (Jonathan Lange, 791889)

* ``MatchesException`` now permits a tuple of types rather than a single type
(when using the type matching mode). (Robert Collins)

* ``MatchesStructure.byEquality`` added to make the common case of matching
many attributes by equality much easier. ``MatchesStructure.byMatcher``
added in case folk want to match by things other than equality.
(Jonathan Lange)

* New convenience assertions, ``assertIsNone`` and ``assertIsNotNone``.
(Christian Kampka)

* New matchers:

* ``AllMatch`` matches many values against a single matcher.
(Jonathan Lange, 615108)

* ``Contains``. (Robert Collins)

* ``GreaterThan``. (Christian Kampka)

* New helper, ``safe_hasattr`` added. (Jonathan Lange)

* ``reraise`` added to ``testtools.compat``. (Jonathan Lange)

~~~~~~

This release brings consistent use of super for better compatibility with
multiple inheritance, fixed Python3 support, improvements in fixture and mather
outputs and a compat helper for testing libraries that deal with bytestrings.

Changes
-------

* ``TestCase`` now uses super to call base ``unittest.TestCase`` constructor,
``setUp`` and ``tearDown``. (Tim Cole, 771508)

* If, when calling ``useFixture`` an error occurs during fixture set up, we
still attempt to gather details from the fixture. (Gavin Panella)


Improvements
------------

* Additional compat helper for ``BytesIO`` for libraries that build on
testtools and are working on Python 3 porting. (Robert Collins)

* Corrected documentation for ``MatchesStructure`` in the test authors
document. (Jonathan Lange)

* ``LessThan`` error message now says something that is logically correct.
(Gavin Panella, 762008)

* Multiple details from a single fixture are now kept separate, rather than
being mooshed together. (Gavin Panella, 788182)

* Python 3 support now back in action. (Martin [gz], 688729)

* ``try_import`` and ``try_imports`` have a callback that is called whenever
they fail to import a module. (Martin Pool)

~~~~~~

The last release of testtools could not be easy_installed. This is considered
severe enough for a re-release.

Improvements
------------

* Include ``doc/`` in the source distribution, making testtools installable
from PyPI again (Tres Seaver, 757439)

~~~~~

Many, many new matchers, vastly expanded documentation, stacks of bug fixes,
better unittest2 integration. If you've ever wanted to try out testtools but
been afraid to do so, this is the release to try.


Changes
-------

* The timestamps generated by ``TestResult`` objects when no timing data has
been received are now datetime-with-timezone, which allows them to be
sensibly serialised and transported. (Robert Collins, 692297)

Improvements
------------

* ``AnnotatedMismatch`` now correctly returns details.
(Jonathan Lange, 724691)

* distutils integration for the testtools test runner. Can now use it for
'python setup.py test'. (Christian Kampka, 693773)

* ``EndsWith`` and ``KeysEqual`` now in testtools.matchers.__all__.
(Jonathan Lange, 692158)

* ``MatchesException`` extended to support a regular expression check against
the str() of a raised exception. (Jonathan Lange)

* ``MultiTestResult`` now forwards the ``time`` API. (Robert Collins, 692294)

* ``MultiTestResult`` now documented in the manual. (Jonathan Lange, 661116)

* New content helpers ``content_from_file``, ``content_from_stream`` and
``attach_file`` make it easier to attach file-like objects to a
test. (Jonathan Lange, Robert Collins, 694126)

* New ``ExpectedException`` context manager to help write tests against things
that are expected to raise exceptions. (Aaron Bentley)

* New matchers:

* ``MatchesListwise`` matches an iterable of matchers against an iterable
of values. (Michael Hudson-Doyle)

* ``MatchesRegex`` matches a string against a regular expression.
(Michael Hudson-Doyle)

* ``MatchesStructure`` matches attributes of an object against given
matchers. (Michael Hudson-Doyle)

* ``AfterPreproccessing`` matches values against a matcher after passing them
through a callable. (Michael Hudson-Doyle)

* ``MatchesSetwise`` matches an iterable of matchers against an iterable of
values, without regard to order. (Michael Hudson-Doyle)

* ``setup.py`` can now build a snapshot when Bazaar is installed but the tree
is not a Bazaar tree. (Jelmer Vernooij)

* Support for running tests using distutils (Christian Kampka, 726539)

* Vastly improved and extended documentation. (Jonathan Lange)

* Use unittest2 exception classes if available. (Jelmer Vernooij)