The branch, master has been updated via 6897be7... testtools: Fix included testtools, for systems that don't have it. from 5f3fcf7... s4-python: Install external included packages only if they're not present on the system.
http://gitweb.samba.org/?p=samba.git;a=shortlog;h=master - Log ----------------------------------------------------------------- commit 6897be747594e385ee032ac1409289ce2d208548 Author: Jelmer Vernooij <jel...@samba.org> Date: Wed Mar 31 04:19:36 2010 +0200 testtools: Fix included testtools, for systems that don't have it. ----------------------------------------------------------------------- Summary of changes: lib/testtools/HACKING | 139 +++++++++++++ lib/testtools/LICENSE | 19 ++ lib/testtools/MANIFEST.in | 9 + lib/testtools/MANUAL | 213 ++++++++++++++++++++ lib/testtools/Makefile | 28 +++ lib/testtools/NEWS | 191 ++++++++++++++++++ lib/testtools/README | 54 +++++ lib/testtools/setup.py | 25 +++ lib/testtools/{ => }/testtools/__init__.py | 0 lib/testtools/{ => }/testtools/content.py | 0 lib/testtools/{ => }/testtools/content_type.py | 0 lib/testtools/{ => }/testtools/matchers.py | 0 lib/testtools/{ => }/testtools/run.py | 0 lib/testtools/{ => }/testtools/runtest.py | 0 lib/testtools/{ => }/testtools/testcase.py | 0 .../{ => }/testtools/testresult/__init__.py | 0 .../{ => }/testtools/testresult/doubles.py | 0 lib/testtools/{ => }/testtools/testresult/real.py | 0 lib/testtools/{ => }/testtools/tests/__init__.py | 0 lib/testtools/{ => }/testtools/tests/helpers.py | 0 .../{ => }/testtools/tests/test_content.py | 0 .../{ => }/testtools/tests/test_content_type.py | 0 .../{ => }/testtools/tests/test_matchers.py | 0 .../{ => }/testtools/tests/test_runtest.py | 0 .../{ => }/testtools/tests/test_testresult.py | 0 .../{ => }/testtools/tests/test_testsuite.py | 0 .../{ => }/testtools/tests/test_testtools.py | 0 lib/testtools/{ => }/testtools/testsuite.py | 0 lib/testtools/{ => }/testtools/utils.py | 0 lib/update-external.sh | 2 +- 30 files changed, 679 insertions(+), 1 deletions(-) create mode 100644 lib/testtools/HACKING create mode 100644 lib/testtools/LICENSE create mode 100644 lib/testtools/MANIFEST.in create mode 100644 lib/testtools/MANUAL create mode 100644 lib/testtools/Makefile create mode 100644 lib/testtools/NEWS create mode 100644 lib/testtools/README create mode 100755 lib/testtools/setup.py rename lib/testtools/{ => }/testtools/__init__.py (100%) rename lib/testtools/{ => }/testtools/content.py (100%) rename lib/testtools/{ => }/testtools/content_type.py (100%) rename lib/testtools/{ => }/testtools/matchers.py (100%) rename lib/testtools/{ => }/testtools/run.py (100%) rename lib/testtools/{ => }/testtools/runtest.py (100%) rename lib/testtools/{ => }/testtools/testcase.py (100%) rename lib/testtools/{ => }/testtools/testresult/__init__.py (100%) rename lib/testtools/{ => }/testtools/testresult/doubles.py (100%) rename lib/testtools/{ => }/testtools/testresult/real.py (100%) rename lib/testtools/{ => }/testtools/tests/__init__.py (100%) rename lib/testtools/{ => }/testtools/tests/helpers.py (100%) rename lib/testtools/{ => }/testtools/tests/test_content.py (100%) rename lib/testtools/{ => }/testtools/tests/test_content_type.py (100%) rename lib/testtools/{ => }/testtools/tests/test_matchers.py (100%) rename lib/testtools/{ => }/testtools/tests/test_runtest.py (100%) rename lib/testtools/{ => }/testtools/tests/test_testresult.py (100%) rename lib/testtools/{ => }/testtools/tests/test_testsuite.py (100%) rename lib/testtools/{ => }/testtools/tests/test_testtools.py (100%) rename lib/testtools/{ => }/testtools/testsuite.py (100%) rename lib/testtools/{ => }/testtools/utils.py (100%) Changeset truncated at 500 lines: diff --git a/lib/testtools/HACKING b/lib/testtools/HACKING new file mode 100644 index 0000000..8fe323c --- /dev/null +++ b/lib/testtools/HACKING @@ -0,0 +1,139 @@ +=================================== +Notes for contributing to testtools +=================================== + +Coding style +------------ + +In general, follow PEP 8 <http://www.python.org/dev/peps/pep-0008/>. + +For consistency with the standard library's ``unittest`` module, method names +are generally ``camelCase``. + +testtools supports Python 2.4 and later, so avoid any 2.5-only features like +the ``with`` statement. + + +Copyright assignment +-------------------- + +Part of testtools raison d'etre is to provide Python with improvements to the +testing code it ships. For that reason we require all contributions (that are +non-trivial) to meet one of the following rules: + + - be inapplicable for inclusion in Python. + - be able to be included in Python without further contact with the + contributor. + - be copyright assigned to Jonathan M. Lange. + +Please pick one of these and specify it when contributing code to testtools. + + +Licensing +--------- + +All code that is not copyright assigned to Jonathan M. Lange (see Copyright +Assignment above) needs to be licensed under the MIT license that testtools +uses, so that testtools can ship it. + + +Testing +------- + +Please write tests for every feature. This project ought to be a model +example of well-tested Python code! + +Take particular care to make sure the *intent* of each test is clear. + +You can run tests with ``make check``, or by running ``./run-tests`` directly. + + +Source layout +------------- + +The top-level directory contains the ``testtools/`` package directory, and +miscellaneous files like README and setup.py. + +The ``testtools/`` directory is the Python package itself. It is separated +into submodules for internal clarity, but all public APIs should be âpromotedâ +into the top-level package by importing them in ``testtools/__init__.py``. +Users of testtools should never import a submodule, they are just +implementation details. + +Tests belong in ``testtools/tests/``. + + +Commiting to trunk +------------------ + +Testtools is maintained using bzr, with its trunk at lp:testtools. This gives +every contributor the ability to commit their work to their own branches. +However permission must be granted to allow contributors to commit to the trunk +branch. + +Commit access to trunk is obtained by joining the testtools-devs Launchpad +team. Membership in this team is contingent on obeying the testtools +contribution policy, including assigning copyright of all the work one creates +and places in trunk to Jonathan Lange. + + +Code Review +----------- + +All code must be reviewed before landing on trunk. The process is to create a +branch in launchpad, and submit it for merging to lp:testtools. It will then +be reviewed before it can be merged to trunk. It will be reviewed by someone: + + * not the author + * a committer (member of the testtools-devs team) + +As a special exception, while the testtools committers team is small and prone +to blocking, a merge request from a committer that has not been reviewed after +24 hours may be merged by that committer. When the team is larger this policy +will be revisited. + +Code reviewers should look for the quality of what is being submitted, +including conformance with this HACKING file. + +Changes which all users should be made aware of should be documented in NEWS. + + +NEWS management +--------------- + +The file NEWS is structured as a sorted list of releases. Each release can have +a free form description and more or more sections with bullet point items. +Sections in use today are 'Improvements' and 'Changes'. To ease merging between +branches, the bullet points are kept alphabetically sorted. The release NEXT is +permanently present at the top of the list. + + +Release tasks +------------- + +In no particular order: + +* Choose a version number. + +* Ensure __init__ has that version. + +* Add a version number to NEWS immediately below NEXT. + +* Possibly write a blurb into NEWS. + +* Replace any additional references to NEXT with the version being released. + +* Create a source distribution and upload to pypi ('make release'). + +* Upload to Launchpad as well. + +* If a new series has been created (e.g. 0.10.0), make the series on Launchpad. + +* Merge or push the release branch to trunk. + +* Make a new milestone for the *next release*. We don't really know how we want + to handle these yet, so this is a suggestion not actual practice: + + * during release we rename NEXT to $version. + + * we call new milestones NEXT. diff --git a/lib/testtools/LICENSE b/lib/testtools/LICENSE new file mode 100644 index 0000000..bdc733f --- /dev/null +++ b/lib/testtools/LICENSE @@ -0,0 +1,19 @@ +Copyright (c) 2008 Jonathan M. Lange <j...@mumak.net> and the testtools authors. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/lib/testtools/MANIFEST.in b/lib/testtools/MANIFEST.in new file mode 100644 index 0000000..3296ee4 --- /dev/null +++ b/lib/testtools/MANIFEST.in @@ -0,0 +1,9 @@ +include LICENSE +include HACKING +include Makefile +include MANIFEST.in +include MANUAL +include NEWS +include README +include run-tests +include .bzrignore diff --git a/lib/testtools/MANUAL b/lib/testtools/MANUAL new file mode 100644 index 0000000..a040c28 --- /dev/null +++ b/lib/testtools/MANUAL @@ -0,0 +1,213 @@ +====== +Manual +====== + +Introduction +------------ + +This document provides overview of the features provided by testtools. Refer +to the API docs (i.e. docstrings) for full details on a particular feature. + +Extensions to TestCase +---------------------- + +Controlling test execution +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Testtools supports two ways to control how tests are executed. The simplest +is to add a new exception to self.exception_handlers:: + + >>> self.exception_handlers.insert(-1, (ExceptionClass, handler)). + +Having done this, if any of setUp, tearDown, or the test method raise +ExceptionClass, handler will be called with the test case, test result and the +raised exception. + +Secondly, by overriding __init__ to pass in runTest=RunTestFactory the whole +execution of the test can be altered. The default is testtools.runtest.RunTest +and calls case._run_setup, case._run_test_method and finally +case._run_teardown. Other methods to control what RunTest is used may be +added in future. + + +TestCase.addCleanup +~~~~~~~~~~~~~~~~~~~ + +addCleanup is a robust way to arrange for a cleanup function to be called +before tearDown. This is a powerful and simple alternative to putting cleanup +logic in a try/finally block or tearDown method. e.g.:: + + def test_foo(self): + foo.lock() + self.addCleanup(foo.unlock) + ... + + +TestCase.addOnException +~~~~~~~~~~~~~~~~~~~~~~~ + +addOnException adds an exception handler that will be called from the test +framework when it detects an exception from your test code. The handler is +given the exc_info for the exception, and can use this opportunity to attach +more data (via the addDetails API) and potentially other uses. + + +TestCase.skip +~~~~~~~~~~~~~ + +``skip`` is a simple way to have a test stop running and be reported as a +skipped test, rather than a success/error/failure. This is an alternative to +convoluted logic during test loading, permitting later and more localized +decisions about the appropriateness of running a test. Many reasons exist to +skip a test - for instance when a dependency is missing, or if the test is +expensive and should not be run while on laptop battery power, or if the test +is testing an incomplete feature (this is sometimes called a TODO). Using this +feature when running your test suite with a TestResult object that is missing +the ``addSkip`` method will result in the ``addError`` method being invoked +instead. + + +New assertion methods +~~~~~~~~~~~~~~~~~~~~~ + +testtools adds several assertion methods: + + * assertIn + * assertNotIn + * assertIs + * assertIsNot + * assertIsInstance + * assertThat + + +Improved assertRaises +~~~~~~~~~~~~~~~~~~~~~ + +TestCase.assertRaises returns the caught exception. This is useful for +asserting more things about the exception than just the type:: + + error = self.assertRaises(UnauthorisedError, thing.frobnicate) + self.assertEqual('bob', error.username) + self.assertEqual('User bob cannot frobnicate', str(error)) + + +TestCase.assertThat +~~~~~~~~~~~~~~~~~~~ + +assertThat is a clean way to write complex assertions without tying them to +the TestCase inheritance hierarchy (and thus making them easier to reuse). + +assertThat takes an object to be matched, and a matcher, and fails if the +matcher does not match the matchee. + +See pydoc testtools.Matcher for the protocol that matchers need to implement. + +testtools includes some matchers in testtools.matchers. +python -c 'import testtools.matchers; print testtools.matchers.__all__' will +list those matchers. + +An example using the DocTestMatches matcher which uses doctests example +matching logic:: + + def test_foo(self): + self.assertThat([1,2,3,4], DocTestMatches('[1, 2, 3, 4]')) + + +Creation methods +~~~~~~~~~~~~~~~~ + +testtools.TestCase implements creation methods called ``getUniqueString`` and +``getUniqueInteger``. See pages 419-423 of *xUnit Test Patterns* by Meszaros +for a detailed discussion of creation methods. + + +Test renaming +~~~~~~~~~~~~~ + +``testtools.clone_test_with_new_id`` is a function to copy a test case +instance to one with a new name. This is helpful for implementing test +parameterization. + + +Extensions to TestResult +------------------------ + +TestResult.addSkip +~~~~~~~~~~~~~~~~~~ + +This method is called on result objects when a test skips. The +``testtools.TestResult`` class records skips in its ``skip_reasons`` instance +dict. The can be reported on in much the same way as succesful tests. + + +TestResult.time +~~~~~~~~~~~~~~~ + +This method controls the time used by a TestResult, permitting accurate +timing of test results gathered on different machines or in different threads. +See pydoc testtools.TestResult.time for more details. + + +ThreadsafeForwardingResult +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A TestResult which forwards activity to another test result, but synchronises +on a semaphore to ensure that all the activity for a single test arrives in a +batch. This allows simple TestResults which do not expect concurrent test +reporting to be fed the activity from multiple test threads, or processes. + +Note that when you provide multiple errors for a single test, the target sees +each error as a distinct complete test. + + +TextTestResult +~~~~~~~~~~~~~~ + +A TestResult that provides a text UI very similar to the Python standard +library UI. Key differences are that its supports the extended outcomes and +details API, and is completely encapsulated into the result object, permitting +it to be used without a 'TestRunner' object. Not all the Python 2.7 outcomes +are displayed (yet). It is also a 'quiet' result with no dots or verbose mode. +These limitations will be corrected soon. + + +Test Doubles +~~~~~~~~~~~~ + +In testtools.testresult.doubles there are three test doubles that testtools +uses for its own testing: Python26TestResult, Python27TestResult, +ExtendedTestResult. These TestResult objects implement a single variation of +the TestResult API each, and log activity to a list self._events. These are +made available for the convenience of people writing their own extensions. + + +startTestRun and stopTestRun +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Python 2.7 added hooks 'startTestRun' and 'stopTestRun' which are called +before and after the entire test run. 'stopTestRun' is particularly useful for +test results that wish to produce summary output. + +testtools.TestResult provides empty startTestRun and stopTestRun methods, and +the default testtools runner will call these methods appropriately. + + +Extensions to TestSuite +----------------------- + +ConcurrentTestSuite +~~~~~~~~~~~~~~~~~~~ + +A TestSuite for parallel testing. This is used in conjuction with a helper that +runs a single suite in some parallel fashion (for instance, forking, handing +off to a subprocess, to a compute cloud, or simple threads). +ConcurrentTestSuite uses the helper to get a number of separate runnable +objects with a run(result), runs them all in threads using the +ThreadsafeForwardingResult to coalesce their activity. + + +Running tests +------------- + +Testtools provides a convenient way to run a test suite using the testtools +result object: python -m testtools.run testspec [testspec...]. diff --git a/lib/testtools/Makefile b/lib/testtools/Makefile new file mode 100644 index 0000000..5e232e3 --- /dev/null +++ b/lib/testtools/Makefile @@ -0,0 +1,28 @@ +# See README for copyright and licensing details. + +PYTHON=python +SOURCES=$(shell find testtools -name "*.py") + +check: + PYTHONPATH=$(PWD) $(PYTHON) -m testtools.run testtools.tests.test_suite + +TAGS: ${SOURCES} + ctags -e -R testtools/ + +tags: ${SOURCES} + ctags -R testtools/ + +clean: + rm -f TAGS tags + find testtools -name "*.pyc" -exec rm '{}' \; + +release: + ./setup.py sdist upload --sign + +apidocs: + pydoctor --make-html --add-package testtools \ + --docformat=restructuredtext --project-name=testtools \ + --project-url=https://launchpad.net/testtools + + +.PHONY: check clean release apidocs diff --git a/lib/testtools/NEWS b/lib/testtools/NEWS new file mode 100644 index 0000000..90d7fc4 --- /dev/null +++ b/lib/testtools/NEWS @@ -0,0 +1,191 @@ +testtools NEWS +++++++++++++++ + +NEXT +~~~~ + +Improvements +------------ + +* New matcher "Annotate" that adds a simple string message to another matcher, + much like the option 'message' parameter to standard library assertFoo + methods. + +* New matchers "Not" and "MatchesAll". "Not" will invert another matcher, and + "MatchesAll" that needs a successful match for all of its arguments. + +* On Python 2.4, where types.FunctionType cannot be deepcopied, testtools will + now monkeypatch copy._deepcopy_dispatch using the same trivial patch that + added such support to Python 2.5. The monkey patch is triggered by the + absence of FunctionType from the dispatch dict rather than a version check. + Bug #498030. + +* On windows the test 'test_now_datetime_now' should now work reliably. + +* TestCase.getUniqueInteger and TestCase.getUniqueString now have docstrings. + +* TestCase.getUniqueString now takes an optional prefix parameter, so you can + now use it in circumstances that forbid strings with '.'s, and such like. + +* testtools.testcase.clone_test_with_new_id now uses copy.copy, rather than + copy.deepcopy. Tests that need a deeper copy should use the copy protocol to + control how they are copied. Bug #498869. + +* The backtrace test result output tests should now pass on windows and other + systems where os.sep is not '/'. + + +0.9.2 +~~~~~ + +Python 3 support, more matchers and better consistency with Python 2.7 -- +you'd think that would be enough for a point release. Well, we here on the +testtools project think that you deserve more. + +We've added a hook so that user code can be called just-in-time whenever there +is an exception, and we've also factored out the "run" logic of test cases so +that new outcomes can be added without fiddling with the actual flow of logic. + +It might sound like small potatoes, but it's changes like these that will +bring about the end of test frameworks. + + +Improvements +------------ + +* A failure in setUp and tearDown now report as failures not as errors. -- Samba Shared Repository